ReqLLM.Telemetry (ReqLLM v1.11.0)

@type context() :: %{
  request_id: String.t(),
  model: LLMDB.Model.t(),
  operation: atom(),
  mode: lifecycle_mode(),
  transport: transport(),
  payload_mode: payload_mode(),
  reasoning_contract: reasoning_contract(),
  original_opts: keyword(),
  request_summary: map(),
  request_payload: any(),
  request_started?: boolean(),
  request_stopped?: boolean(),
  started_at: integer() | nil,
  request_measurement: map() | nil,
  requested_reasoning: map(),
  effective_reasoning: map(),
  reasoning_started?: boolean(),
  reasoning_started_at: integer() | nil,
  reasoning_observation: map(),
  response_summary_state: map()
}

lifecycle_mode()

@type lifecycle_mode() :: :sync | :stream

payload_mode()

@type payload_mode() :: :none | :raw

reasoning_contract()

@type reasoning_contract() ::
  :openai_effort
  | :openai_or_thinking
  | :anthropic_thinking
  | :platform_anthropic
  | :google_budget
  | :alibaba_thinking
  | :thinking_toggle
  | :zenmux_reasoning
  | :unsupported

transport()

@type transport() :: :req | :finch

Functions

emit_token_usage(model, usage, metadata \\ [])

@spec emit_token_usage(LLMDB.Model.t(), map() | nil, keyword()) :: :ok

Emits the compatibility token usage event.

exception_request(context, error, opts \\ [])

@spec exception_request(context(), Exception.t() | term(), keyword()) :: context()

Emits request exception telemetry and returns the updated context.

new_context(model, opts, extra \\ [])

@spec new_context(LLMDB.Model.t(), keyword(), keyword()) :: context()

Builds a telemetry context for a request lifecycle.

observe_response(context, response)

@spec observe_response(context(), any()) :: context()

Observes a terminal response and updates response and reasoning state.

observe_stream_chunk(context, chunk)

@spec observe_stream_chunk(context(), ReqLLM.StreamChunk.t()) :: context()

Observes a streaming chunk and emits milestone-based reasoning updates.

put_request_context(request, context)

@spec put_request_context(Req.Request.t(), context()) :: Req.Request.t()

Stores telemetry context in a Req request.

put_response_context(response, context)

@spec put_response_context(Req.Response.t(), context()) :: Req.Response.t()

Stores telemetry context in a Req response private map.

reasoning_metadata(context, extra \\ %{})

@spec reasoning_metadata(context(), map()) :: map()

Returns the normalized metadata map for reasoning lifecycle events.

request_context(request)

@spec request_context(Req.Request.t()) :: context() | nil

Reads telemetry context from a Req request.

request_context_key()

@spec request_context_key() :: atom()

Returns the private key used to store telemetry context on Req requests.

request_metadata(context, extra)

@spec request_metadata(context(), map()) :: map()

Returns the normalized request metadata map for request lifecycle events.

start_request(context, request_source)

@spec start_request(context(), any()) :: context()

Emits request start telemetry and returns the updated context.

stop_request(context, response, opts \\ [])

@spec stop_request(context(), any(), keyword()) :: context()

Emits request stop telemetry and returns the updated context.

usage_from_response(arg1)

@spec usage_from_response(any()) :: map() | nil

Extracts token usage metadata from a Req response private map.