Skip to content

The only tool you need to know what is happening and how to fix it.

3.3 KB
Raw Blame
# Data Flow

Traceway is OpenTelemetry first. Your services are instrumented with the OpenTelemetry SDK for their language and export over OTLP/HTTP. See [OpenTelemetry](/client/otel) for the setup.

## Request Flow

Here's how the concepts connect in a typical request:

1. **Request arrives** → The HTTP instrumentation starts a server **Span**, which begins a **Trace** or joins the one the caller started (automatic)
2. **Auth middleware runs** → You add `user_id` to the active span's **Attributes** (done by you, Traceway does not know about your authentication)
3. **Handler executes** → Child **Spans** are created for sub-operations (DB queries, outgoing HTTP calls, your own spans)
4. **Error occurs** → The exception is recorded on the span it happened in and becomes an **Issue**, linked to that trace and span (automatic)
5. **Request completes** → The exporter sends the spans. Traceway stores accepted spans and shows the server span as an **Endpoint** with its duration, status code and waterfall

## Task Flow

Here's how the concepts connect in a typical scheduled or queued job:

1. **Job starts** → The queue instrumentation starts a consumer **Span**. Depending on the queue instrumentation, it either joins the producer's trace or starts a new trace with an OTel link
2. **Your job code executes** → Child **Spans** are created for sub-operations
3. **Error occurs** → The exception is recorded on its span and becomes an **Issue**, linked to the job's trace
4. **Job completes** → Traceway stores the spans and shows the consumer span as a **Task**, alongside the producer endpoint when both share a trace ID

## Metrics Flow

1. **System metrics collected** → The OpenTelemetry Collector's host metrics receiver, or your runtime's metrics instrumentation, reports CPU, memory, disk and network
2. **Custom metrics recorded** → Your code records counters, gauges and histograms with the OpenTelemetry metrics API, with attributes as tags
3. **Exported** → Metrics are batched and sent over OTLP
4. **Displayed on dashboards** → Metrics appear on configurable, org-shareable dashboards with line charts, area charts, bar charts, single values, gauges, and tables, filterable and groupable by tags

## Ingestion

Traces, metrics and logs arrive over OTLP/HTTP at `/api/otel/v1/traces`, `/api/otel/v1/metrics` and `/api/otel/v1/logs`. Each request authenticates with the project token. Stack traces are symbolicated at ingest, and everything lands in the same telemetry store.

Browser and mobile apps use the Traceway SDK for their platform, which sends the native JSON collection-frame format to `/api/report` and adds session replay and on-device crash capture. Traceway builds canonical spans from those frames and keeps the API’s native UUID identities; OTLP export maps span and parent IDs to eight bytes and includes the available attributes and service metadata. Pick yours under [Docs](/client).

## After the data collection

All this data flows to your Traceway dashboard where you can:

- Sort endpoints by impact to find the worst performers
- Get notified when errors happen
- Track task durations over time
- Monitor system health through metrics

Sampling, project permissions, healthcheck filtering and row rejection can remove telemetry before storage. Trace views are also bounded by access, time, row and attribute limits.