\n @amsterdamdatalabs/traces\n
\n\n Shared OpenInference tracing types, span attribute constants, and event emit for enact-os packages\n
\n\n## What is it?\n\n`@amsterdamdatalabs/traces` is the canonical tracing contract for the enact-os observability stack. It provides:\n\n- **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\n- **Span attribute constants** — `enact.*` and `llm.*` extension attributes on top of the OpenInference semantic conventions\n- **Emit** — a zero-dependency `emitEvent()` that writes NDJSON to the watchdog dir and publishes to Apache Iggy in parallel\n\nUsed by `enact-gateway`, `enact-factory`, `enact-wiki`, `enact-agent`, and `enact-watchdog`.\n\n## Installation\n\n```bash\nnpm install @amsterdamdatalabs/traces\n```\n\n## Usage\n\n### Emit a trace event\n\n```typescript\nimport { emitEvent } from '@amsterdamdatalabs/traces/emit';\nimport type { EnactRawV1Event } from '@amsterdamdatalabs/traces';\n\nconst event: EnactRawV1Event = {\n schema: 'enact.raw.v1',\n ts: Date.now(),\n span_kind: 'llm_call',\n payload: { /* ... */ },\n};\n\nawait emitEvent(event, { ndjsonFile: 'factory-events.ndjson' });\n```\n\n### Use span attribute constants\n\n```typescript\nimport {\n ENACT_ROUTING_TIER,\n ENACT_PROVIDER,\n LLM_ENDPOINT_KEY,\n} from '@amsterdamdatalabs/traces/conventions';\n\nspan.setAttribute(ENACT_ROUTING_TIER, 'standard');\nspan.setAttribute(ENACT_PROVIDER, 'anthropic');\n```\n\n### Use typed payloads\n\n```typescript\nimport type { LlmCallPayload } from '@amsterdamdatalabs/traces/payloads';\n\nconst payload: LlmCallPayload = {\n model: 'claude-sonnet-4-6',\n input_tokens: 1200,\n output_tokens: 340,\n};\n```\n\n## Sub-path exports\n\n| Import | Contents |\n|--------|----------|\n| `@amsterdamdatalabs/traces` | All types, payloads, conventions, and emit |\n| `@amsterdamdatalabs/traces/conventions` | `enact.*` and `llm.*` span attribute constants |\n| `@amsterdamdatalabs/traces/payloads` | Typed payload schemas for each span kind |\n| `@amsterdamdatalabs/traces/emit` | `emitEvent()` — NDJSON + Iggy publish |\n\n## Environment variables\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `ENACT_WATCHDOG_DIR` | `.enact/watchdog` | Directory for NDJSON output files |\n| `IGGY_HTTP_URL` | `http://127.0.0.1:43214` | Apache Iggy HTTP endpoint |\n| `IGGY_HTTP_ACCESS_TOKEN` | — | Bearer token for Iggy auth |\n| `IGGY_HTTP_USERNAME` | `iggy` | Iggy username (if no token) |\n| `IGGY_HTTP_PASSWORD` | `iggy` | Iggy password (if no token) |\n| `ENACT_OBSERVABILITY_DEBUG` | — | Log emit errors to stderr |\n\n## License\n\nProprietary — Copyright © 2026 Amsterdam Data Labs.\n","readmeFilename":"README.md"}