# `Tinkex.Regularizer.Telemetry`
[🔗](https://github.com/North-Shore-AI/tinkex/blob/v0.4.0/lib/tinkex/regularizer/telemetry.ex#L1)

Telemetry helpers for regularizer events.

This module provides convenience functions for attaching telemetry handlers
to regularizer-specific events.

## Events

The following events are emitted by the regularizer pipeline:

### Custom Loss Events

- `[:tinkex, :custom_loss, :start]` - Emitted when custom loss computation begins
  - Measurements: `%{system_time: integer}`
  - Metadata: `%{regularizer_count: integer, track_grad_norms: boolean}`

- `[:tinkex, :custom_loss, :stop]` - Emitted when custom loss computation completes
  - Measurements: `%{duration: integer, loss_total: float, regularizer_total: float}`
  - Metadata: `%{regularizer_count: integer}`

- `[:tinkex, :custom_loss, :exception]` - Emitted on failure
  - Measurements: `%{duration: integer}`
  - Metadata: `%{reason: term}`

### Per-Regularizer Events

- `[:tinkex, :regularizer, :compute, :start]` - Before each regularizer
  - Measurements: `%{system_time: integer}`
  - Metadata: `%{regularizer_name: String.t(), weight: float, async: boolean}`

- `[:tinkex, :regularizer, :compute, :stop]` - After each regularizer
  - Measurements: `%{duration: integer, value: float, contribution: float, grad_norm: float | nil}`
  - Metadata: `%{regularizer_name: String.t(), weight: float, async: boolean}`

- `[:tinkex, :regularizer, :compute, :exception]` - On regularizer failure
  - Measurements: `%{duration: integer}`
  - Metadata: `%{regularizer_name: String.t(), weight: float, reason: term}`

## Example Usage

    # Attach a logger to all regularizer events
    handler_id = Tinkex.Regularizer.Telemetry.attach_logger()

    # Attach with options
    handler_id = Tinkex.Regularizer.Telemetry.attach_logger(
      handler_id: "my-app-regularizer-logger",
      level: :debug
    )

    # Detach when done
    Tinkex.Regularizer.Telemetry.detach(handler_id)

## Custom Handlers

    :telemetry.attach(
      "my-handler",
      [:tinkex, :regularizer, :compute, :stop],
      fn event, measurements, metadata, config ->
        # Custom handling
        IO.inspect({event, measurements, metadata})
      end,
      %{}
    )

# `attach_logger`

```elixir
@spec attach_logger(keyword()) :: term()
```

Attach a logger that prints regularizer telemetry events to the console.

## Options

- `:handler_id` - Custom handler ID (default: auto-generated)
- `:level` - Log level (default: `:info`)

## Returns

The handler ID for later detachment.

## Examples

    handler_id = Tinkex.Regularizer.Telemetry.attach_logger()

    handler_id = Tinkex.Regularizer.Telemetry.attach_logger(
      handler_id: "my-regularizer-logger",
      level: :debug
    )

# `detach`

```elixir
@spec detach(term()) :: :ok | {:error, :not_found}
```

Detach a previously attached handler.

# `events`

```elixir
@spec events() :: [[atom()]]
```

Returns the list of regularizer telemetry events.

Useful for programmatic attachment of handlers.

---

*Consult [api-reference.md](api-reference.md) for complete listing*