Events Claudex emits, and a ready-made logger for them.

Claudex writes nothing to your logs on its own. It emits :telemetry events, and you decide what happens to them. To see what the SDK is doing while you're debugging, attach the logger that ships with it:

Claudex.Telemetry.attach_default_logger()

That's it — no config, no compile flags. Turn it off with detach_default_logger/0. For anything beyond development, attach your own handler with :telemetry.attach_many/4 and send the events wherever they belong.

What's in an event, and what isn't

Metadata carries model names, HTTP status, request ids, token counts, durations, tool names, and turn numbers. It never carries prompts, completions, tool arguments, tool results, or anything from your client — logs get shipped to places conversations shouldn't go, and an API key should never be one keystroke from a log line.

Events

[:claudex, :request, :start | :stop | :exception]

A span around one HTTP request. Metadata has :method and :path throughout, :model when the request names one, and on :stop also :status, :request_id, and — when the response carries usage — :input_tokens and :output_tokens. The request id is worth capturing: it's what Anthropic support asks for, and Claudex otherwise keeps it only on errors.

[:claudex, :stream, :start | :stop]

A streaming response, from the first byte to the last. :stop measurements carry :duration and :chunks. Nothing else reports on a lazy stream, so this is the only way to see one that ended early.

[:claudex, :retry, :declined]

A retry that Claudex refused because part of the response had already reached the caller — retrying would replay output and bill twice. Req logs the retries it makes; without this, the ones we decline look like nothing happened.

[:claudex, :tool, :start | :stop | :exception]

A span around one tool call. :stop metadata has :tool and an :outcome of :ok, :refused, :failed, or :unknown_tool.

[:claudex, :tool_runner, :turn] and [:claudex, :tool_runner, :stop]

One event per reply in a tool conversation, and one when the loop ends carrying :stop — :completed, :refusal, or :max_turns.