Observability sinks

Every run emits a typed AgentfootprintEvent stream. Where that stream goes is a port with adapters, exactly like memory or hosting: the agent loop never knows whether it is feeding CloudWatch, an OTel collector, a file, or nothing.

The port

interface ObservabilityStrategy extends BaseStrategy {
  readonly capabilities: ObservabilityCapabilities;
  exportEvent(event: AgentfootprintEvent): void;
}

Two members of its own, six inherited — and only two of the eight are required:

Two laws govern exportEvent, and they are what make a bad sink survivable:

exportEvent MUST be sync void. Buffer internally; drain in flush().

MUST NOT throw. Errors caught and routed to _onError at the dispatch layer; one bad strategy never breaks the agent loop.

Who calls flush() and stop()

Three doors, since 8.12.0: the handle enable.* returns (handle.flush() / handle.stop()), agent.shutdown(), and a standingAgent closing with its default shutdown: 'flush'. agent.run() never flushes — that part is unchanged, and it is why a batching exporter still needs one of the three at process end.

Mounting one

import { agentcoreObservability } from 'agentfootprint/observe';

const handle = agent.enable.observability({
  strategy: agentcoreObservability({ region: 'us-west-2', logGroupName: '/agentfootprint/assistant' }),
});

ObservabilityEnableOptions is { strategy?, tier?, sampleRate?, detach?, flushOn? }.

Axis 1 — which sink

All on agentfootprint/observe:

agentcoreObservability is a thin wrapper over the CloudWatch base — the only difference is the strategy name. That is stated here rather than implied, because it tells you the two rows have the same reliability, not merely similar shapes.

otelObservability takes your tracer rather than bundling an SDK: OTel's SDK is heavyweight and exporter-specific, and forcing one would defeat the portability the standard exists for. When an injected tracer's spans do not implement addEvent, the adapter falls back to flattened ${eventName}.${key} attributes — degraded (last-write-wins) but never silently dropped.

Google Cloud — the same adapter, pointed at telemetry.googleapis.com

Google's Telemetry API accepts standard OTLP, and Google's own migration guide recommends moving off the Cloud Trace exporter because its proprietary transform can lose data. So there is no googleCloudTracer() factory and there is not going to be one: it would construct a TracerProvider from packages you install either way and attach a GoogleAuth header — about twenty lines of wiring behind four new optional peer dependencies. otelObservability() already takes the tracer.

const auth = new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/cloud-platform' });
const client = await auth.getClient();

const exporter = new OTLPTraceExporter({
  url: 'https://telemetry.googleapis.com',      // regional: telemetry.<REGION>.rep.googleapis.com
  // TLS *and* renewable Google call credentials — not TLS plus copied headers.
  credentials: credentials.combineChannelCredentials(
    credentials.createSsl(),
    credentials.createFromGoogleCredential(client),
  ),
});

plus OTEL_RESOURCE_ATTRIBUTES=gcp.project_id=<PROJECT_ID> and GOOGLE_CLOUD_QUOTA_PROJECT=<PROJECT_ID>. Google's console renders the GenAI views from the OpenTelemetry GenAI semantic conventions — the same gen_ai.* attributes this adapter already emits — once you opt in with OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental. There is no auto-instrumentation for @google/genai on npm, so agentfootprint's own provider hooks are the instrumentation.

Axis 2 — composition

composeObservability(children) returns one ObservabilityStrategy named 'compose', whose capabilities are the OR of its children's:

import { composeObservability, agentcoreObservability, otelObservability } from 'agentfootprint/observe';

agent.enable.observability({
  strategy: composeObservability([
    agentcoreObservability({ region: 'us-west-2', logGroupName: '/agentfootprint/assistant' }),
    otelObservability({ tracer }),
  ]),
});

exportEvent fans out to every child; flush() and stop() reach all of them. One child failing does not stop the others — the passive-recorder rule. Siblings exist for the other strategy kinds: composeCost, composeLiveStatus, composeLens.

Axis 3 — delivery timing

detach decides when the sink's work happens relative to the agent loop:

driver is required — there is no library default, because the right one is an environment fact. Drivers come from footprintjs/detach: microtaskBatchDriver (cross-runtime, the usual in-process pick), setImmediateDriver (Node), setTimeoutDriver (configurable delay), immediateDriver, plus factories createSendBeaconDriver (browser, survives page-unload) and createWorkerThreadDriver.

import { microtaskBatchDriver } from 'footprintjs/detach';

agent.enable.observability({
  strategy: agentcoreObservability({ region: 'us-west-2', logGroupName: '/agentfootprint/assistant' }),
  detach: { driver: microtaskBatchDriver, mode: 'forget' },   // keep the loop unblocked
});

Axis 4 — volume

tier is 'minimal' | 'standard' | 'firehose', default 'standard', and filters which event types reach the strategy. sampleRate (0–1) thins what is left.

relevantEventTypes on the strategy itself is the finer instrument: the dispatcher will not even forward types outside that set.

Which conversation an event belongs to

EventMeta.sessionId (9.4.0) rides beside runId — one session produces many runs, and an event needs to say which of each it is. The CloudWatch and AgentCore adapters serialize the whole envelope, so it arrives without their knowing about it.

await agent.run(message, { sessionId });   // or let standingAgent do it for you

standingAgent sets it on both run() and resume() from the request's own session id. It is never derived, guessed, or defaulted to the runId: an anonymous request has no session, and an absent key and an invented one are different facts. Worked example: Exporters.

Who the run was for — the audit wire (9.11.0)

The stream has always said what happened and when. EventMeta.principal and EventMeta.tenant are the who, and together the three are an audit record rather than a debug log.

await agent.run(message, { identity: { tenant: 'acme', principal: 'alice@acme.test', conversationId } });

Every event of that run carries meta.principal and meta.tenant.

They are stamped only from an identity a caller NAMED — run({ identity }) or run(input, { identity }), the same tuple memory and the permission gate scope on. Three things deliberately do not produce them:

Which sinks carry it

Two kinds of adapter, and the difference decides the answer:

An envelope-serializing sink inherits any new meta field for free; a span-mapping one does not, and a doc that assumed otherwise would have been wrong about two of the six. OTel uses agentfootprint.* names rather than enduser.id: the semantic convention for that attribute has moved once already, and quietly claiming a convention we do not track is worse than a name that says whose field it is.

What a recording keeps

recordRun(runner, options?) produces the canonical Recording — { snapshot, events, structure } — which is what an offline viewer replays.

Embeddings are summarized, not kept. By default every embedding / embeddings field — in boundary payloads, in the snapshot's subflow results, in tool results riding the event stream — is replaced with { dims, norm } when the recording is frozen. dims is the dimensionality; norm is the L2 norm rounded to four decimals — a checksum, not an operand.

The measurement behind the default: one retrieval turn's recording weighed 2.76 MB, about 1.1 MB of it embedding floats. Nothing that renders a recording reads those floats, and the retrieval evidence a debugger actually needs — score, passage, document, rejected candidates — carries no vectors and is untouched. Set recordEmbeddings: true only when a consumer genuinely replays raw vectors offline.

The same option exists on BoundaryRecorder, where it applies at capture time rather than at freeze time.

Status

Next

• Identity & credentials — where the actor on the wire comes from
• Observability — the event taxonomy and the three workflows
• Exporters: AgentCore & OTEL — step-by-step wiring for both
• Offline replay — what a recording is for
• AWS & Bedrock AgentCore — the worked provider
• Google Cloud & Gemini — the OTLP recipe in full, and the rest of that column