Telemetry integration for observability.

Puck automatically emits telemetry events when the :telemetry dependency is installed. No configuration is required.

Events

Call Start

[:puck, :call, :start] - Executed before the LLM call.

Measurements

• :system_time - The system time in native units.

Metadata

• :client - The Puck.Client struct.
• :prompt - The prompt content.
• :context - The Puck.Context struct.

Call Stop

[:puck, :call, :stop] - Executed after a successful LLM call.

Measurements

• :duration - Time taken in native units.

Metadata

• :client - The Puck.Client struct.
• :response - The Puck.Response struct.
• :context - The Puck.Context struct.

Call Exception

[:puck, :call, :exception] - Executed when the call fails.

Measurements

• :duration - Time taken before failure in native units.

Metadata

• :client - The Puck.Client struct.
• :context - The Puck.Context struct.
• :kind - The exception type (:error, :exit, or :throw).
• :reason - The error reason.
• :stacktrace - The stacktrace (may be empty).

Stream Start

[:puck, :stream, :start] - Executed before streaming begins.

Measurements

• :system_time - The system time in native units.

Metadata

• :client - The Puck.Client struct.
• :prompt - The prompt content.
• :context - The Puck.Context struct.

Stream Chunk

[:puck, :stream, :chunk] - Executed for each streamed chunk.

Measurements

No measurements.

Metadata

• :client - The Puck.Client struct.
• :chunk - The chunk data.
• :context - The Puck.Context struct.

Stream Stop

[:puck, :stream, :stop] - Executed after streaming completes.

Measurements

• :duration - Time taken in native units.

Metadata

• :client - The Puck.Client struct.
• :context - The Puck.Context struct.

Stream Exception

[:puck, :stream, :exception] - Executed when streaming initialization fails.

Measurements

• :duration - Time taken before failure in native units.

Metadata

• :client - The Puck.Client struct.
• :context - The Puck.Context struct.
• :kind - The exception type (:error, :exit, or :throw).
• :reason - The error reason.
• :stacktrace - The stacktrace (may be empty).

Backend Request

[:puck, :backend, :request] - Executed before the backend request.

Measurements

• :system_time - The system time in native units.

Metadata

• :config - The backend configuration.
• :messages - The messages being sent.

Backend Response

[:puck, :backend, :response] - Executed after the backend response.

Measurements

• :system_time - The system time in native units.

Metadata

• :config - The backend configuration.
• :response - The backend response.

Backend BAML Error

[:puck, :backend, :baml, :error] — Emitted when the BAML backend returns an error. Includes the raw LLM response from the collector so callers can inspect what the model actually returned.

Measurements

No measurements.

Metadata

• :function - The BAML function name.
• :reason - The error reason (string from the NIF).
• :raw_llm_response - The raw LLM response string, or nil if unavailable.

The :raw_llm_response value is the unredacted model output. If the prompt contained sensitive data, the response may echo it back. Redact before logging in production.

Compaction Start

[:puck, :compaction, :start] - Executed before context compaction.

Measurements

• :system_time - The system time in native units.

Metadata

• :context - The Puck.Context struct before compaction.
• :strategy - The compaction strategy module.
• :config - The compaction configuration.

Compaction Stop

[:puck, :compaction, :stop] - Executed after successful compaction.

Measurements

• :duration - Time taken in native units.
• :messages_before - Message count before compaction.
• :messages_after - Message count after compaction.

Metadata

• :context - The Puck.Context struct after compaction.
• :strategy - The compaction strategy module.

Compaction Error

[:puck, :compaction, :error] - Executed when compaction fails.

Measurements

• :duration - Time taken before failure in native units.

Metadata

• :context - The Puck.Context struct.
• :strategy - The compaction strategy module.
• :reason - The error reason.

LiveView Stream Start

[:puck, :live_view, :stream, :start] — Emitted when a LiveView stream begins.

Measurements

• :system_time - The system time in native units.

Metadata

• :stream_id - The stream identifier.
• :client - The Puck.Client struct.

LiveView Stream Stop

[:puck, :live_view, :stream, :stop] — Emitted when a LiveView stream completes.

Measurements

• :duration - Time taken in native units.

Metadata

• :stream_id - The stream identifier.
• :response - The Puck.Response struct.

LiveView Stream Error

[:puck, :live_view, :stream, :error] — Emitted when a LiveView stream fails.

Measurements

No measurements.

Metadata

• :stream_id - The stream identifier.
• :reason - The error reason.

LiveView Stream Cancel

[:puck, :live_view, :stream, :cancel] — Emitted when a LiveView stream is cancelled.

Measurements

No measurements.

Metadata

• :stream_id - The stream identifier.
• :content - The accumulated content at cancellation.

LiveView Stream Handler Error

[:puck, :live_view, :stream, :handler_error] — Emitted when a Puck.LiveView.Handler callback raises.

Measurements

No measurements.

Metadata

• :stream_id - The stream identifier.
• :handler - The handler module.
• :callback - The callback that raised (e.g. :on_chunk, :on_done).
• :reason - The exception.

Attaching Handlers

:telemetry.attach_many("my-handler", Puck.Telemetry.event_names(), &handler/4, nil)

# Or use the default logger
Puck.Telemetry.attach_default_logger()