Versioning

Track different versions of your application to compare performance and behavior over time.

Why Version Your Traces?

Versioning your traces allows you to:

Compare performance metrics across different releases
Track regressions or improvements in LLM responses
Debug issues by filtering traces to specific versions
A/B test different prompts or configurations
Monitor the impact of model upgrades

Setting a Default Version

Set a default version during initialization to automatically tag all traces:

1
2
3
4
5
6
7
8
9
10
import tracium
 
# Set version during initialization
tracium.init(
    api_key="sk_live_...",
    default_version="1.2.3",  # Your application version
)
 
# All traces now include version="1.2.3"
tracium.trace()

Note: Use your application's version, not the SDK version. This helps you track changes in your code, not the Tracium SDK.

Version Per Trace

You can also set the version on individual traces, which overrides the default:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
import tracium
 
client = tracium.init(
    api_key="sk_live_...",
    default_version="1.0.0",
)
 
# Override version for a specific trace
with client.agent_trace(
    agent_name="experiment-bot",
    version="1.0.0-beta",  # Override for this trace
) as trace:
    # This trace uses version "1.0.0-beta"
    pass
 
# Other traces still use "1.0.0"
with client.agent_trace(agent_name="production-bot") as trace:
    pass

Using start_trace()

The start_trace() function also accepts a version parameter:

1
2
3
4
5
6
7
8
9
10
11
import tracium
 
tracium.init(api_key="sk_live_...")
 
# Start a trace with a specific version
with tracium.start_trace(
    agent_name="my-agent",
    version="2.0.0-rc1",
) as trace:
    # Your code here
    pass

Version from Environment

A common pattern is to read the version from an environment variable or package metadata:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
import tracium
import os
 
# From environment variable
version = os.getenv("APP_VERSION", "dev")
 
tracium.init(
    api_key="sk_live_...",
    default_version=version,
)
 
# Or from package metadata (Python 3.8+)
from importlib.metadata import version as pkg_version
 
try:
    app_version = pkg_version("your-package-name")
except Exception:
    app_version = "unknown"
 
tracium.init(
    api_key="sk_live_...",
    default_version=app_version,
)

Semantic Versioning

We recommend using semantic versioning (SemVer) for consistency:

# Standard versions
"1.0.0"
"2.1.3"

# Pre-release versions
"1.0.0-alpha"
"1.0.0-beta.1"
"2.0.0-rc.1"

# Development versions
"1.0.0-dev"
"1.0.0+build.123"

# Git-based versions
"1.0.0+abc1234"  # Include commit hash

Best Practices

Always Set a Version

Even during development, use a version like "dev" or "local" to distinguish development traces from production.

Match Your Release Process

Use the same version string as your deployment/release process. This makes it easy to correlate traces with specific releases.

Include Build Info for CI/CD

In CI/CD environments, consider including the build number or commit hash for precise traceability.

← Auto-Instrumentation Multi-Tenancy →