Crate ratel_ai_telemetry 

ratel-ai-telemetry — the ratel.* telemetry vocabulary.

See README.md and the wire contract in ../CONVENTIONS.md for design.

Enums

AuthOutcome

Outcome of an MCP auth flow. Emitted as ratel.auth.outcome; needs_auth is the 401-driven AuthNeeds case (ADR-0007 auth_needs).

ExperimentArmOutcome

Completion outcome of one experiment-arm dispatch.

ExperimentArmRole

Immutable role assigned when an experiment arm is dispatched.

ExperimentDropReason

Terminal reason a peer-eligible shadow produced no comparison.

ExperimentSkipReason

Reason a requested shadow dispatch did not start.

Origin

Where a ratel.* span’s search came from. Emitted as the ratel.origin attribute; mirrors the local trace Origin (ADR-0007).

SearchTarget

What a ratel.search span was searching. Emitted as ratel.search.target; folds capability-tool search, skill search, and fact search into one span shape.

Constants

CAPTURE_CONTENT_ENV

The ecosystem instrumentation env var gating message/tool content capture. Default off; the standard OTel gen_ai gate rather than a Ratel-invented flag (CONVENTIONS.md § Capture gating). This crate is constants-only — the TS/Python init() helpers read it. Values: legacy boolean, or the enum NO_CONTENT (default) / SPAN_ONLY / EVENT_ONLY / SPAN_AND_EVENT.

EXECUTE_TOOL

execute_tool — the gen_ai.operation.name value for a tool invocation.

EXPERIMENTAL_CATALOG_DEFINITIONS_ENV

Ratel-specific opt-in for the experimental catalog-definition event. The generic content-capture gate must also allow EventRecord content.

GEN_AI_INFERENCE_DETAILS

gen_ai.client.inference.operation.details — inference request/response content.

GEN_AI_INPUT_MESSAGES

gen_ai.input.messages — the input message list (Opt-In content).

GEN_AI_OPERATION_NAME

gen_ai.operation.name — set to EXECUTE_TOOL for a tool invocation.

GEN_AI_OUTPUT_MESSAGES

gen_ai.output.messages — generated outputs; every message includes finish_reason.

GEN_AI_SYSTEM_INSTRUCTIONS

gen_ai.system_instructions — the system prompt as a bare parts[] (Opt-In content).

GEN_AI_TOOL_CALL_ARGUMENTS

gen_ai.tool.call.arguments — tool arguments (Opt-In content, gated).

GEN_AI_TOOL_CALL_ID

gen_ai.tool.call.id — tool call id, when available.

GEN_AI_TOOL_CALL_RESULT

gen_ai.tool.call.result — tool result (Opt-In content, gated).

GEN_AI_TOOL_NAME

gen_ai.tool.name — the capability tool id.

RATEL_AUTH_FLOW

ratel.auth.flow — MCP auth flow.

RATEL_AUTH_OUTCOME

ratel.auth.outcome — ok / refreshed / needs_auth / failed (see AuthOutcome).

RATEL_CATALOG_CONTENT_HASH

ratel.catalog.content_hash — canonical definition SHA-256.

RATEL_CATALOG_DEFINITION

ratel.catalog.definition — experimental, opt-in complete catalog definition event.

RATEL_CATALOG_DESCRIPTION

ratel.catalog.description — model-facing catalog entry description.

RATEL_CATALOG_ID

ratel.catalog.id — stable catalog entry id.

RATEL_CATALOG_INPUT_SCHEMA

ratel.catalog.input_schema — canonical JSON tool input schema.

RATEL_CATALOG_KIND

ratel.catalog.kind — tool, skill, or fact.

RATEL_CATALOG_NAME

ratel.catalog.name — model-facing catalog entry name.

RATEL_CATALOG_OUTPUT_SCHEMA

ratel.catalog.output_schema — canonical JSON tool output schema.

RATEL_CATALOG_SCHEMA_OMITTED

ratel.catalog.schema_omitted — one or more oversized schema attributes were omitted.

RATEL_CATALOG_SEARCHABLE_DESCRIPTION

ratel.catalog.searchable_description — effective searchable description.

RATEL_CATALOG_SEARCHABLE_DESCRIPTION_OVERRIDDEN

ratel.catalog.searchable_description_overridden — whether an override is set.

RATEL_CATALOG_TAGS

ratel.catalog.tags — search tags; empty for tools.

RATEL_CATALOG_USE_DEFINITION_OVERRIDES

ratel.catalog.use_definition_overrides — runtime opted into externally-sourced definition overrides.

RATEL_EVENT_ID

ratel.event.id — runtime-event/OTel deduplication and join key.

RATEL_EXPERIMENT_AGREEMENT_EXACT_ORDER

ratel.experiment.agreement.exact_order — whether complete ordered ids agree.

RATEL_EXPERIMENT_AGREEMENT_ITEM_ATTRS

ratel.experiment.agreement.item_attrs — rank-zero shared-key agreement map.

RATEL_EXPERIMENT_AGREEMENT_JACCARD_AT_K

ratel.experiment.agreement.jaccard_at_k — rank-window Jaccard agreement.

RATEL_EXPERIMENT_AGREEMENT_K

ratel.experiment.agreement.k — rank window used for Jaccard.

RATEL_EXPERIMENT_AGREEMENT_OVERLAP_COUNT

ratel.experiment.agreement.overlap_count — complete-set overlap count.

RATEL_EXPERIMENT_AGREEMENT_RESULT_ATTRS

ratel.experiment.agreement.result_attrs — result-level union-key agreement map.

RATEL_EXPERIMENT_AGREEMENT_TOP1

ratel.experiment.agreement.top1 — whether first ranked ids agree.

RATEL_EXPERIMENT_ARM

ratel.experiment.arm — one serving or shadow experiment-arm dispatch.

RATEL_EXPERIMENT_ARM_BAGGAGE_KEY

Baggage key matching RATEL_EXPERIMENT_ARM.

RATEL_EXPERIMENT_COLD

ratel.experiment.cold — whether warmup was unresolved when selection began.

RATEL_EXPERIMENT_COMPARISON

ratel.experiment.comparison — one shadow-vs-served comparison.

RATEL_EXPERIMENT_DROP

ratel.experiment.drop — one peer comparison that could not be emitted.

RATEL_EXPERIMENT_DROP_REASON

ratel.experiment.drop.reason — comparison drop reason (see ExperimentDropReason).

RATEL_EXPERIMENT_DURATION_MS

ratel.experiment.duration_ms — arm callback duration in milliseconds.

RATEL_EXPERIMENT_EFFECTIVE_ARM

ratel.experiment.effective_arm — caller-visible arm after fallback.

RATEL_EXPERIMENT_FALLBACK

ratel.experiment.fallback — one successful fallback selection.

RATEL_EXPERIMENT_FALLBACK_EFFECTIVE_ARM

ratel.experiment.fallback.effective_arm — fallback arm that served.

RATEL_EXPERIMENT_FALLBACK_REUSED_SHADOW

ratel.experiment.fallback.reused_shadow — whether fallback reused admitted shadow work.

RATEL_EXPERIMENT_HIT_COUNT

ratel.experiment.hit_count — ranked result count when ranking succeeds.

RATEL_EXPERIMENT_ID

ratel.experiment.id — configured experiment id.

RATEL_EXPERIMENT_ID_BAGGAGE_KEY

Baggage key matching RATEL_EXPERIMENT_ID.

RATEL_EXPERIMENT_INVOCATION

ratel.experiment.invocation — attributed or unattributed tool invocation.

RATEL_EXPERIMENT_INVOCATION_AGE_MS

ratel.experiment.invocation.age_ms — selection age at invocation report time.

RATEL_EXPERIMENT_INVOCATION_ATTRIBUTED

ratel.experiment.invocation.attributed — whether an invocation matched a selection.

RATEL_EXPERIMENT_INVOCATION_RANK

ratel.experiment.invocation.rank — zero-based first rank, or -1 when absent.

RATEL_EXPERIMENT_OUTCOME

ratel.experiment.outcome — arm completion attr and reported-outcome EventRecord name.

RATEL_EXPERIMENT_OUTCOME_LABEL

ratel.experiment.outcome.label — free non-empty reported outcome label.

RATEL_EXPERIMENT_OUTCOME_SCORE

ratel.experiment.outcome.score — finite reported outcome score.

RATEL_EXPERIMENT_RANKING_ERROR

ratel.experiment.ranking_error — error type when ranking projection fails.

RATEL_EXPERIMENT_RESULTS

ratel.experiment.results — ranked measurement for one experiment arm.

RATEL_EXPERIMENT_RESULT_ATTRIBUTES_ERROR

ratel.experiment.result_attributes_error — result-level projection error type.

RATEL_EXPERIMENT_RESULT_ATTRS

ratel.experiment.result_attrs — capture-gated item attrs aligned to result ids.

RATEL_EXPERIMENT_RESULT_ATTRS_ENCODING_ERROR

ratel.experiment.result_attrs_encoding_error — item-attribute encoding error type.

RATEL_EXPERIMENT_RESULT_IDS

ratel.experiment.result_ids — ordered ranked result identifiers.

RATEL_EXPERIMENT_RESULT_SCORES

ratel.experiment.result_scores — ordered finite scores when every item has one.

RATEL_EXPERIMENT_ROLE

ratel.experiment.role — immutable dispatch role (see ExperimentArmRole).

RATEL_EXPERIMENT_ROLE_BAGGAGE_KEY

Baggage key matching RATEL_EXPERIMENT_ROLE.

RATEL_EXPERIMENT_SELECTION_ID

ratel.experiment.selection_id — opaque selection correlation id.

RATEL_EXPERIMENT_SELECTION_ID_BAGGAGE_KEY

Baggage key matching RATEL_EXPERIMENT_SELECTION_ID.

RATEL_EXPERIMENT_SERVED_ARM

ratel.experiment.served.arm — effective served arm in a peer comparison.

RATEL_EXPERIMENT_SERVED_DURATION_MS

ratel.experiment.served.duration_ms — effective served arm callback duration.

RATEL_EXPERIMENT_SERVED_HIT_COUNT

ratel.experiment.served.hit_count — effective served ranking size.

RATEL_EXPERIMENT_SERVED_OUTCOME

ratel.experiment.served.outcome — effective served arm outcome.

RATEL_EXPERIMENT_SHADOW_ARM

ratel.experiment.shadow.arm — compared shadow arm.

RATEL_EXPERIMENT_SHADOW_DURATION_MS

ratel.experiment.shadow.duration_ms — compared shadow arm callback duration.

RATEL_EXPERIMENT_SHADOW_HIT_COUNT

ratel.experiment.shadow.hit_count — compared shadow ranking size.

RATEL_EXPERIMENT_SHADOW_OUTCOME

ratel.experiment.shadow.outcome — compared shadow arm outcome.

RATEL_EXPERIMENT_SKIP

ratel.experiment.skip — one shadow dispatch skipped for capacity.

RATEL_EXPERIMENT_SKIP_ARM

ratel.experiment.skip.arm — shadow arm skipped for capacity.

RATEL_EXPERIMENT_SKIP_CONCURRENCY

ratel.experiment.skip.concurrency — configured shadow concurrency.

RATEL_EXPERIMENT_SKIP_REASON

ratel.experiment.skip.reason — skip reason (see ExperimentSkipReason).

RATEL_EXPERIMENT_TURN

ratel.experiment.turn — optional caller-supplied turn annotation.

RATEL_EXPERIMENT_UNIT

ratel.experiment.unit — pseudonymous 16-hex unit hash.

RATEL_EXPERIMENT_UNIT_BAGGAGE_KEY

Baggage key matching RATEL_EXPERIMENT_UNIT.

RATEL_ORIGIN

ratel.origin — direct library call vs agent-synthesized (shared attribute).

RATEL_SEARCH

ratel.search — capability search (unifies tool-search and skill-search).

RATEL_SEARCH_HIT_COUNT

ratel.search.hit_count — results returned.

RATEL_SEARCH_QUERY

ratel.search.query — the search text (content, gated like message content).

RATEL_SEARCH_RESULTS

ratel.search.results — Opt-In search-content event; gated like content.

RATEL_SEARCH_TARGET

ratel.search.target — tool, skill, or fact (see SearchTarget).

RATEL_SEARCH_TOP_K

ratel.search.top_k — requested result count.

RATEL_SKILL_ID

ratel.skill.id — skill loaded on the ratel.skill.load span.

RATEL_SKILL_LOAD

ratel.skill.load — skill content load (get_skill_content).

RATEL_TOOL_ARGS_SIZE_BYTES

ratel.tool.args_size_bytes — argument payload size on the execute_tool span.

RATEL_TOOL_EXECUTION_DETAILS

ratel.tool.execution.details — Opt-In structured tool arguments/result event.

RATEL_UPSTREAM_REGISTER

ratel.upstream.register — upstream-MCP ingest.

RATEL_UPSTREAM_SERVER

ratel.upstream.server — upstream MCP server backing a tool / auth flow.

RATEL_UPSTREAM_TOOL_COUNT

ratel.upstream.tool_count — tools ingested on register.

RATEL_UPSTREAM_TRANSPORT

ratel.upstream.transport — stdio / http / sse / …

SEMCONV_VERSION

The pinned OpenTelemetry semantic-conventions version this vocabulary tracks (the gen_ai group). The pin is the contract; consumers read against this exact version, never “latest”. Bumping it is a reviewed change with its own PR and, if the shape changed, a superseding ADR (CONVENTIONS.md § The pin).