Architecture Overview

Traceway organizes your application telemetry around two building blocks: Traces and Issues. Everything else — spans, attributes, metrics — enriches these two concepts.

Building Blocks

Traces

A Trace is a timed unit of work. There are two specializations:

• Endpoints — HTTP requests, automatically created by middleware (e.g., GET /api/users/:id)
• Tasks — Background jobs, manually created in your code (e.g., cron jobs, queue workers)

Both carry duration, attributes, and spans. Learn more →

Issues

An Issue captures a problem — an exception, a panic, or an explicitly sent message. Issues can be connected to a trace via the trace's context, linking the error to the request or task that caused it.

Similar exceptions are automatically grouped by normalized stack trace hash. Learn more →

Attributes

Attributes are key-value metadata attached to traces and issues. Values are strings — if the string is valid JSON, the dashboard displays it with proper formatting.

Attributes flow from global scope to per-request scope. Learn more →

Spans

Spans are timed sub-operations within a trace. Use them to measure where time is spent — database queries, API calls, business logic steps.

Spans display as a timeline within a trace in the dashboard. Learn more →

Metrics

Metrics are time-series measurements of your application's health. System metrics (CPU, memory, goroutines) are collected automatically, and you can capture custom metrics with optional tags for filtering and grouping.

Metrics are displayed on a configurable dashboard with widget groups and multiple chart types. Learn more →

See Data Flow for how these concepts connect during request processing, task execution, and metrics collection.