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
import tracium

# Recommended: configure and enable tracing in one call
client = tracium.trace(
    api_key="sk_live_...",
    default_version="1.2.3",  # Your application version
)

# All traces now include version="1.2.3"

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

← Auto-Instrumentation Multi-Tenancy →