# `Puck.Telemetry` [🔗](https://github.com/bradleygolden/puck/blob/v0.2.25/lib/puck/telemetry.ex#L2) 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() # `attach_default_logger` Attaches a default logging handler to all Puck telemetry events. This is a convenience function for quick debugging. For production use, you should implement your own handler with appropriate log levels and formatting. ## Options - `:level` - Log level to use (default: `:debug`) ## Example Puck.Telemetry.attach_default_logger() Puck.Telemetry.attach_default_logger(level: :info) # `detach_default_logger` Detaches the default logging handler. # `event_names` Returns all telemetry event names that can be emitted. Useful for attaching handlers to all events. ## Example :telemetry.attach_many("my-handler", Puck.Telemetry.event_names(), &handler/4, nil) --- *Consult [api-reference.md](api-reference.md) for complete listing*