TraceRoot SDK is a clean and principled package built upon OpenTelemetry with enhanced debugging and tracing experience. It provides smart logging and tracing with minimal setup and code changes.

You can follow the docs here to get more details and have a deeper understanding of the TraceRoot SDK.

python3.11 -m venv venv
source venv/bin/activate
pip install traceroot
# or install the latest version from the source code
pip install -e .

Cloud mode is to use TraceRoot's cloud service to store the logs and traces.

For the TraceRoot SDK to work with your application, you need to set up some environment variables with some credentials.

Please visit TraceRoot.AI to get the credentials.

You also need to input following information to traceroot.init(...) at the beginning of your entry file for your Python program to have a full experience:

traceroot.init(
    token="traceroot-********************************",
    service_name="sdk-example-service",
    github_owner="traceroot-ai",
    github_repo_name="traceroot-sdk",
    github_commit_hash="main"
)

Or you can just put them in a yaml file called .traceroot-config.yaml in the root of your project:

token: "traceroot-********************************"
service_name: "sdk-example-service"
github_owner: "traceroot-ai"
github_repo_name: "traceroot-sdk"
github_commit_hash: "main"

• token is the token for the TraceRoot API.
• service_name is the name of the service or program you are going to keep track of.
• github_owner is the owner of the GitHub repository.
• github_repo_name is the name of the GitHub repository.
• github_commit_hash is the commit hash of the GitHub repository.
• You can disable the cloud export of spans and logs by setting the enable_span_cloud_export and enable_log_cloud_export to false. Notice that if you disable the cloud export of spans, the cloud export of logs will also be disabled.
• You can also choose to whether export the spans and logs to the console by setting the enable_span_console_export and enable_log_console_export to true or false.

The GitHub information is optional. If you do not provide them, the TraceRoot SDK will not be able to provide you with the GitHub information in the logs.

You can also provide the configuration in the environment variables. The environment variables are the same as the configuration parameters, but with the prefix TRACEROOT_. For example, you can set the TRACEROOT_TOKEN environment variable to the token for the TraceRoot API.

You can run following example to see how to use the environment variables:

TRACEROOT_TOKEN=traceroot-* TRACEROOT_SERVICE_NAME=new_name TRACEROOT_ENABLE_LOG_CLOUD_EXPORT=1 python3 examples/override_example.py

The priority of the configuration is as follows:

1. Environment variables
2. traceroot.init(...) parameters
3. .traceroot-config.yaml file

For example, if you provide the configuration in the environment variables, the configuration in the .traceroot-config.yaml file will be overridden.

Local mode is to use TraceRoot's local database to store the logs and traces.

You need to set up a local database to store the logs and traces by running the jaeger docker container.

Download the Jaeger Docker image:

docker run cr.jaegertracing.io/jaegertracing/jaeger:2.8.0 --help

Run the Jaeger Docker container:

docker stop jaeger || true && docker rm jaeger || true && docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 14268:14268 \
  -p 14250:14250 \
  -p 4317:4317 \
  -p 4318:4318 \
  cr.jaegertracing.io/jaegertracing/jaeger:2.8.0

docker logs -f jaeger

Then you need to use following code to initialize the TraceRoot SDK in local mode:

traceroot.init(
    service_name="sdk-example-service",
    github_owner="traceroot-ai",
    github_repo_name="traceroot-sdk",
    github_commit_hash="main"
    local_mode=True
)

Or you can just put them in a yaml file called .traceroot-config.yaml in the root of your project:

service_name: "sdk-example-service"
github_owner: "traceroot-ai"
github_repo_name: "traceroot-sdk"
github_commit_hash: "main"
local_mode: true

There is an example of using the configuration file for the local mode in the .traceroot-config-local.yaml file.

You can also set the following settings in the .traceroot-config.yaml file:

• enable_span_console_export: Whether to enable console export and print the spans to the console.
• enable_log_console_export: Whether to enable console export and print the logs to the console.

For an end-to-end example that uses the TraceRoot SDK for a multi-agent system, please refer to the Multi-agent System with TraceRoot SDK.

The source code of the multi-agent system example is available in traceroot-examples/examples/multi_agent.

If you use our exploratory TraceRoot SDK in your research, please cite the following paper:

@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.