Skip to main content
@agentium/observability adds tracing, metrics, and structured logging. Default capture retains lifecycle metadata and usage. Prompt text, tool arguments/results, output text, and error bodies are excluded before retention or export.

Instrument an Agent

Use instrumentBus(eventBus, options) for shared buses, Teams, or Workflows. detach() removes subscriptions; shutdown() also drains owned work within its deadline. A shut-down observer cannot be reattached.

Choose an exporter

Selecting a destination is not permission to capture content. Shorthand exporters inherit instrument capture options. Explicit exporter instances independently apply their own capture policy.

Opt into content deliberately

This configuration fragment uses an existing Agent:
Opt in at both the tracer and each explicitly constructed exporter. Known credential-key fields are always removed; free text still needs application-specific redaction. Metadata identifiers can also be personal data. Redactors must be synchronous. Error stacks are never included by content mode.

Bounds and shutdown

A full export queue drops newest records. Trace retention evicts oldest records. Diagnostics expose drops and failures. Slow exporters do not block Agent completion; shutdown aborts cooperative requests and bounds its wait. A noncooperative callback can retain its in-flight slot until it settles. Core EventBus observers cannot change an Agent outcome: thrown errors and rejected observer promises are isolated. Use hooks, policy, or approval for control. onObserverError is a separate host diagnostic callback, not a telemetry payload exporter.

OpenTelemetry

OTelExporter implements HTTP JSON. Its endpoint is a base URL that appends /v1/traces; tracesEndpoint is the full signal URL. Protobuf configuration is rejected. Pass authentication through headers, not embedded URL credentials. Use OTelBridgeExporter with your existing provider/tracer when you need the host SDK’s sampling, processors, or binary exporter. The bridge never registers a global provider or shuts down the host provider. The host owns that lifecycle.

Langfuse

Use LangfuseOTLPExporter or "langfuse-otlp" for the current integration. Configure LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, and optionally LANGFUSE_BASE_URL. Keep the legacy exporter only for a deliberately maintained compatible deployment; do not dual-send the same spans through both paths.

Metrics and logs

MetricsCollector and MetricsExporter expose bounded accounting and dashboard streams. Model/tool/run lineage correlates execution with usage and outcomes. StructuredLogger supports configured drains and the same capture controls. Telemetry is observation; dropped data does not establish that an operation did or did not execute.

Read authoritative costs

Set cost: true on the Agent and read result.costs for its cost snapshot. Use a shared CostTracker and queryCosts() for session or historical queries. An exported trace or metric is a bounded projection of these records. The legacy cost.tracked event carries a replacement run total. A later total replaces the previous value for that run. Do not add each event or combine parent totals with the same child charges. Canonical assessment events use stable IDs and revisions so corrections can replace selected costs without duplicate spend. Missing usage or pricing is not zero. Keep incomplete status visible in dashboards, and retain the accounting ledger separately from telemetry queues. See cost and tracing patterns.