@ratel-ai/telemetry

v0.1.2 · TypeScript · npm · source

Generated from the doc comments at ratel-ai/ratel@3be0ecb — 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 OTLP config resolver and the content-capture gate are re-exported from ./config; the init() exporter, which does pull the OpenTelemetry SDK, lives in @ratel-ai/telemetry-otlp.

Interfaces

InitOptions

init() (in @ratel-ai/telemetry-otlp) resolves endpoint + auth from RATEL_URL / RATEL_API_KEY, with explicit { endpoint, apiKey } values taking precedence over the environment. An explicit apiKey sets the Bearer header; the RATEL_API_KEY fallback only applies when neither apiKey nor an explicit Authorization header is given, so ambient env never overrides an auth header the caller passed on purpose.

Properties

apiKey?

optional apiKey?: string

Ratel API key; sent as Authorization: Bearer <apiKey>. Defaults to RATEL_API_KEY.

endpoint?

optional endpoint?: string

Full OTLP traces URL (incl. /v1/traces). Defaults to RATEL_URL.

headers?

optional headers?: Record<string, string>

Extra headers merged onto the request. An explicit Authorization here is kept over the RATEL_API_KEY env fallback.

serviceName?

optional serviceName?: string

service.name resource attribute. Defaults to DEFAULT_SERVICE_NAME.

---

ResolvedOtlpConfig

Resolved exporter configuration; the pure core of the OTLP exporter, exposed for testing.

Properties

headers

headers: Record<string, string>

serviceName

serviceName: string

url

url: string

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

API_KEY_ENV

const API_KEY_ENV: "RATEL_API_KEY" = "RATEL_API_KEY"

Env var whose value is the default Ratel API key.

---

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; honored by init() 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

---

DEFAULT_SERVICE_NAME

const DEFAULT_SERVICE_NAME: "ratel" = "ratel"

service.name used when the caller does not pass one.

---

ENDPOINT_ENV

const ENDPOINT_ENV: "RATEL_URL" = "RATEL_URL"

Env var whose value is the default OTLP endpoint.

---

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 message text and tool-call content (never span attributes). Borrowed from gen_ai (Tier 1).

---

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_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 event carrying hit ids + scores + per-stage BM25 timing; gated like content. The ratel.search span itself carries only counts.

---

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_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

---

resolveOtlpConfig()

resolveOtlpConfig(opts?, env?): ResolvedOtlpConfig

Resolve InitOptions into concrete exporter config. Pure and env-injectable so the endpoint/auth precedence is testable without a network.

Parameters

Returns

ResolvedOtlpConfig

---

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