OpenTelemetry Events

Claude Code can send log events to an OpenTelemetry (OTEL) collector. This page lists the 28 events that the program emits and the attributes each one carries. The variables that turn telemetry on and set the exporters are on Telemetry and Debug.

Events

Source: the program. The attribute names come from the call sites of the event emitter, read into claude-code-otel.json. A key that some call sites leave out may be missing from an event. So treat every attribute as optional. The schema has the type of each attribute. The program sends some numbers as strings. So look a field up there before you rely on its type. Only tool_decision is marked

Documented: An official docs page names this item.

, because earlier pages of this site name it. We did not check the other events against the official Monitoring page.

Event	Status	What It Records	Attributes
api_error	Undocumented: Only the program shows this item. It can change without notice.	An API request failed.	model, error, status_code, duration_ms, attempt, request_id, client_request_id, speed, query_source, effort, agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name
api_refusal	Undocumented: Only the program shows this item. It can change without notice.	The API refused a request.	model, request_id, speed, attempt, server_fallback_hop, query_source, effort, has_category, has_explanation, category, agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name
api_request	Undocumented: Only the program shows this item. It can change without notice.	An API request finished, with token counts, cost, and timing.	model, input_tokens, output_tokens, cache_read_tokens, cache_creation_tokens, cache_creation_5m_tokens, cache_creation_1h_tokens, cost_usd, cost_usd_micros, duration_ms, ttft_ms, request_id, client_request_id, speed, query_source, effort, agent.name, skill.name, plugin.name, marketplace.name, mcp_server.name, mcp_tool.name
api_retries_exhausted	Undocumented: Only the program shows this item. It can change without notice.	An API request used all its retries.	model, error, status_code, total_attempts, total_retry_duration_ms, speed, query_source, effort
assistant_response	Undocumented: Only the program shows this item. It can change without notice.	A model response. The text is in response only when OTEL_LOG_ASSISTANT_RESPONSES or OTEL_LOG_USER_PROMPTS allows it.	response_length, response, request_id, message.uuid, model, query_source
at_mention	Undocumented: Only the program shows this item. It can change without notice.	An @ mention was used.	mention_type, success
auth	Undocumented: Only the program shows this item. It can change without notice.	An auth action ran.	action, success, auth_method, error_category, status_code
compaction	Undocumented: Only the program shows this item. It can change without notice.	A context compaction ran.	trigger, success, duration_ms, pre_tokens, post_tokens, error, precompute_reuse
feedback_survey	Undocumented: Only the program shows this item. It can change without notice.	A step of the session quality survey.	event_type, appearance_id, response, survey_type, enabled_via_override, event_origin, event_origin_server, trigger_type, plugin_id_hash, plugin.name
hook_execution_complete	Undocumented: Only the program shows this item. It can change without notice.	The hooks of one hook event finished.	hook_event, hook_name, num_hooks, num_success, num_blocking, num_non_blocking_error, num_cancelled, total_duration_ms, stdout_chars, additional_context_chars, system_message_chars, initial_user_message_chars, num_outputs_persisted, managed_only, hook_source, safe_mode, hook_definitions
hook_execution_start	Undocumented: Only the program shows this item. It can change without notice.	The hooks of one hook event started.	hook_event, hook_name, num_hooks, managed_only, hook_source, safe_mode, hook_definitions
hook_plugin_metrics	Undocumented: Only the program shows this item. It can change without notice.	A hook event of a plugin.	plugin_id, hook_event
hook_registered	Undocumented: Only the program shows this item. It can change without notice.	A hook was registered.	hook_event, hook_type, hook_source, safe_mode, hook_matcher, plugin.name, plugin_id_hash
internal_error	Undocumented: Only the program shows this item. It can change without notice.	An internal error, with its name and code.	error_name, error_code
managed_settings_resolved	Undocumented: Only the program shows this item. It can change without notice.	Managed settings were resolved. OTEL_LOG_MANAGED_SETTINGS adds the redacted settings.	managed_settings.trigger, managed_settings.sources, managed_settings.source_behavior, managed_settings.helper.state, managed_settings.helper.applied, managed_settings.helper.entry, managed_settings.helper.path, managed_settings.helper.script_sha256, managed_settings.resolved_sha256, managed_settings.settings, managed_settings.settings_truncated, error.type
mcp_server_connection	Undocumented: Only the program shows this item. It can change without notice.	The result of an MCP server connection.	status, transport_type, server_scope, duration_ms, is_plugin, plugin_id_hash, plugin.name, error_code, server_name, error
permission_mode_changed	Undocumented: Only the program shows this item. It can change without notice.	The permission mode changed.	from_mode, to_mode, trigger
plugin_installed	Undocumented: Only the program shows this item. It can change without notice.	A plugin was installed.	plugin.name, plugin.version, marketplace.name, marketplace.is_official, install.trigger, install.disabled_by_default
plugin_loaded	Undocumented: Only the program shows this item. It can change without notice.	A plugin was loaded.	plugin.name, marketplace.name, plugin.version, plugin.scope, enabled_via, plugin_id_hash, has_hooks, has_mcp, host_owned_mcp, skill_path_count, command_path_count, agent_path_count, safe_mode
retention_sweep	Undocumented: Only the program shows this item. It can change without notice.	A cleanup of old session data ran, with counts.	result, period_days, used_default, skip_reason, transcripts_deleted, transcripts_exempted_desktop, session_files_deleted, artifacts_deleted, files_retained_fresh, files_past_cutoff, error_count, history_entries_pruned
safety_event	Gated: Works only behind a flag or a server gate. Server flag tengu_snoopy_creek, off by default since 2.1.312	A permission or safety decision. Off by default since 2.1.312, because the server-side gate tengu_snoopy_creek now defaults to false. In 2.1.311 it defaulted to true. The code that sends the event is still in the program, and both of its call sites test the gate, so a server-side flag can turn the event on again.	category, decision, decision_source, reason_type, reason_code, rule_source, grant_scope, circuit_breaker, classifier_category, hook_event, tool_class, tool_name, tool_source, permission_mode, tool_use_id, sandbox_violation_count, sandbox_enabled
skill_activated	Undocumented: Only the program shows this item. It can change without notice.	A skill was activated.	skill.name, invocation_trigger, skill.source, skill.kind, plugin.name, marketplace.name
subagent_completed	Undocumented: Only the program shows this item. It can change without notice.	A subagent finished, with token and tool-use counts.	agent_type, agent.source, is_built_in, is_async, total_tokens, total_tool_uses, duration_ms, model, final_model, model_swapped, plugin_id_hash, plugin.name
system_prompt	Undocumented: Only the program shows this item. It can change without notice.	The system prompt, or its hash.	system_prompt_hash, system_prompt, system_prompt_length, system_prompt_truncated
tool	Undocumented: Only the program shows this item. It can change without notice.	A tool definition, or its hash.	tool_name, tool_hash, tool, tool_truncated
tool_decision	Documented: An official docs page names this item.	A tool use was accepted or rejected. OTEL_LOG_TOOL_DETAILS adds classifier_category.	decision, source, tool_name, tool_use_id, tool_source, tool_parameters, classifier_verdict, classifier_category, permission_mode
tool_result	Undocumented: Only the program shows this item. It can change without notice.	A tool call finished. After a git commit it also carries the vcs.ref.head.* fields.	tool_name, tool_use_id, success, duration_ms, tool_parameters, tool_input, tool_input_size_bytes, tool_result_size_bytes, decision_source, decision_type, mcp_server_scope, vcs.ref.head.revision, vcs.ref.head.name, vcs.ref.head.type, error_type, error
user_prompt	Undocumented: Only the program shows this item. It can change without notice.	A user prompt. The text is in prompt only when OTEL_LOG_USER_PROMPTS is on.	prompt_length, prompt, prompt_text

What Two Attributes Report

Attribute	Status	What It Reports	Notes
effort	Undocumented: Only the program shows this item. It can change without notice.	The effort level in force for the request.	Since 2.1.312. Before, it could name a newly picked level before the model applied it. The program takes the level from the last effort change that the conversation holds, and uses the new pick only when there is none. The api_request event reads it from output_config.effort of the request, and the refusal path passes the same level. We did not trace api_error and api_retries_exhausted one by one.
mcp_server.name	Undocumented: Only the program shows this item. It can change without notice.	The server name. For most servers that a plugin declares it reports custom.	Since 2.1.312, it reports the real name for a remote MCP server with a fixed URL of type http, sse, or ws that a plugin declares, when the plugin comes from an official marketplace that the program vouches for. A server whose endpoint is a template still reports custom.

Source: the program. The level in force is in chunk-r5cyd28m.js lines 135670, 136924, and 141434. The server name is in chunk-3xe0k172.js lines 44518 to 44531 and 48503 to 48514, with custom at line 42524. The safety_event gate is in chunk-r5cyd28m.js lines 186177, 186258, 186295, and 186356, and in chunk-2ht8z368.js line 184333 of 2.1.311.

Attributes on Every Event

Every event carries these base attributes: user.id, user.email, user.groups, event.name, event.timestamp, event.sequence, prompt.id, and workspace.host_paths. When OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES is set, the program also copies the keys of OTEL_RESOURCE_ATTRIBUTES.

Related Pages

• Telemetry and Debug lists the variables that control telemetry.
• JSON Schemas has the exact fields in claude-code-otel.json.
• Undocumented Items indexes every undocumented item.
• Monitoring in the official docs.