traceroot 0.0.4a9

The SDK that revolutionizes debugging and tracing.

TraceRoot SDK

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.

Quick Start

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

Installation

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

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

Prerequisite

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.

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.

Local Mode

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

Prerequisite

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.

Other Settings

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.

Examples

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.

Citation

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}
}

Contact Us

Please reach out to [e-mail] or visit TraceRoot.AI if you do not have these credentials or have any questions.