Expand description
HTTP API contract for the Trace Infra service.
§Why trace is its own service and not part of History Infra
Conversation messages and trace events look similar on the wire and behave nothing alike:
| Conversation | Trace | |
|---|---|---|
| Replayed into a model prompt | yes | never |
| Losing one record | loses user work | acceptable |
| Volume | one per turn | many per turn |
| Retention | durable | short |
Sharing one store would force the stricter guarantee onto high-volume diagnostic data, and — worse — put events one filtering mistake away from being replayed as conversation. Separate services keep that impossible by construction.
§Layering
agent-trace-contract paths + DTOs + redaction (this crate)
agent-trace-runtime store implementation
agent-trace-server router + auth + binSee api.md for the full HTTP reference.
Structs§
- Activity
Point - Activity data point (daily).
- Activity
Response - Activity response grouped by project.
- ApiError
- Error body shared by every non-2xx response.
- Append
Events Request - Append
Response - Result of an append.
skippedcounts ids that already existed, so a caller can tell a fresh write from a deduplicated retry. - Cache
HitRate Point - Cache hit rate data point.
- Cache
HitRate Response - Cache hit rate response (flat list).
- Click
House Admin Config - Redacted platform ClickHouse connection. Secrets are never serialized.
- Cost
Breakdown Point - Cost breakdown data point (input/output/total).
- Cost
Breakdown Response - Cost breakdown response (flat list).
- Create
Langfuse Project Request - Allocate a Langfuse project and project-level API key to Infra resources.
- Error
Rate Point - A single error-rate data point (daily bucket).
- Error
Rate Response - Error rate response grouped by project.
- Events
Response - Events in chronological order, oldest first.
- Initialize
Runtime Binding Request - Langfuse
Admin Config - Redacted platform Langfuse organization credentials. Secrets are never serialized.
- Langfuse
Project - Persisted Langfuse project assignment. Project secrets are intentionally absent from lookup/list responses.
- Langfuse
Project Page - Latency
Point - A single latency data point (daily bucket).
- Latency
Response - Latency response grouped by project.
- List
Langfuse Projects Request - Query the project-to-resource relationships maintained by Trace Infra.
- Metrics
Query - Request body for all metrics queries.
- Model
Breakdown Entry - A single model breakdown row.
- Model
Trend Point - Model usage trend point (daily).
- Model
Trend Response - Model trend response grouped by project.
- Pricing
Tier Point - Pricing tier analysis data point.
- Pricing
Tier Response - Pricing tier response (flat list).
- Project
Summary - Project-level summary stats.
- Provisioned
Langfuse Project - Creation response. The secret can be recovered only through an idempotent replay of the same create request; ordinary project queries redact it.
- Runtime
Event Record - One runtime trace event.
- Runtime
Langfuse Binding - Search
Events Request - Token
Distribution Point - Token distribution statistics (by model).
- Token
Distribution Response - Token distribution response (flat list).
- Token
Usage Point - A single data point in a token-usage timeseries.
- Token
Usage Response - Top-level response for the token-usage timeseries endpoint.
- Trace
Scope - Identifies what a trace event belongs to.
- Update
Click House Admin Config Request - Update
Langfuse Admin Config Request
Enums§
- Metrics
Data Source - Which ClickHouse table to query.
Constants§
- ADMIN_
CLICKHOUSE_ CONFIG_ PATH - ADMIN_
GATEWAY_ CLICKHOUSE_ CONFIG_ PATH - ADMIN_
GATEWAY_ LANGFUSE_ CONFIG_ PATH - ADMIN_
LANGFUSE_ CONFIG_ PATH - ADMIN_
LANGFUSE_ PROJECTS_ PATH - AUDIENCE
- DEFAULT_
PAGE_ SIZE - Default page size when a request omits
limit. - DEFAULT_
PORT - EVENTS_
APPEND_ PATH - EVENTS_
SEARCH_ PATH - HEALTH_
PATH - LANGFUSE_
PROJECTS_ PATH - LANGFUSE_
PROJECT_ PATH - MAX_
LANGFUSE_ PROJECT_ PAGE_ SIZE - MAX_
METRICS_ LOOKBACK_ DAYS - MAX_
PAGE_ SIZE - Upper bound the server enforces on any page size.
- METRICS_
ACTIVITY_ PATH - METRICS_
CACHE_ HIT_ RATE_ PATH - METRICS_
COST_ BREAKDOWN_ PATH - METRICS_
ERROR_ RATE_ PATH - METRICS_
LATENCY_ PATH - METRICS_
MODEL_ BREAKDOWN_ PATH - METRICS_
MODEL_ TREND_ PATH - METRICS_
PRICING_ TIER_ PATH - METRICS_
PROJECT_ SUMMARY_ PATH - METRICS_
TOKEN_ DISTRIBUTION_ PATH - METRICS_
TOKEN_ USAGE_ PATH - REDACTED
- Placeholder written over any value that looks like a credential.
- RUNTIME_
BINDING_ INITIALIZE_ PATH - RUNTIME_
BINDING_ PATH - SERVICE_
NAME - SERVICE_
TOKEN_ ENV - Optional static service token. When unset, the server runs in open mode.
Functions§
- redact_
payload - Mask credential-shaped fields anywhere in a trace payload.