The only tool you need to know what is happening and how to fix it.
Go alertingexception-trackerissue-trackinglogsmetricsmonitoringobservability-platformopen-telemetryotelsession-replaytelemetrytraces
# Architecture Overview
Traceway's mental model is small. There's one underlying primitive, **spans**, and a handful of **materialized views** over those spans that make the dashboard fast.
## The primitive: spans
Every piece of trace data Traceway ingests is an OpenTelemetry span. Spans carry a name, a kind, a duration, attributes, events (exceptions live here), and parent/trace ids. The shape is OTel-native: Traceway speaks OTLP directly and doesn't impose its own trace model on top.
[Learn more about spans →](/learn/spans)
## The materialized views
On ingestion, Traceway classifies each span and writes a row into a dedicated table when the kind or attributes match a rule. These tables are the top-level dashboard concepts:
- **Endpoints**: inbound HTTP entry points (`GET /api/users/:id`).
- **Tasks**: queue consumers, scheduled commands, anything that runs as a "thing that completes".
- **AI Traces**: any span carrying `gen_ai.*` attributes, root or child.
- **Issues**: exception events lifted off whichever entity owned the span.
Each table is indexed and shaped for one job: answering "what's slow?", "what's expensive?", "what's failing?" without scanning the full span store. They're projections, not parallel universes: the underlying span data is the source of truth.
[Trace classification rules and the views →](/learn/traces) · [Issues →](/learn/issues) · [AI Tracing →](/learn/ai-tracing)
## Root and non-root entities
Endpoints, Tasks, and AI Traces all carry an `is_root` flag. A row is **non-root** when the span that produced it was a child of another span: a queue worker started by an HTTP request, an LLM call made inside that same handler, a downstream service hop. Non-root rows link back to the originating trace via their `traceId`, so the distributed-trace view shows the full picture across all the entities that share one OTel trace id.
[More on root vs non-root →](/learn/traces#root-and-non-root-entities)
## Enrichments
- **Attributes**: key-value metadata on spans and the entities derived from them. Flow from global → per-request scope. [Details →](/learn/attributes)
- **Sessions**: user-session grouping for browser/mobile clients, separate from traces. [Details →](/learn/sessions)
- **Metrics**: time-series measurements, ingested via OTLP metrics. Independent of the trace pipeline. [Details →](/learn/metrics)
- **Logs**: OTLP logs ingestion, joinable to traces by trace id. [Details →](/learn/logs)
<img src="/architecture.png" alt="Traceway Architecture" style={{ maxWidth: '100%', height: 'auto' }} />
See [Data Flow](/learn/data-flow) for how these connect during request processing, task execution, and metrics collection, and [Project Structure](/learn/projects) for how to split an application across Traceway projects before you instrument it.
## Objectives
An [SLO](/learn/slos) holds any of the above to a target: the share of good requests of an endpoint, of spans matching a filter, of task runs, of monitor probes, of metric time slices, or of crash-free sessions, over a rolling 7, 30 or 90 day window. The worker folds the raw rows into per-minute good/total buckets once, so the current SLI, the error budget and the burn rates are sums over buckets rather than scans, and the burn-rate [alert rules](/learn/alerts#slo-burn-rate) read the same buckets.
## Above a single project
Everything above is scoped to one project. The [Organization Overview](/learn/organization-overview) sits above them all: every server reporting into the organization, every recently active issue, every monitor, and every open on-call page, each one a sidebar click apart. It is how a fleet of servers or a [Kubernetes cluster](/learn/kubernetes) is read at a glance before you drill into the project that owns the problem.
## Authentication
Every way in has its own credential: SDKs and OTel exporters use the project token, CI uses the source map token for symbol uploads, the dashboard uses a JWT or a personal access token, the [CLI](/learn/cli-auth) uses a device flow, and [MCP clients](/learn/mcp) use OAuth with PKCE. Role middleware scopes what an authenticated user can do.
<img src="/auth-types.png" alt="Traceway authentication types" style={{ maxWidth: '100%', height: 'auto' }} />