Workspaces

Group and filter traces by project, team, or environment.

What are Workspaces?

Workspaces group your traces so you can:

Filter traces and analytics in the dashboard
Run drift detection per workspace
Separate projects, environments, or teams

Default Workspace at Init

Set a default workspace at init. All traces — automatic and manual — will use it unless overridden.

1
2
3
4
5
6
7
8
9
10
11
import tracium

# Option 1: Pass workspace_id directly
tracium.trace(
    api_key="your_api_key_here",
    workspace_id="id from your dashboard",
)

# Option 2: Use an env var instead
# export TRACIUM_WORKSPACE_ID=production
tracium.trace(api_key="your_api_key_here")

Using workspace_id in Traces

Pass workspace_id to agent_trace() to override the default:

1
2
3
4
5
6
7
8
9
10
import tracium

client = tracium.init(api_key="sk_live_...")

with client.agent_trace(
    agent_name="support-bot",
    workspace_id="id from your dashboard",
) as trace:
    with trace.span(span_type="llm", name="generate_response") as span:
        span.record_output({"response": "Hello!"})

Workspace with start_trace

start_trace() also accepts workspace_id. Omit it to use the default:

1
2
3
4
5
6
7
8
9
10
11
import tracium

tracium.trace(api_key="your_api_key_here", workspace_id="id from your dashboard")

# Uses default workspace
with tracium.start_trace(agent_name="my-agent") as trace:
    pass

# Override for this trace
with tracium.start_trace(agent_name="my-agent", workspace_id="id from your dashboard") as trace:
    pass

Workspace with agent_trace Decorator

The @agent_trace decorator works the same way:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
import tracium
from tracium import agent_trace, agent_span

client = tracium.init(api_key="your_api_key_here", workspace_id="id from your dashboard")

@agent_trace(client=client, agent_name="support-bot")
def handle_support(request: str):
    # Uses default workspace
    return generate_response(request)

@agent_trace(client=client, agent_name="support-bot", workspace_id="id from your dashboard")
def handle_support_staging(request: str):
    # Override workspace
    return generate_response(request)

Drift Detection

Trigger drift checks scoped to a workspace:

1
2
3
4
5
6
7
8
9
import tracium

client = tracium.init(api_key="sk_live_...")

# Trigger drift check for a specific workspace
results = client.trigger_drift_check(
    workspace_id="id from your dashboard",
    metrics=["latency", "error_rate"],
)

Workspaces vs Tenancy

They solve different problems:

Feature	Workspace	Tenant
Scope	Per init or per trace	Context-wide via set_tenant()
Use case	Projects, environments, teams	Customers, organizations
How to set	workspace_id param or env var	tracium.set_tenant()

You can use both on the same trace — tenant_id and workspace_id work together.

Best Practices

Set Default at Init

Configure workspace_id at init or via env var so every trace gets a workspace automatically. Great for separating prod, staging, and dev.

Combine with Tenancy

Use set_tenant for customer identity and workspace_id for project or environment — together they give you precise filtering.

Complete Example

example.pypython

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import os
import tracium

# Default workspace from env
tracium.trace(
    workspace_id=os.getenv("TRACIUM_WORKSPACE_ID", "default"),
)

# LLM calls are traced automatically
from openai import OpenAI
client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": user_message}],
)

← Multi-Tenancy OpenAI Integration →