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.