​
TraceRoot SDK for TypeScript

A TypeScript SDK for TraceRoot tracing and logging.

​
Introduction

This SDK allows you to trace functions and utilizes TraceRoot’s own logger within the TraceRoot trace. It captures all the context designed for advanced debugging of AI agents.

​
OpenTelemetry

The trace is built upon OpenTelemetry, and the traces will be sent to TraceRoot’s own endpoint.

​
Winston

The logger is based on Winston, designed for integration with CloudWatch so currently the logs will be stored in AWS.

​
Installation

Please install the SDK with the latest version: 
npm install traceroot-sdk-ts@latest

​
Configuration

At first you need to create a traceroot.config.ts file in the root of your project:
  1. You should specify the service name, which is the name of the service you are tracing.
  2. GitHub related information is optional. If you specified, you also need to put GitHub token to the integration on the TraceRoot.AI platform.
  3. The token is required and you can generate one from the TraceRoot.AI platform integration page.
  4. The enable_span_console_export and enable_log_console_export are optional and you can enable them to see the spans and logs in the console. We recommend to not enable span console export as it make the terminal output too verbose.
  5. The local_mode is optional and you can enable it to store all data locally, which is using the Jaeger backend and SQlite for data storage. More details please checkout our open sourced traceroot project.
Here is an example of the traceroot.config.ts file: 
import type { TraceRootConfigFile } from 'traceroot-sdk-ts/src/config';

const config: TraceRootConfigFile = {
  // Basic service configuration
  service_name: 'ts-example',
  github_owner: 'traceroot-ai',
  github_repo_name: 'traceroot-sdk-ts',
  github_commit_hash: 'main',

  // Your environment configuration such as development, staging, production
  environment: 'development',

  // Token configuration
  // This is the token you can generate from the TraceRoot.AI website
  token: 'traceroot-***********************',

  // Whether to enable console export of spans and logs
  enable_span_console_export: false,
  enable_log_console_export: true,

  // Local mode that whether to store all data locally
  local_mode: false,
};
export default config;
Notice that to use the traceroot.config.ts file, you need to ensure you have TypeScript installed so that the SDK can correctly parse the config file. An example is shown in this package.json file: 
"dependencies": {
    "@aws-sdk/node-http-handler": "^3.370.0",
    "next": "15.4.5",
    "react": "19.1.0",
    "react-dom": "19.1.0",
    "traceroot-sdk-ts": "0.0.1-alpha.7",
    "undici": "^7.13.0",
    "ts-node": "^10.9.2",
    "typescript": "^5"
},
A real example is here. If you don’t have TypeScript node and runtime installed, you can use the JavaScript config instead: 
const config = {
  // Basic service configuration
  service_name: 'js-example',
  github_owner: 'traceroot-ai',
  github_repo_name: 'traceroot-sdk',
  github_commit_hash: 'main',

  // Your environment configuration
  // development, staging, production
    environment: 'development',

  // Token configuration
  token: 'traceroot-*',

  // Whether to enable console export of spans and logs
  enable_span_console_export: false,
  enable_log_console_export: true,

  // Local mode that whether to store all data locally
  local_mode: false,
};

module.exports = config;
A real example is here.

​
Usage

TraceRoot SDK for TypeScript Usage Please use the image above and descriptions below to understand what’s the effect of traceroot.traceFunction, function name, service name, environment, and logging.

​
Tracing Functions

Then you can use the traceroot.traceFunction to trace your functions. We require that you at least need to call this function to the entry point of your application. For example, if you have a workflow called, you can wrap around your workflow with this to allow to track tracing information. If you add more traceroot.traceFunction to the children function of the parent function, the tracing information will have a nicer tree structure, which allows better performance of the AI agents to analyze the tracing and logging information.

​
Function Name

If you specify the spanName parameter, the span name will be used as the name of the function that will be shown in the TraceRoot.AI platform.

​
Logging

Only within one a traceroot.traceFunction, you can use the traceroot logger to log the information, including logger.info, logger.error, logger.warn, logger.debug and logger.critical. Notice that within the traceroot.traceFunction, the log will be correctly tracked and you can see the log in the TraceRoot.AI platform by clicking each workflows of the tracing information. Here is an example of how to use the traceroot.traceFunction and the logger: 
import * as traceroot from 'traceroot-sdk-ts';

const logger = traceroot.get_logger();

async function main() {
  const greet = traceroot.traceFunction(
    async function greet(name: string): Promise<string> {
      logger.info(`Greeting inside traced function: ${name}`);
      // Simulate some async work
      await new Promise(resolve => setTimeout(resolve, 100));
      return `Hello, ${name}!`;
    },
    { spanName: 'greet' }
  );

  const result = await greet('world');
  logger.info(`Greeting result: ${result}`);
}

main().then(async () => {
  await traceroot.forceFlushTracer();
  await traceroot.shutdownTracing();
  await traceroot.forceFlushLogger();
  await traceroot.shutdownLogger();
  process.exit(0);
});
Notice that you need to call those flush and shutdown functions to ensure the logging and tracing data is sent to the TraceRoot.AI platform. For the traceroot.traceFunction, you can replace it with the decorator such as @traceroot.trace({ spanName: 'greet' }): 
import * as traceroot from 'traceroot-sdk-ts';

const logger = traceroot.get_logger();

class GreetingService {
  // @ts-ignore - TypeScript has strict typing issues with decorators, but this works at runtime
  @traceroot.trace({ spanName: 'greet' })
  async greet(name: string): Promise<string> {
    logger.info(`Greeting inside traced function: ${name}`);
    // Simulate some async work
    await new Promise(resolve => setTimeout(resolve, 1000));
    return `Hello, ${name}!`;
  }
}

async function main() {
  const service = new GreetingService();
  const result = await service.greet('world');
  logger.info(`Greeting result: ${result}`); // This will not be shown in TraceRoot UI
}

main().then(async () => {
  await traceroot.forceFlushTracer();
  await traceroot.shutdownTracing();
  await traceroot.forceFlushLogger();
  await traceroot.shutdownLogger();
  process.exit(0);
});

​
Example

A real example by using the TraceRoot SDK within Next.js api route is here.