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.
recordEventqueues 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
onErrorandscope.stats(). - Retries with exponential backoff and jitter on network errors,
429and5xx. A401or other4xxis 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. AbeforeExithook flushes if you forget. The background timer never keeps your process alive. - Transport. Events go to the hosted service over
https. A self-hostedendpointmust also behttps, exceptlocalhost.
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.