Skip to main content
The TraceRoot TypeScript SDK provides automatic and manual instrumentation for AI agents using OpenTelemetry.

​
Instrumentation

Pass module instances to initialize() to instrument all calls automatically: 
import OpenAI from 'openai';
import { TraceRoot } from '@traceroot-ai/traceroot';

TraceRoot.initialize({
  instrumentModules: { openAI: OpenAI },
});

const openai = new OpenAI();

​
The Observe Wrapper

Wrap any async function to create a span: 
import { observe } from '@traceroot-ai/traceroot';

const result = await observe({ name: 'my_function', type: 'tool' }, async () => {
  return doWork('your input here');
});

​
Parameters

ParameterTypeDefaultDescription
namestringfunction nameSpan name
type'span' | 'agent' | 'tool' | 'llm''span'Span kind — 'agent' for multi-step agents, 'tool' for function calls, 'llm' for model inference, 'span' for generic
metadataRecord<string, unknown>—Static metadata to attach
tagsstring[]—Tags to attach

​
Setting Trace Context

Use usingAttributes() to set user and session context for all spans created within a block: 
import { usingAttributes } from '@traceroot-ai/traceroot';

await usingAttributes(
  {
    sessionId: 'conv-123',
    userId: 'user-456',
    tags: ['production', 'v2'],
    metadata: { feature: 'chat' },
  },
  async () => {
    // All spans here inherit the attributes above
    await runAgent('What is the weather?');
  },
);

​
Parameters

ParameterTypeDescription
sessionIdstringSession / conversation ID
userIdstringUser identifier
tagsstring[]Tags to attach to all spans
metadataRecord<string, unknown>Arbitrary metadata

​
Updating Spans and Traces

Update the current span or trace programmatically: 
import { updateCurrentSpan, updateCurrentTrace } from '@traceroot-ai/traceroot';

await observe({ name: 'my_agent', type: 'agent' }, async () => {
  updateCurrentSpan({
    input: { query: userInput },
    output: { response: agentOutput },
    metadata: { model: 'gpt-4o' },
  });

  updateCurrentTrace({
    userId: 'user-123',
    sessionId: 'sess-456',
    tags: ['prod'],
    metadata: { plan: 'pro' },
  });
});

​
updateCurrentSpan Parameters

ParameterTypeDescription
inputunknownInput data
outputunknownOutput data
metadataRecord<string, unknown>Custom metadata

​
updateCurrentTrace Parameters

ParameterTypeDescription
userIdstringUser identifier
sessionIdstringSession identifier
tagsstring[]Tags for the trace
metadataRecord<string, unknown>Trace-level metadata

​
Environment Variables

VariableDefaultDescription
TRACEROOT_API_KEY(required)API key
TRACEROOT_HOST_URLhttps://app.traceroot.aiAPI endpoint
TRACEROOT_ENABLEDtrueEnable/disable tracing
TRACEROOT_ENVIRONMENT—Deployment environment tag (e.g. production, staging)
TRACEROOT_GIT_REPOauto-detectedGit repository (owner/repo)
TRACEROOT_GIT_REFauto-detectedGit reference