TypeScript SDK

Instrument your own agents. The package is @tracemason/sdk (packages/sdk-typescript); it is not published to npm yet, so install it from the workspace.

import { Tracemason } from "@tracemason/sdk";

const scope = new Tracemason({
  apiKey: process.env.TRACEMASON_API_KEY,
});

const session = await scope.startSession({
  agent: "research-agent",
  environment: "staging",
});

await session.recordEvent({
  type: "tool.execution",
  tool: "database.query",
  metadata: { operation: "SELECT", resource: "analytics" },
});

await session.end();
await scope.shutdown();

Create the key under Integrations → Ingestion keys.

Behaviour

  • Non-blocking. recordEvent queues the event and returns. Delivery is batched in the background (every 2 s, or when 100 events are waiting).
  • Never throws from recording. Delivery problems go to onError and scope.stats().
  • Retries with exponential backoff and jitter on network errors, 429 and 5xx. A 401 or other 4xx is not retried.
  • Bounded. At most 5,000 events are held; beyond that the oldest are dropped and counted.
  • Graceful shutdown. session.end() flushes; scope.shutdown() flushes and stops. A beforeExit hook flushes if you forget. The background timer never keeps your process alive.
  • Transport. Events go to the hosted service over https. A self-hosted endpoint must also be https, except localhost.

API

new Tracemason(options)

Option Default
apiKey TRACEMASON_API_KEY Ingestion key
endpoint TRACEMASON_ENDPOINT, then https://app.tracemason.com Only for a self-hosted server
allowMetadataKeys [] Extra metadata keys allowed to leave the process
flushIntervalMs 2000
maxBatchSize 100 Up to 500
maxQueueSize 5000
maxRetries 5 Per batch
onError — (error) => void
enabled true false makes the SDK a no-op

scope.startSession({ agent, agentType?, model?, environment?, repository?, branch? })

Returns a Session and records session.started.

session.recordEvent(input)

Field
type "tool.execution" (a finished tool call), "tool.requested", "error", or any dotted custom name
tool, category Tool name and action category (database.query, file.write, …)
outcome "success" (default for tool.execution), "failure", "blocked"
durationMs, errorType
files [{ path, operation }]
hosts Hostnames the action reached
usage { inputTokens, outputTokens, reportedCostUsd }
metadata Flat map; see below

session.tool(name, fn, fields?)

Runs fn, times it, records tool.completed or tool.failed, and re-throws on failure.

const rows = await session.tool("database.query", () => db.query(sql), { category: "database.query" });

session.reportError(error)

Records error.reported with the error's type only — never its message or stack.

Trace context

const ctx = session.traceContext();        // serialize and pass to another process
const same = scope.continueSession(ctx);   // events land in the same trace

Redaction

Metadata is filtered through an allowlist, then scanned for credential patterns. Keys not on the built-in list are dropped unless you add them with allowMetadataKeys. Nested objects and arrays are never sent. See What is collected.