A TypeScript SDK for TraceRoot tracing and logging.
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.
The trace is built upon OpenTelemetry, and the traces will be sent to TraceRoot's own endpoint.
The logger is based on Winston, designed for integration with CloudWatch. And currently the logs will be stored in AWS.
npm install traceroot-sdk-ts@latest
At first you need to create a traceroot.config.ts
file in the root of your project:
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;
An example is shown in the traceroot.config.ts file.
If you don't have TypeScript node and runtime installed, you can also use JavaScript config:
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;
An example is shown in the traceroot.config.js file.
Sometimes it's quite hard to find the config file in the project root due to webpack or other bundlers. You can set the TRACEROOT_CONFIG_PATH
environment variable to indicate the location of the config file.
export TRACEROOT_CONFIG_PATH=/path/to/your/traceroot.config.ts
You can enable the cloud export of spans and logs by setting the enable_span_cloud_export
and enable_log_cloud_export
to true
. By default, all those are set to true
. If you set enable_span_cloud_export
to false
, the cloud export of spans will be disabled (it will also disable the cloud export of logs). If you set enable_log_cloud_export
to false
, only the cloud export of logs will be disabled.
You can enable the console export of spans and logs by setting the enable_span_console_export
and enable_log_console_export
to true
. Enable them will print out spans or logs in the console.
Then you can use the traceroot.traceFunction
to trace your functions:
import * as traceroot from 'traceroot-sdk-ts';
const logger = traceroot.getLogger();
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);
});
Or just use the decorator such as:
import * as traceroot from 'traceroot-sdk-ts';
const logger = traceroot.getLogger();
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);
});
You can also log with some metadata and make it searchable in the TraceRoot UI via:
logger.info({ requestId, userId }, `Making another request`);
// or
logger.info({ userId }, `Making another request`, { requestId });
If you choose to log with metadata, you can search for it in the TraceRoot UI. Here is an example:
import * as traceroot from 'traceroot-sdk-ts';
const logger = traceroot.getLogger();
async function main() {
const makeRequest = traceroot.traceFunction(
async function makeRequest(requestId: string, userId: string): Promise<string> {
// This will store the userId as a metadata attribute in the span so you can search for it in the TraceRoot UI
logger.info({ userId }, `Making request: ${requestId}`);
logger.debug('Pure debug message');
await makeAnotherRequest(requestId, userId);
// Simulate some async work
await new Promise(resolve => setTimeout(resolve, 1000));
return `Request ${requestId} completed`;
},
{ spanName: 'makeRequest', traceParams: true }
);
const result = await makeRequest('123', 'user123');
logger.info(`Request result: ${result}`); // This will not be shown in TraceRoot UI
}
async function makeAnotherRequest(requestId: string, userId: string) {
await new Promise(resolve => setTimeout(resolve, 1000));
// This will store the requestId and userId as a metadata attribute in the span so you can search for it in the TraceRoot UI
logger.info({ userId, requestId }, `Making another request`);
}
main().then(async () => {
await traceroot.forceFlushTracer();
await traceroot.shutdownTracing();
await traceroot.forceFlushLogger();
await traceroot.shutdownLogger();
process.exit(0);
});
In the example above, you can search for requestId
in the TraceRoot UI by
- Clicking the search bar category icon and select
log
. - Type
requestId
in the first input box. - Select
=
and in the second input box type123
for this example. - Type Enter button to add that criteria to search. Then you can see all traces or workflows with
requestId
as123
logging metadata in the TraceRoot UI. - Notice that within the same trace decorator or
traceFunction
call, a new logging metadata will replace the previous one. For example, if you have twologger.info
calls with first one havingrequestId
as123
and the second one havingrequestId
as456
, the second one will replace the first one at last. For now, to avoid this, you may need to add a newtraceFunction
call or a newtrace
decorator.
More details can be found in the examples.
You can run following examples after modifying the traceroot.config.ts
file:
npx ts-node --transpile-only examples/simple-example-sync.ts # Not working for now
npx ts-node --transpile-only examples/simple-example.ts
npx ts-node --transpile-only examples/simple-example-decorator.ts
npx ts-node --transpile-only examples/example.ts
npx ts-node --transpile-only examples/example-decorator.ts
npx ts-node --transpile-only examples/child-logger-example.ts
npx ts-node --transpile-only examples/log-level-example.ts
npm install
npm run build
npm run format
npm run lint --fix
npx prettier --write src tests examples
npx prettier --write [JS-CONFIG-FILE]
npm run test # Run tests
npm test -- tests/logger/logger.pathProcessing.test.ts # Run a specific test
npm login
npm run build
npm pack --dry-run
# Alpha (for testing)
# For next alpha version
npm version prerelease --preid=alpha # 0.0.1-alpha.1
npm publish --tag alpha
npm dist-tag ls traceroot-sdk-ts
# Add the latest version to the latest tag
npm dist-tag add traceroot-sdk-ts@0.0.1-alpha.[version] latest
npm view traceroot-sdk-ts
# Install the alpha version
npm install traceroot-sdk-ts@alpha
If you find our exploratory TraceRoot useful in your research, please consider citing:
@article{traceroot_2025,
title={TraceRoot Is All You Need for Debugging and Tracing},
author={Zecheng Zhang and Xinwei He},
year = {2025},
publisher = {GitHub},
url = {https://github.com/traceroot-ai/traceroot}
}
Please reach out to founders@traceroot.ai or visit TraceRoot.AI if you do not have these credentials or have any questions.