# Traceway review: OpenTelemetry observability with self-hosting

> Traceway is a Go-based observability platform that receives OTLP telemetry and combines logs, traces, metrics, exceptions, session replay, AI tracing, and paging. Its self-hosted Docker Compose deployment suits teams standardized on OpenTelemetry, but the README does not document a complete production setup or rollback procedure.

**tracewayapp/traceway** — The only tool you need to know what is happening and how to fix it.

- Repository: https://github.com/tracewayapp/traceway
- Website: https://tracewayapp.com
- Stars: 1,758 · Forks: 93
- Language: Go
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/tracewayapp-traceway

## What Traceway centralizes for OpenTelemetry teams

Traceway addresses the problem of splitting application telemetry across separate systems. The README positions it as an OpenTelemetry-native platform that accepts data through OTLP/HTTP, then makes logs, traces, metrics, exceptions, session replay, AI calls, and operational alerts available in one product. Its intended users are software teams that want broad observability without maintaining a collector and separate vendor SDKs for every service.

The feature scope is unusually broad for a self-hosted project. Traceway lists trace-linked log search, end-to-end span waterfalls, route-level latency percentiles, runtime and custom metrics, grouped exceptions, and profiling. It also covers real-user monitoring and session replay for web applications built with any JavaScript framework and for Flutter applications. AI observability tracks token use, cost, latency, provider conversations, tool calls, and content flags. On-call features include schedules, overrides, escalation policies, acknowledgment links, and delivery through email, Slack, Pushover, Telegram, or SMS.

That breadth is useful when replacing several disconnected tools. It is also a larger deployment than a simple trace viewer. The root Docker Compose file starts Traceway alongside ClickHouse and PostgreSQL, while the all-in-one Dockerfile builds a frontend, a Go backend, and the data services into a larger runtime image. Traceway is therefore both an observability backend and an operations surface, rather than only an OpenTelemetry receiver.

## Traceway's ingest and telemetry data flow

The documented intake path starts with an OpenTelemetry exporter. Traceway accepts native OTLP/HTTP telemetry from any OpenTelemetry SDK, and its README says applications do not need a separate collector or per-language vendor SDK. This places Traceway at the endpoint of an existing telemetry pipeline rather than requiring agents that bypass OpenTelemetry.

After ingestion, the platform associates different telemetry types into a diagnostic workflow. Logs can lead to the relevant span, while trace waterfalls show how work moved across services. Endpoint views calculate P50, P95, and P99 latency, throughput, and error rate for individual routes. Exceptions receive normalized stack traces and a SHA-256 fingerprint, allowing related reports to be grouped into ranked issues. Source-map support covers webpack, esbuild, and Vite, while the standalone symbolicator also handles iOS dSYM, Android R8 mapping, and Dart or Flutter obfuscation artifacts.

Storage has a clear division in the repository files. Traceway connects to ClickHouse for telemetry and PostgreSQL for application data. The Compose configuration persists ClickHouse data in a named `clickhouse-data` volume and waits for both dependencies to become healthy before starting Traceway. The backend is written in Go. Its build stage compiles a static Linux executable with the `transactional_pg telemetry_ch` build tags and embeds the built frontend.

Not every integration is equally mature. Profiling is explicitly labeled experimental. AI analytics depends on stable instrumentation fields such as `gen_ai.conversation.id` and `user.id`; the README warns against using a session ID where a stable customer or tenant identifier is expected. Incorrect identity instrumentation can therefore make per-customer conversation cost and length misleading.

## Installing Traceway's agent skills

The README's shortest documented setup path installs two agent skills from the repository. This command installs support for both `/traceway-setup`, which examines a codebase and wires telemetry integrations, and `/traceway`, which installs the Traceway CLI for querying production data.

```bash
npx skills add tracewayapp/traceway
```

After running the command, a compatible coding agent should be able to read the installed `SKILL.md` files. The README says `/traceway-setup` configures OpenTelemetry for backend services and Traceway SDKs for web or mobile code, then checks whether telemetry arrives. The exact files and edits it makes depend on the target repository and are not enumerated in the README.

The `/traceway` skill provides the first query path through the CLI. According to the README, the client can query exceptions, logs, endpoints, and metrics. It emits JSON when output is piped and tables when connected to a terminal. Its read-only behavior has one explicit exception: archiving an exception requires `--yes`. This makes the CLI useful during incident investigation because an agent can request selected fields and interpret stable errors without turning ordinary investigation into a broad write operation.

There is an important documentation gap here. The README says to point an OTLP exporter at Traceway, but it does not show the exporter endpoint, required headers, TLS settings, or a minimal application configuration. A reader must consult the Traceway server documentation before expecting `/traceway-setup` to connect an application successfully. The README's claim that self-hosting takes 90 seconds is not accompanied by a complete installation procedure.

## Deploying Traceway's Compose stack safely

The repository includes several Compose variants: `docker-compose.yml`, `docker-compose.browser.yml`, `docker-compose.duckdb.yml`, and `docker-compose.sqlite.yml`. The default `docker-compose.yml` uses `Dockerfile.minimal` for Traceway and starts separate ClickHouse and PostgreSQL services. It publishes Traceway on port 80 and configures health checks for the data services.

The Compose file exposes operational constraints that matter more than the short marketing description. Its environment includes example database credentials and `JWT_SECRET: change-this-to-a-secure-secret-at-least-32-chars`. Those values must not be retained for a real deployment. Proxy trust also affects per-IP rate limits because those limits can use the forwarded client address. File comments state that only loopback is trusted by default and identify `TRUSTED_PROXIES` and `TRUSTED_PROXY_HEADER` as the relevant settings when a proxy, ingress, or CDN sits in front of Traceway.

Session recordings introduce another policy choice. `STORAGE_PATH` holds on-disk recordings, and `SESSION_RECORDING_RETENTION_DAYS` controls their retention. The Compose comments say an hourly worker also runs at startup, that `0` disables deletion, and that the setting has no effect when `STORAGE_TYPE=s3`. Those details make retention configurable, but the README does not document backup, restore, or rollback.

The multiple Compose files also imply that storage choices are deployment decisions rather than interchangeable names. DuckDB and SQLite variants should not be selected merely because their filenames are shorter. Their suitability depends on workload, persistence, concurrency, and migration behavior, none of which is described in the README.

## Operational limits in profiling, retention, and upgrades

Traceway covers several areas that are often separate products, but this breadth creates operational boundaries. Session replay requires suitable browser or Flutter instrumentation and can record user interface activity for later inspection. Retention is controlled for on-disk recordings, but the README does not define consent controls, capture exclusions, access auditing, or deletion behavior for telemetry stored elsewhere. Those details require direct review before deploying replay in a sensitive application.

Profiling carries the clearest maturity warning. The README labels CPU, heap, and goroutine flame graphs experimental. It says the profiler ingests native Go pprof and OTLP profiles and supports version-to-version diffing, but it does not describe retention, sampling controls, or production overhead. A team should not infer a stable profiling contract from the feature's presence.

Upgrade cost extends beyond replacing a container. Traceway stores telemetry in ClickHouse and application state in PostgreSQL. The README does not provide a version-compatibility matrix for Traceway, ClickHouse, and PostgreSQL, and it does not document schema migrations. The repository has dedicated CLI, backend, Helm, Dockerfile, and database variants, suggesting several deployment paths, but the existence of a path does not prove that every path supports the same feature set.

Maintenance activity is recent. The repository is not archived, and the last push was on 2026-10-15. Recent releases include backend and CLI version 2.0.5 on 2026-10-12. That confirms recent development activity, but the README and release list do not include migration notes, compatibility matrices, or a rollback procedure for version 2.

## Traceway versus a Collector-only architecture

The clearest alternative is to use an OpenTelemetry Collector as the telemetry entry point and retain separate systems for logs, traces, metrics, exceptions, replay, and paging. This changes the architecture rather than simply comparing feature lists. The collector can receive and process OTLP, export to backend-specific systems, and provide a compatibility layer when destinations change. Traceway instead positions itself as the OTLP destination and application-facing observability platform.

This difference matters for teams that already standardized collector pipelines, data governance, routing, or backend migration. Traceway's stated simplicity comes from sending an OTLP exporter directly to the platform, without a collector. A collector-based architecture adds infrastructure but separates ingestion policy from the storage and investigation interface.

Traceway is a better fit when the goal is to consolidate those functions in one self-hosted product and accept its ClickHouse and PostgreSQL deployment model. It is a weaker fit when the immediate requirement is only OTLP routing, when existing retention systems cannot be consolidated, or when unresolved questions about replay privacy, schema upgrades, and rollback prevent production use. The MIT license applies to this repository and includes the listed feature set, with no stated BSL restriction. Operators still need to review the licenses of separately distributed dependencies and images.

## Conclusion

Adopt Traceway when an OpenTelemetry-based, self-hosted observability platform with broad built-in coverage matters more than a minimal collector layer. Do not adopt it for a small trial until the exact OTLP destination, production secrets, persistence, backup, and upgrade procedure are confirmed in the server documentation. For this repository, the first concrete check is whether the ClickHouse, PostgreSQL, and Traceway settings in docker-compose.yml match the intended production environment.

## FAQ

### How do I install Traceway and query telemetry from an agent?

Run `npx skills add tracewayapp/traceway`, then use the installed `/traceway-setup` and `/traceway` skills. The README says `/traceway-setup` instruments supported projects and verifies incoming data, while `/traceway` installs the CLI and queries exceptions, logs, endpoints, and metrics.

### Does Traceway require an OpenTelemetry Collector?

No. Traceway states that applications can point an OTLP exporter directly at it, without a collector, glue code, or per-language vendor SDK. The README does not include the complete exporter configuration.

### What database services are required by the default Traceway deployment?

The default `docker-compose.yml` starts Traceway with ClickHouse and PostgreSQL. Traceway waits for both services to pass their health checks before starting.

## Sources

- [License: MIT](https://github.com/tracewayapp/traceway/blob/main/LICENSE)
- [Project website](https://tracewayapp.com)
- [README](https://github.com/tracewayapp/traceway/blob/main/README.md)
- [Releases](https://github.com/tracewayapp/traceway/releases)
- [tracewayapp/traceway on GitHub](https://github.com/tracewayapp/traceway)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tracewayapp-traceway