@ratel-ai/telemetry

v0.2.0 · TypeScript · npm · source

Generated from the doc comments at ratel-ai/ratel@d8635d5 — do not edit by hand. Regenerate with pnpm sync:api in apps/docs.

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

See the wire contract in CONVENTIONS.md. Emitting the vocabulary is done through the standard OpenTelemetry JS SDK; this package adds no transport and no schema (ADR-0007). These constants are the ratel.* overlay Ratel owns, plus the small subset of gen_ai.* keys the overlay emits directly on the execute_tool span (borrowed verbatim from OpenTelemetry, never renamed).

This package is OTel-free (ADR-0007): the only behavior it carries beyond the constants is the content-capture gate, re-exported from ./content-capture. Wiring a provider — endpoint, auth, exporters, processors, flush — is the host's job.

Type Aliases

AuthOutcome

AuthOutcome = typeof AuthOutcome[keyof typeof AuthOutcome]

Outcome of an MCP auth flow. Carried by ratel.auth.outcome; NeedsAuth is the 401-driven AuthNeeds case (ADR-0007 auth_needs).

---

ContentCapture

ContentCapture = typeof ContentCapture[keyof typeof ContentCapture]

Message/tool content capture modes for OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT (CONVENTIONS.md § Capture gating). Default off.

---

Origin

Origin = typeof Origin[keyof typeof Origin]

Whether a ratel.* span was a direct library call or synthesized by the agent inside its loop. Carried by ratel.origin; mirrors the local trace Origin (ADR-0007).

---

SearchTarget

SearchTarget = typeof SearchTarget[keyof typeof SearchTarget]

What a ratel.search span was searching. Carried by ratel.search.target; folds capability-tool search and skill search into one span shape.

Variables

AuthOutcome

const AuthOutcome: object

Outcome of an MCP auth flow. Carried by ratel.auth.outcome; NeedsAuth is the 401-driven AuthNeeds case (ADR-0007 auth_needs).

Type Declaration

---

CAPTURE_CONTENT_ENV

const CAPTURE_CONTENT_ENV: "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT" = "OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT"

The ecosystem instrumentation env var gating message/tool content capture. Default off; the shared ecosystem name rather than a Ratel-invented flag (CONVENTIONS.md § Capture gating). Values: legacy boolean, or the enum NO_CONTENT (default) / SPAN_ONLY / EVENT_ONLY / SPAN_AND_EVENT.

---

ContentCapture

const ContentCapture: object

Message/tool content capture modes for OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT (CONVENTIONS.md § Capture gating). Default off.

Type Declaration

---

EXECUTE_TOOL

const EXECUTE_TOOL: "execute_tool" = "execute_tool"

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

Deliberately the standard OTel gen_ai operation, not a bespoke ratel.invoke span, so a generic OTel backend already understands it (locked 2026-07-05). The invoke is enriched with ratel.* attributes.

---

GEN_AI_INFERENCE_DETAILS

const GEN_AI_INFERENCE_DETAILS: "gen_ai.client.inference.operation.details" = "gen_ai.client.inference.operation.details"

gen_ai.client.inference.operation.details — the event that carries inference request and response content. Borrowed from gen_ai (Tier 1).

---

GEN_AI_INPUT_MESSAGES

const GEN_AI_INPUT_MESSAGES: "gen_ai.input.messages" = "gen_ai.input.messages"

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

---

GEN_AI_OPERATION_NAME

const GEN_AI_OPERATION_NAME: "gen_ai.operation.name" = "gen_ai.operation.name"

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

---

GEN_AI_OUTPUT_MESSAGES

const GEN_AI_OUTPUT_MESSAGES: "gen_ai.output.messages" = "gen_ai.output.messages"

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

---

GEN_AI_SYSTEM_INSTRUCTIONS

const GEN_AI_SYSTEM_INSTRUCTIONS: "gen_ai.system_instructions" = "gen_ai.system_instructions"

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

---

GEN_AI_TOOL_CALL_ARGUMENTS

const GEN_AI_TOOL_CALL_ARGUMENTS: "gen_ai.tool.call.arguments" = "gen_ai.tool.call.arguments"

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

---

GEN_AI_TOOL_CALL_ID

const GEN_AI_TOOL_CALL_ID: "gen_ai.tool.call.id" = "gen_ai.tool.call.id"

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

---

GEN_AI_TOOL_CALL_RESULT

const GEN_AI_TOOL_CALL_RESULT: "gen_ai.tool.call.result" = "gen_ai.tool.call.result"

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

---

GEN_AI_TOOL_NAME

const GEN_AI_TOOL_NAME: "gen_ai.tool.name" = "gen_ai.tool.name"

gen_ai.tool.name — the capability tool id.

---

Origin

const Origin: object

Whether a ratel.* span was a direct library call or synthesized by the agent inside its loop. Carried by ratel.origin; mirrors the local trace Origin (ADR-0007).

Type Declaration

---

RATEL_AUTH_FLOW

const RATEL_AUTH_FLOW: "ratel.auth.flow" = "ratel.auth.flow"

ratel.auth.flow — MCP auth flow.

---

RATEL_AUTH_OUTCOME

const RATEL_AUTH_OUTCOME: "ratel.auth.outcome" = "ratel.auth.outcome"

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

---

RATEL_ORIGIN

const RATEL_ORIGIN: "ratel.origin" = "ratel.origin"

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

---

RATEL_SEARCH

const RATEL_SEARCH: "ratel.search" = "ratel.search"

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

---

RATEL_SEARCH_HIT_COUNT

const RATEL_SEARCH_HIT_COUNT: "ratel.search.hit_count" = "ratel.search.hit_count"

ratel.search.hit_count — results returned.

---

RATEL_SEARCH_QUERY

const RATEL_SEARCH_QUERY: "ratel.search.query" = "ratel.search.query"

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

---

RATEL_SEARCH_RESULTS

const RATEL_SEARCH_RESULTS: "ratel.search.results" = "ratel.search.results"

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

---

RATEL_SEARCH_TARGET

const RATEL_SEARCH_TARGET: "ratel.search.target" = "ratel.search.target"

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

---

RATEL_SEARCH_TOP_K

const RATEL_SEARCH_TOP_K: "ratel.search.top_k" = "ratel.search.top_k"

ratel.search.top_k — requested result count.

---

RATEL_SKILL_ID

const RATEL_SKILL_ID: "ratel.skill.id" = "ratel.skill.id"

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

---

RATEL_SKILL_LOAD

const RATEL_SKILL_LOAD: "ratel.skill.load" = "ratel.skill.load"

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

---

RATEL_TOOL_ARGS_SIZE_BYTES

const RATEL_TOOL_ARGS_SIZE_BYTES: "ratel.tool.args_size_bytes" = "ratel.tool.args_size_bytes"

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

---

RATEL_TOOL_EXECUTION_DETAILS

const RATEL_TOOL_EXECUTION_DETAILS: "ratel.tool.execution.details" = "ratel.tool.execution.details"

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

---

RATEL_UPSTREAM_REGISTER

const RATEL_UPSTREAM_REGISTER: "ratel.upstream.register" = "ratel.upstream.register"

ratel.upstream.register — upstream-MCP ingest.

---

RATEL_UPSTREAM_SERVER

const RATEL_UPSTREAM_SERVER: "ratel.upstream.server" = "ratel.upstream.server"

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

---

RATEL_UPSTREAM_TOOL_COUNT

const RATEL_UPSTREAM_TOOL_COUNT: "ratel.upstream.tool_count" = "ratel.upstream.tool_count"

ratel.upstream.tool_count — tools ingested on register.

---

RATEL_UPSTREAM_TRANSPORT

const RATEL_UPSTREAM_TRANSPORT: "ratel.upstream.transport" = "ratel.upstream.transport"

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

---

SearchTarget

const SearchTarget: object

What a ratel.search span was searching. Carried by ratel.search.target; folds capability-tool search and skill search into one span shape.

Type Declaration

---

SEMCONV_VERSION

const SEMCONV_VERSION: "1.42.0" = "1.42.0"

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" (CONVENTIONS.md § The pin).

Functions

clearContentCapture()

clearContentCapture(generation): void

Clear the programmatic content-capture override, but only when generation — the token returned by setContentCapture — still identifies the most recent set. A stale token no-ops, so an old handle shutting down late cannot clobber an override a newer caller installed (and silently re-enable, or disable, capture via the env fallback). For an unconditional clear, use setContentCapture(null).

Parameters

Returns

void

---

contentCaptureMode()

contentCaptureMode(env?): ContentCapture

Parse the ecosystem content-capture gate. A mode set via setContentCapture wins outright (env is the fallback, as in OTel); otherwise default ContentCapture.NoContent when unset/empty/unrecognized. The legacy boolean form maps true to full capture (ContentCapture.SpanAndEvent) and false to none.

Parameters

Returns

ContentCapture

---

setContentCapture()

setContentCapture(mode): number

Programmatically set the content-capture mode. While set, contentCaptureMode returns this mode regardless of OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT — programmatic config wins over the environment, matching how OpenTelemetry treats env vars as the fallback for code-level configuration. Pass null/undefined to clear the override unconditionally and return to env-driven parsing.

The mode is validated like the env var (case-insensitive, legacy true/false/ 1/0 accepted) and throws a TypeError on anything unrecognized — failing loud at config time instead of storing a value that would both disable capture and mask the env var.

Returns a generation token identifying this call as the current owner of the override; pass it to clearContentCapture to clear only if no newer set has happened since (the safe form for shutdown/teardown hooks).

Parameters

Returns

number