Skip to main content

instrumentation.ts

instrumentation.ts is the single home for telemetry, auto-discovered and run once at startup before the first agent turn. Add it when you want an external telemetry sink or explicit content-capture controls.

Minimal Example​

import { defineInstrumentation } from "@assemblyline-agents/core";
import { createOtlpSinkFromEnv } from "@assemblyline-agents/otlp";

export default defineInstrumentation({
  serviceName: "starter-agent",
  captureContent: "usage",
  setup: ({ env }) => createOtlpSinkFromEnv(env)
});

Full Options​

FieldType / valuesDefaultEffect
serviceNamestringagent nameService name stamped on spans.
setup({ agentName, manifest, env }) => sink—Runs once at startup; return a telemetry sink to export spans.
captureContentlevel string | policy object"usage"Content-capture detail; a bare level is shorthand for { level }.
recordInputs / recordOutputsbooleanfalseRecord run inputs/outputs on spans.

captureContent also accepts a policy object:

FieldType / valuesDefaultEffect
leveloff | usage | content | full—Capture level (required in object form).
maxCharsnumber~8000 (relaxed at full)Per-field character cap before truncation.
redactbooleantrue (even at full)Key-based redaction of sensitive values.
redactKeysstring[]built-in setExtra sensitive key names to redact.
sampleRatenumber 0..11Per-trace sampling of content; usage/metadata always export.
includeToolIObooleantrue at content/fullCapture tool arguments and results.

Agent Runs​

Agent Runs-style observability is available without instrumentation.ts through run, event, tool, checkpoint, delivery, usage, subagent, and timeline query contracts. The Node host exposes authenticated inspection endpoints under /runs.

OTLP Export​

@assemblyline-agents/otlp provides:

  • createOtlpSink(options)
  • createOtlpSinkFromEnv(env)

createOtlpSinkFromEnv reads OTEL_EXPORTER_OTLP_ENDPOINT, OTEL_EXPORTER_OTLP_HEADERS, OTEL_SERVICE_NAME, OTEL_EXPORTER_OTLP_TIMEOUT, ASSEMBLY_LINE_OTLP_BATCH_MAX, and ASSEMBLY_LINE_OTLP_FLUSH_MS. Any OTLP backend works: Langfuse, Phoenix, Grafana, and others.

Capture Levels​

LevelRecords
offNo span content.
usageToken usage, cost, model, provider, finish reason, and tool-call spans. No message bodies.
contentAdds bounded prompt, completion, and tool IO previews with redaction.
fullMore complete prompt, completion, and tool IO capture; use only in trusted environments.

Conventions​

  • Prefer usage in production unless operators have an explicit reason to capture content and the product privacy materials account for it.
  • Host- or gateway-supplied instrumentation overrides win over instrumentation.ts.