# `ReqAI.Telemetry`
[🔗](https://github.com/benjreinhart/req_ai/blob/v0.0.1-rc.3/lib/req_ai/telemetry.ex#L1)

Attribute extraction callbacks for telemetry events.

`ReqAI.generate/2` emits `[:req_ai, :generate, :start]`,
`[:req_ai, :generate, :stop]`, and `[:req_ai, :generate, :exception]` events.
`ReqAI.stream/4` emits the same lifecycle events under `[:req_ai, :stream]`.
Attach handlers with `:telemetry` to observe calls.

The provider module is the default attribute extractor and may implement any
of this module's optional callbacks. Pass `telemetry: MyApp.Telemetry` to
`ReqAI.Provider.new/2` to select another extractor, or `telemetry: false` to
disable emission. A `:telemetry_metadata` map adds static tags to events:

    ReqAI.Provider.new(ReqAI.Provider.OpenAI,
      telemetry_metadata: %{feature: :summarizer}
    )

Metadata uses simple atom keys: `:operation`, `:provider`, `:model`,
`:response_id`, `:response_model`, `:finish_reasons`, `:input_tokens`, and
`:output_tokens`. Optional usage breakdowns are `:cache_read_input_tokens`,
`:cache_write_input_tokens`, and `:reasoning_output_tokens`. Input totals
include cache reads/writes; output totals include reasoning. Breakdowns are
subsets of these totals. Missing values are omitted, not recorded as zero.
Extraction coverage varies by provider and request mode; attributes are
included when available. Streaming calls also include `stream: true`.
Stop metadata includes `:http_status_code` when an HTTP response is available,
`:error`, and `:error_type` on errors.

Stop measurements include `:duration`. Streaming stop measurements also
include `:time_to_first_chunk` when a chunk was received, including a
protocol-only event. Both measurements use native time units. Applications
integrating with OpenTelemetry can map metadata to its semantic conventions
in their handlers.

Built-in extractors select operational attributes rather than recording
request or response bodies. Custom extractors and static metadata control
any additional data recorded. Exception events include the standard
`:telemetry.span/3` exception metadata, which may contain exception details.

# `event_metadata`
*optional* 

```elixir
@callback event_metadata(
  metadata :: map(),
  event :: term(),
  response :: Req.Response.t(),
  opts :: keyword()
) :: map()
```

# `request_metadata`
*optional* 

```elixir
@callback request_metadata(
  metadata :: map(),
  request :: map() | keyword(),
  opts :: keyword()
) :: map()
```

# `response_metadata`
*optional* 

```elixir
@callback response_metadata(metadata :: map(), Req.Response.t(), opts :: keyword()) ::
  map()
```

---

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