Concepts
Kalibr's data model in 2 minutes.
You will learn: - The hierarchy: Tenant → Workflow → Trace → Span - When to use each concept - How they appear in the dashboard
The Hierarchy
Tenant (customer)
└── Workflow (operation type)
└── Trace (single execution)
└── Span (individual step)
Tenant
The customer using your service.
os.environ["KALIBR_TENANT_ID"] = "acme_corp"
Use for: Per-customer billing, usage limits, cost attribution.
Workflow
A named operation (like "research_pipeline" or "support_triage").
os.environ["KALIBR_WORKFLOW_ID"] = "research_pipeline"
Use for: Grouping related calls, tracking operation costs, identifying bottlenecks.
Trace
One execution of a workflow. Created automatically.
Contains: Start/end time, total cost, success/failure, all spans.
Span
A single step within a trace.
Auto-created for: OpenAI, Anthropic, Google SDK calls.
Manually created with:
@trace(operation="fetch_docs", provider="database", model="postgres")
def fetch_documents(query):
return db.query(query)
Environment Variables
| Variable | Description |
|---|---|
KALIBR_API_KEY |
Your API key (required) |
KALIBR_COLLECTOR_URL |
Collector endpoint (required for cloud) |
KALIBR_WORKFLOW_ID |
Current workflow name |
KALIBR_TENANT_ID |
Customer ID |
KALIBR_SERVICE |
Service name |
KALIBR_ENVIRONMENT |
prod/staging/dev |
For cloud usage, set KALIBR_COLLECTOR_URL=https://api.kalibr.systems/api/ingest