ax-agent-observability

AxAgent Observability Rules (@ax-llm/ax)

Use this skill when an agent needs runtime visibility, progress reporting, tracing, usage accounting, or chat-log access. For ordinary agent setup use ax-agent. For RLM runtime policy use ax-agent-rlm. For memories and dynamic skill loading use ax-agent-memory-skills.

Choose The Smallest Hook

• Need a quick prompt/runtime trace during development -> start with debug: true.
• Need structured per-turn code, raw runtime result, formatted output, provider thoughts, or actor stage -> use actorTurnCallback.
• Need context-pressure and compaction telemetry -> use onContextEvent.
• Need real-time task progress emitted by actor code -> use agentStatusCallback.
• Need every runtime function call before execution -> use onFunctionCall.
• Need model prompts/responses after a run -> use getChatLog().
• Need centralized chat/embed usage across APIs, users, agents, and services -> use axGlobals.onUsage plus usageContext.
• Need token usage by actor/responder -> use getUsage() and resetUsage().
• Need usage split by context and task stages -> use getStagedUsage().
• Need Ax program traces -> use getTraces().
• Do not add multiple hooks unless the user clearly needs each output stream.

Global Runtime Defaults

OpenTelemetry and debug defaults come from the shared Ax runtime surface:

import { axGlobals, axCreateDefaultColorLogger } from '@ax-llm/ax';
import { metrics, trace } from '@opentelemetry/api';

axGlobals.rateLimiter = async (next, info) => next();
axGlobals.tracer = trace.getTracer('agent-app');
axGlobals.meter = metrics.getMeter('agent-app');
axGlobals.debug = true;
axGlobals.logger = axCreateDefaultColorLogger();
axGlobals.onUsage = (event) => usageQueue.enqueue(event);

Each agent run snapshots these globals. A forward-scoped rateLimiter, tracer, or meter overrides agent defaults, child-generator defaults, service hooks, and globals for that invocation. Ax carries it through the distiller, executor, responder, repeated actor turns, citation repair, built-in llmQuery, context-map work, checkpoint/tombstone summaries, and other direct internal model calls without mutating child programs or leaking across concurrent runs.