Observations & Tracing

Observations & Tracing

The Observations section of the dashboard is where all telemetry data from your instrumented applications appears. It has three views: Requests, Tracing, and Exceptions.

---

How Traces Flow

Your App (SDK)
  → OpenTelemetry spans (protobuf)
  → POST /api/sdk/traces
  → Server parses + stores in MongoDB
  → Dashboard queries + visualizes

Every span contains:

Field | Description -- | -- traceId | Unique identifier for the entire trace spanId | Identifier for this specific span parentSpanId | Parent span (for nested traces) spanName | Human-readable name (e.g. openai.chat) spanKind | CLIENT, SERVER, INTERNAL, PRODUCER, CONSUMER serviceName | Your application_name from init() resourceAttributes | Environment, SDK info, deployment spanAttributes | Model, tokens, cost, prompt/completion text duration | Duration in nanoseconds statusCode | OK, ERROR, or UNSET statusMessage | Error message if applicable timestamp | When the span started

---

Trace Mapping

When the dashboard queries traces, it maps provider-specific span attribute names to a common schema. This is what allows tmam to show a unified view across 40+ different providers.

The SDK writes to the OTel semantic conventions (gen_ai.*) which the server normalizes into queryable fields.

---

Data Retention

By default, all traces are stored indefinitely in MongoDB. For large-scale deployments, consider setting up a MongoDB TTL index on the createdAt field to auto-expire old traces.

// In the MongoDB shell — expire traces older than 90 days
db.traces.createIndex(
  { "createdAt": 1 },
  { expireAfterSeconds: 7776000 }
)