What is it?

@amsterdamdatalabs/traces is the canonical tracing contract for the enact-os observability stack. It provides:

• Payload schemas — typed event payloads for every span kind: LLM calls, tool calls, memory reads/writes, proc-tap, agent lifecycle, hook-fired, cache hits, and hand runs
• Span attribute constants — enact.* and llm.* extension attributes on top of the OpenInference semantic conventions
• Emit — a zero-dependency emitEvent() that writes NDJSON to the watchdog dir and publishes to Apache Iggy in parallel

Used by enact-gateway, enact-factory, enact-wiki, enact-agent, and enact-watchdog.

Installation

npm install @amsterdamdatalabs/traces

Usage

Emit a trace event

import { emitEvent } from '@amsterdamdatalabs/traces/emit';
import type { EnactRawV1Event } from '@amsterdamdatalabs/traces';

const event: EnactRawV1Event = {
  schema: 'enact.raw.v1',
  ts: Date.now(),
  span_kind: 'llm_call',
  payload: { /* ... */ },
};

await emitEvent(event, { ndjsonFile: 'factory-events.ndjson' });

Use span attribute constants

import {
  ENACT_ROUTING_TIER,
  ENACT_PROVIDER,
  LLM_ENDPOINT_KEY,
} from '@amsterdamdatalabs/traces/conventions';

span.setAttribute(ENACT_ROUTING_TIER, 'standard');
span.setAttribute(ENACT_PROVIDER, 'anthropic');

Use typed payloads

import type { LlmCallPayload } from '@amsterdamdatalabs/traces/payloads';

const payload: LlmCallPayload = {
  model: 'claude-sonnet-4-6',
  input_tokens: 1200,
  output_tokens: 340,
};

Sub-path exports

| Import | Contents | |--------|----------| | @amsterdamdatalabs/traces | All types, payloads, conventions, and emit | | @amsterdamdatalabs/traces/conventions | enact.* and llm.* span attribute constants | | @amsterdamdatalabs/traces/payloads | Typed payload schemas for each span kind | | @amsterdamdatalabs/traces/emit | emitEvent() — NDJSON + Iggy publish |

Environment variables

| Variable | Default | Purpose | |----------|---------|---------| | ENACT_WATCHDOG_DIR | .enact/watchdog | Directory for NDJSON output files | | IGGY_HTTP_URL | http://127.0.0.1:43214 | Apache Iggy HTTP endpoint | | IGGY_HTTP_ACCESS_TOKEN | — | Bearer token for Iggy auth | | IGGY_HTTP_USERNAME | iggy | Iggy username (if no token) | | IGGY_HTTP_PASSWORD | iggy | Iggy password (if no token) | | ENACT_OBSERVABILITY_DEBUG | — | Log emit errors to stderr |

License

Proprietary — Copyright © 2026 Amsterdam Data Labs.