Skip to main content

​
Python SDK for TraceRoot

​
Introduction

The TraceRoot Python SDK is a lightweight wrapper around OpenTelemetry, optimized for ease of use.

​
Installation

pip install traceroot

​
Environment Setup

Create a TraceRoot token from the dashboard, and add it to your backend .env file.
.env
# The token for the TraceRoot API
TRACEROOT_TOKEN=your_traceroot_token_here

# The name of the service you are tracking
TRACEROOT_SERVICE_NAME=traceroot

# The owner of the GitHub repository
TRACEROOT_GITHUB_OWNER=github_owner

# The name of the GitHub repository
TRACEROOT_GITHUB_REPO_NAME=github_repo_name

# The commit hash of the GitHub repository
TRACEROOT_GITHUB_COMMIT_HASH=main

# Enable cloud export of spans (default: `true`)
TRACEROOT_ENABLE_SPAN_CLOUD_EXPORT=true

# Enable cloud export of logs (default: `true`)
TRACEROOT_ENABLE_LOG_CLOUD_EXPORT=true

# Enable console export of spans (default: `false`)
TRACEROOT_ENABLE_SPAN_CONSOLE_EXPORT=false

# Enable console export of logs (default: `true`)
TRACEROOT_ENABLE_LOG_CONSOLE_EXPORT=true

# Enable additional tracer loggings for internal debugging (default: `false`)
TRACEROOT_TRACER_VERBOSE=false

# Enable additional logger logging for internal debugging (default: `false`)
TRACEROOT_LOGGER_VERBOSE=false
Then run 
from dotenv import load_dotenv
import traceroot

load_dotenv()  # load variables from .env into os.environ
traceroot.init()
Important: For best results, call traceroot.init() as early as possible in your application. Ideally before you import other TraceRoot components in any source files, e.g. 
from traceroot.logger import get_logger
logger = get_logger()
This ensures that tracing and logging are properly initialized.

​
Examples

Uses @traceroot.trace() for traces and TraceRoot logger similar to the default Python logger. 
import os
from typing import Dict

import traceroot
import uvicorn
from dotenv import find_dotenv, load_dotenv
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel

# Load environment variables
dotenv_path = find_dotenv()
if dotenv_path:
    load_dotenv(dotenv_path)

# Initialize TraceRoot
traceroot.init()
from traceroot.integrations.fastapi import connect_fastapi
from traceroot.logger import get_logger

logger = get_logger()

# Create FastAPI app and connect TraceRoot
app = FastAPI(title="My TraceRoot App")
connect_fastapi(app)

class QueryRequest(BaseModel):
    message: str

@app.post("/process")
@traceroot.trace()
async def process_request(request: QueryRequest) -> Dict[str, str]:
    logger.info(f"Processing request: {request.message}")
    try:
        # Your business logic here
        result = await process_message(request.message)
        logger.info("Request processed successfully")
        return {"status": "success", "response": result}
    except Exception as e:
        logger.error(f"Error processing request: {str(e)}")
        raise HTTPException(status_code=500, detail=f"Processing failed: {str(e)}")

@traceroot.trace()
async def process_message(message: str) -> str:
    logger.info(f"Processing message: {message}")
    # Simulate some work
    processed = f"Processed: {message}"
    return processed

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

​
Development Installation

If you want to contribute or use the latest features, install from source: 
git clone https://github.com/traceroot-ai/traceroot-sdk.git
cd traceroot
pip install -e .