TypeScript SDK Observability

This page is for TypeScript and Node.js developers. You learn how tracing works in the @armoriq/sdk package, which options and environment variables control it, and which session calls are optional. The SDK builds one OpenTelemetry trace for each session, and sends it to ArmorIQ without telemetry code in your agent.

Install

You need an organization-scoped ArmorIQ API key. The SDK supports Node.js 18.19, and 20.6 or later. The LangChain and Strands adapters need Node.js 20 or later.

npm install @armoriq/sdk@0.8.23

Default setup

Tracing is on by default. With a framework adapter you add no tracing code. See Set up tracing for a complete example and Framework support for tested versions.

import { ArmorIQClient } from '@armoriq/sdk';
import { ArmorIQLangChain } from '@armoriq/sdk/dist/integrations/langchain';

const armoriq = new ArmorIQLangChain({
  client: new ArmorIQClient({ apiKey: process.env.ARMORIQ_API_KEY! }),
  mode: 'sdk',
});

const handler = await armoriq.forUser('alice@example.com', { goal: userMessage });
await agentExecutor.invoke({ input: userMessage }, { callbacks: [handler] });

Creating an ArmorIQClient also patches the openai and @anthropic-ai/sdk packages, so that direct calls are traced while a session is active. An ES module application must call instrumentOpenAI(OpenAI) itself. See Framework support.

Use a session without an adapter

If you call the session API yourself, the session is also the trace. Close it when it ends. The SDK does not close a session for you, and an open session does not export its root span.

const session = client.startSession({ mode: 'sdk' });
try {
  // startPlan, check, and report calls
} finally {
  await session.close();
}

• close(status?, taskOutcome?) ends the plan span and the root span, then sends the rest. The status can be ok (the default), error, denied, cancelled, timeout, or disconnected.
• dispose() is an alias for close(). Both are safe to call more than once and never throw.
• Close the session before the process stops. The SDK drains ended spans when the process exits normally, but it does not handle SIGINT, SIGTERM, or process.exit().

Optional session calls

None of these calls changes a policy decision. They never throw into your code.

Options

Pass observability to the client, to startSession, or to both. A session value overrides the same field from the client.

const client = new ArmorIQClient({
  apiKey: process.env.ARMORIQ_API_KEY!,
  observability: { captureMode: 'metadata' },
});

const quiet = client.startSession({ observability: { enabled: false } });

A local captureMode can only lower what the organization allows. It can never raise it. See Organization controls.

Environment variables

The TypeScript SDK has no setting for a custom certificate authority, a client certificate, a proxy, compression, or gRPC. Use a Collector for those. The full rules for endpoints and headers are in Choose who exports your traces.

Streaming usage

For OpenAI streaming chat requests, the SDK adds stream_options: { include_usage: true } so that token counts arrive in the last chunk. It hides that chunk from your code. If your request already sets stream_options, the SDK does not change it. Set streamUsage: false or ARMORIQ_OTEL_STREAM_USAGE=0 if your gateway rejects the option or you must keep the raw stream.

Transcript token usage

Token usage for a transcript is stored for each session, model, UTC date, and UTC hour. To add these tokens as model spans on the session trace, pass the native session:

await client.captureTranscriptTokens({
  transcriptPath: '/tmp/transcript.jsonl',
  product: 'armorclaude',
  sessionId: session.sessionId,
  otel: session.otelSession,
});

What the SDK records

The SDK adds these spans without code from you:

See What data is captured for fields and Data model for the attributes.

How it behaves

• The SDK reads your organization policy first. It fetches the capture policy with your API key. With armoriq and provider export, the SDK does not wait for the first answer, so spans that start before it arrives are not recorded. With external export, it waits up to 1.4 seconds for the first answer. If the policy is not available, the SDK records nothing.
• Failures are fail-open. A tracing error never changes an allow, hold, or block result, and never throws into your code.
• Closing is bounded. close() waits at most 1.5 seconds to send the rest.
• Export retries are bounded. The SDK retries 429, 502, 503, 504, and common network errors up to 5 times, then drops the batch. It respects Retry-After.
• No silent fallback. If an external setting is missing or invalid, the SDK exports nothing and logs nothing. It does not use localhost or ArmorIQ instead.
• Your trace context stays out of ArmorIQ spans. With armoriq and external export, the root span starts from an empty context. With provider export, it becomes a child of your active span.

Next steps

• Set up tracing
• Choose who exports your traces
• Troubleshoot missing traces