# `Beaver.MLIR.ActionTracing`

Exposes MLIR Action Tracing through Elixir telemetry.

MLIR dispatches actions — pass execution, rewrite-pattern application,
tiling, and other compiler steps — through an action handler registered on
an `MLIR.Context`. This module attaches a context-scoped observer that
records `before`/`after` action events, hands them to the BEAM as structured
telemetry, and can skip or limit actions by tag.

Events are drained explicitly (or on a timer) and emitted as telemetry:

- `[:beaver, :mlir, :compilation, :action, :start]` — before an action runs
- `[:beaver, :mlir, :compilation, :action, :stop]` — after an action runs

Each event carries `tag`, `description`, `depth`, and `ir_units` metadata.
The `stop` event carries a `duration` measurement computed from the paired
`start` event.

Native observers run on MLIR worker threads and never invoke BEAM APIs
directly; events are queued on the native side and drained by the BEAM.

## Options

- `:tags` — only observe actions whose tag is in this list. Defaults to all.
- `:locations` — only observe actions whose context IR units carry a
  matching source location substring. Defaults to all.
- `:skip` — map of tag to a non-negative skip count; the first N occurrences
  of that tag are skipped (not executed).
- `:limit` — map of tag to a non-negative execution limit; further
  occurrences are skipped once the limit is reached.
- `:drain_interval_ms` — when set, a periodic drainer emits telemetry
  automatically. Defaults to `nil` (manual draining).
- `:telemetry` — optional `(event, measurements, metadata) -> term` callback
  used instead of `:telemetry` events (see `Beaver.MLIR.Telemetry`).
- `:metadata` — metadata merged into every emitted action event. Event-owned
  fields take precedence. This can correlate actions with a higher-level
  operation such as one Transform autotuning candidate.

# `attach`

```elixir
@spec attach(
  Beaver.MLIR.Context.t(),
  keyword()
) :: Beaver.MLIR.ActionTracing.Session.t()
```

Attaches an action tracing session to `context`.

Returns a `Session` holding the native session resource. Call `drain/1`
periodically (or pass `drain_interval_ms`) to receive events, and
`detach/1` when done. The session is detached automatically when the context
is destroyed.

# `child_spec`

Returns a specification to start this module under a supervisor.

See `Supervisor`.

# `detach`

```elixir
@spec detach(Beaver.MLIR.ActionTracing.Session.t() | pid()) :: :ok
```

Detaches and releases the tracing session.

# `drain`

```elixir
@spec drain(Beaver.MLIR.ActionTracing.Session.t() | pid()) :: [map()]
```

Drains pending action events from the session and emits telemetry.
Returns the list of decoded events.