Skip to content
Back to search

traceway

Official Traceway plugin marketplace

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026. Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/tracewayapp/traceway with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/tracewayapp/traceway'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tracewayapp--traceway/badge.svg)](/listings/tracewayapp--traceway)

HTML

<a href="/listings/tracewayapp--traceway"><img src="/api/listings/tracewayapp--traceway/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Self-host with Docker (recommended)

git clone https://github.com/tracewayapp/traceway
cd traceway && docker compose up -d
# ✓ dashboard at http://localhost

Point any OTel SDK at `http://localhost/api/otel/v1/traces` (or `/metrics`, `/logs`) and traces start flowing. See the [self-hosting docs](https://docs.tracewayapp.com/server/docker-compose) for production deployment, TLS, and storage configuration.

Prefer a single container with no external databases? The [SQLite image](https://docs.tracewayapp.com/server/sqlite) is the smallest deployment. The [DuckDB image](https://docs.tracewayapp.com/server/duckdb) keeps the same zero-dependency setup but adds a columnar telemetry store for far more dashboard headroom. Run either with `docker compose -f docker-compose.sqlite.yml up -d` or `-f docker-compose.duckdb.yml`.

**Docker images are cryptographically signed with Cosign.**

Embedded mode (inside your Go app)

Run Traceway inside your Go process. No Docker, no external databases, SQLite under the hood:

go get github.com/tracewayapp/traceway/backend
import tracewaybackend "github.com/tracewayapp/traceway/backend"

func main() {
    go tracewaybackend.Run(
        tracewaybackend.WithPort(8082),
        tracewaybackend.WithDefaultUser("admin@localhost.com", "admin"),
        tracewaybackend.WithDefaultProject("My App", "opentelemetry", "dev-token"),
    )

    // ... start your app, point its OTel exporter to http://localhost:8082/api/otel/v1/traces
}

Open `http://localhost:8082`, log in, and hit your app to see traces appear. Full walkthrough in the [embedded mode guide](https://docs.tracewayapp.com/learn/embedded-mode), or check the working examples ([OTel exporter](./examples/embedded-backend-otel) or [Go client SDK](./examples/embedded-backend-go-client)).

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "traceway",
  3. "owner": {
  4. "name": "Traceway"
  5. },
  6. "description": "Official Traceway plugin marketplace",
  7. "plugins": [
  8. {
  9. "name": "tw",
  10. "source": "./",
  11. "description": "Traceway skills: /tw:traceway debugs production issues through the traceway CLI, /tw:traceway-learn is the full guide to every part of Traceway, /tw:traceway-setup instruments a project to report to a Traceway instance."
  12. },
  13. {
  14. "name": "tw-write",
  15. "source": "./plugins/tw-write",
  16. "description": "Traceway write skill: lets an agent make routine on-call changes through the traceway-write CLI. Opt-in, separate from the read-only tw plugin."
  17. }
  18. ]
  19. }
README.md · README · 354 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. > 🎉 **Traceway 2.0 is here.** More reliable traces, better OpenTelemetry compatibility, and a clearer picture of your app. [Read the V2 release post →](https://tracewayapp.com/blog/traceway-2-0)
  2. <p align="center">
  3. <picture>
  4. <source media="(prefers-color-scheme: dark)" srcset="Traceway%20Logo%20White.png" />
  5. <source media="(prefers-color-scheme: light)" srcset="Traceway%20Logo.png" />
  6. <img src="Traceway Logo.png" alt="Traceway Logo" width="200" />
  7. </picture>
  8. </p>
  9. <p align="center">
  10. <sub>Built on <img src="./docs/public/otel.png" height="14" alt="OpenTelemetry" /> <b>OpenTelemetry</b></sub>
  11. </p>
  12. <h3 align="center">OpenTelemetry-native observability. Open source. Self-hosted in 90 seconds.</h3>
  13. <p align="center">
  14. <a href="https://opentelemetry.io"><img alt="OTel-First" src="https://img.shields.io/badge/OTel--First-Native%20OTLP%2FHTTP-425CC7?logo=opentelemetry&logoColor=white" /></a>
  15. <a href="https://github.com/tracewayapp/traceway/blob/main/LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/100%25%20Open%20Source-MIT-22c55e" /></a>
  16. <a href="https://docs.tracewayapp.com/server/docker-compose"><img alt="Self-Host" src="https://img.shields.io/badge/Self--Host-docker%20compose%20up-2496ed?logo=docker&logoColor=white" /></a>
  17. <a href="https://discord.gg/RZq9NT62nc"><img alt="Join us on Discord" src="https://img.shields.io/badge/Discord-Join%20the%20community-5865F2?logo=discord&logoColor=white" /></a>
  18. </p>
  19. <p align="center">
  20. <a href="https://tracewayapp.com">Website</a> · <a href="https://docs.tracewayapp.com">Docs</a> · <a href="https://cloud.tracewayapp.com">Cloud</a> · <a href="https://discord.gg/RZq9NT62nc">Discord</a>
  21. </p>
  22. ---
  23. Traceway is an **OpenTelemetry-native** observability platform. It combines **logs, traces, metrics, real user monitoring (RUM) with session replay, exceptions, AI tracing, and on-call paging** in one place. Point an OTLP exporter at it and you're in business. No Collector, no glue code, no per-language vendor SDK.
  24. **MIT licensed. No BSL. No "open core."** Every feature is in the box. Self-host it for free, or run it on [Traceway Cloud](https://cloud.tracewayapp.com) if you'd rather not babysit infra.
  25. <table width="100%">
  26. <tr>
  27. <td width="50%" valign="top"><img alt="Traceway Issues" src="./.github/screenshots/issues.png" /></td>
  28. <td width="50%" valign="top"><img alt="Traceway Endpoints" src="./.github/screenshots/endpoints.png" /></td>
  29. </tr>
  30. </table>
  31. <p align="center">
  32. <a href="https://discord.gg/RZq9NT62nc"><b>👋 Join the Traceway Community on Discord →</b></a><br>
  33. <sub>Chat with the team, shape the roadmap, get help, and meet other folks running Traceway in production.</sub>
  34. </p>
  35. ## What's in the box
  36. - **Logs**: Structured, trace-linked, sub-second search. Native OTLP/HTTP ingest from any OTel SDK.
  37. - **Traces**: End-to-end span waterfalls across every service. Click a log, jump to its span.
  38. - **Endpoints**: Per-route latency percentiles (P50/P95/P99), throughput, and error rate, ranked by Apdex and a 5-factor impact score.
  39. - **Metrics**: Host, runtime, and custom metrics. Any dimension, any chart, with custom widget groups.
  40. - **Exceptions**: Stack traces are normalized, given a SHA-256 fingerprint, and grouped into ranked issues. Source-mapped (webpack, esbuild, Vite).
  41. - **Profiling** _(experimental)_: Flame graphs for CPU, heap, and goroutines with version-to-version diffing and a top-functions table. Ingests native Go pprof and OTLP profiles.
  42. - **Real User Monitoring**: How fast your site is for real visitors, which release made it slower, and who was affected. Core Web Vitals from every visit, release regression alerts and frontend SLOs. [More below](#real-user-monitoring).
  43. - **Session Replay**: Watch what the user did right before the error. Available for web (any JS framework) and Flutter.
  44. - **AI Observability**: LLM cost, tokens, latency, and full conversations across providers (OpenRouter and any OTel-compatible AI gateway). Calls group into conversations via `gen_ai.conversation.id`, tool calls are parsed from completions and rendered in the chat view, and multi-language content flagging catches conversations containing terms you care about. Per-customer analytics (conversation length, cost per conversation) key on `user.id`: set it to a stable customer identifier such as your account or tenant id, the same value across all of that user's conversations, never a session id.
  45. - **On-Call & Paging**: Rotation schedules with layers and overrides, escalation policies, and pages that escalate until someone acknowledges. Delivered via email, Slack, Pushover, Telegram, or SMS, with one-click acknowledge links that need no login.
  46. - **SLOs**: Service level objectives over any indicator Traceway already stores: endpoint availability or latency, any span filter (a queue consumer, an outbound call), task success, monitor uptime, a metric held under a limit per time slice, or crash-free sessions for browser and mobile projects. Rolling 7, 30 or 90 day windows, an error budget, burn rates, and multi-window burn-rate alerts with recovery notices, all computed from precomputed buckets rather than raw scans.
  47. - **Fleet Overview**: One organization-wide page above every project: each reporting instance with live CPU, memory, disk and network, plus issues, monitors and open pages across all projects. Kubernetes nodes group by cluster, and a single `kubectl apply` instruments a whole cluster.
  48. Plus: background-task (job) monitoring, configurable alerts (Slack / GitHub / email / webhook / Pushover / Telegram), multi-tenant orgs with role-based access, and a per-endpoint slow-threshold override.
  49. ## AI-First
  50. Your agent sets up Traceway, queries production telemetry, and finds the root cause:
  51. ```bash
  52. npx skills add tracewayapp/skills --all
  53. ```
  54. One command installs all four skills into Claude Code, Cursor, Codex, or any agent that reads `SKILL.md`:
  55. - **`/traceway-setup`** reads your repo and wires it up: OTel for backends, Traceway SDKs for web and mobile. Then it verifies data actually arrives.
  56. - **`/traceway`** installs the `traceway` CLI and uses it to query exceptions, logs, endpoints, and metrics, from bug report to root cause.
  57. - **`/traceway-learn`** is the full guide to the product: issues, endpoints, traces, logs, metrics, monitors, status pages, alerts, on-call schedules and paging, and settings. Ask it how anything in Traceway works.
  58. - **`/traceway-write`** teaches an agent to make routine on-call changes safely. It does nothing until you opt in to agent write access (below).
  59. The [CLI](./cli) is designed for agents first: JSON when piped, tables on a TTY, stable error identifiers and exit codes, `--fields` to trim responses. It's read only. Nothing hangs, nothing gets damaged.
  60. Want the agent to act too? Agent write access is opt-in at three levels: a write credential (the separate `traceway-write` CLI, a `tww_` token, or the `/mcp/write` server), an organization admin switch, and the creator's own role. Then an agent can archive issues, acknowledge pages, snooze alerts, run monitors and write post-mortems, and every write lands in an audit log. In Claude Code the `traceway-write` skill is its own plugin (`plugins/tw-write`). [Learn more →](https://docs.tracewayapp.com/learn/agent-write-access)
  61. The skills are plain Markdown in [`skills/`](./skills), MIT-licensed like the rest of Traceway, and every release publishes them to [tracewayapp/skills](https://github.com/tracewayapp/skills), the small repo you install from. No lock-in. [Learn more →](https://tracewayapp.com/product/agent-skills)
  62. <p align="center">
  63. <img alt="Claude Code fixing a production issue from a Traceway error, end to end" src="./traceway-ai-demo.gif" width="900" />
  64. </p>
  65. ## Symbolication
  66. `app.min.js:1:63` tells you nothing. Traceway resolves minified production errors back to the original file, line, and function the moment they arrive. The same engine handles stripped and obfuscated mobile crashes: iOS and Swift against the build's dSYM, Android against its R8 `mapping.txt`, Dart and Flutter against their obfuscation map.
  67. The symbolicator is pure Go and built to keep up with ingest. Every debug artifact (a source map, a dSYM, an R8 mapping) compiles once into a binary `.tw` file and is memory-mapped from disk. Opening a compiled map takes under a microsecond, p99 lookup stays under a millisecond on a cold cache, and no map is re-parsed after a restart. The corpus is a disk budget, not a RAM budget.
  68. The same engine ships as a standalone [OpenTelemetry Collector processor](./backend/app/symbolicator/otelprocessor), drop-in compatible with Honeycomb's `source_map_symbolicator`: same component type, same attribute contract, same config keys. Use it in your own pipeline, with or without Traceway behind it.
  69. Upload source maps from CI with `npx traceway-sourcemaps --directory ./dist`; dSYMs and R8 mappings post to the same endpoint. Benchmarks live in [`benchmarks/`](./benchmarks); run them on your fork. [Learn more →](https://tracewayapp.com/product/symbolication)
  70. ## Real User Monitoring
  71. Real User Monitoring (RUM) shows how your site works for the people using it: how fast pages load and react, which errors happen, and what a user did right before something broke. Add the browser SDK to a React, Vue, Svelte, jQuery or plain JavaScript app and you get:
  72. - **A Web Performance dashboard**, set up when you create the project. It shows the Core Web Vitals (how long the main content takes to appear, how fast the page reacts to a click, how much the layout jumps around), split by page, release, browser, device and country.
  73. - **Release regression alerts and frontend SLOs.** Get told once when a new release is slower than the one before it, and set a target such as "95% of clicks respond within 200 ms".
  74. - **Errors with their history.** Every error arrives with up to 10 minutes of the clicks, requests and console output before it, and a 30 second replay of what the user saw.
  75. - **Captures and recording triggers.** When one customer reports a problem, ask their browser for its recent history. Or describe a situation, such as three failed requests within a minute, and have it recorded when it happens.
  76. - **Remote settings.** Change what browsers collect from the dashboard, for everyone or for one release, without shipping a build.
  77. <p align="center">
  78. <img alt="Web Performance dashboard with Core Web Vitals from real browser visits" src="./website/public/images/rum-dashboard.png" width="900" />
  79. </p>
  80. Two things make it different from RUM tools that upload everything and then sample to keep the bill down:
  81. 1. **Every visit is measured.** Each browser adds up its own page timings and sends one small summary, so nobody is left out of the numbers. What is stored grows with your pages and releases, not with your visitors.
  82. 2. **Details stay in the browser until they are needed.** The last 10 minutes of activity and the page recording are kept in a ring buffer on the device. They are uploaded when an error happens, when a trigger matches, or when you start a capture. A visit with no problems never uploads them.
  83. The browser SDK is OpenTelemetry: it sends standard OTLP logs, traces and metrics and gets its settings over OpAMP, so a click in the browser and the backend work behind it show up as one trace. RUM needs the 2.x browser SDK, which is in beta: `npm install @tracewayapp/frontend@beta`.
  84. [RUM guide](https://docs.tracewayapp.com/learn/rum) · [Best practices](https://docs.tracewayapp.com/learn/rum-best-practices) · [Product page](https://tracewayapp.com/product/rum)
  85. ## Why Traceway
  86. | | Enterprise (Datadog / New Relic) | DIY OSS stack (Prometheus + Loki + Tempo + ...) | **Traceway** |
  87. | ------------------------ | -------------------------------- | ----------------------------------------------- | --------------------------------- |
  88. | **Pricing** | Per-event, per-host, per-seat | Free + ops time | Self-host free, fixed cloud tiers |
  89. | **Setup** | Vendor SDK per language | Glue 6 tools together | `docker compose up -d` |
  90. | **License** | Proprietary | Mixed (some BSL / open-core) | **MIT, no asterisks** |
  91. | **OTel** | Wrapped in vendor SDK | OTel Collector required | **Native OTLP/HTTP ingest** |
  92. | **Replay + traces + AI** | 3 separate products | Wire it yourself | One system, one trace ID |
  93. ## Quick Start
  94. ### Self-host with Docker (recommended)
  95. ```bash
  96. git clone https://github.com/tracewayapp/traceway
  97. cd traceway && docker compose up -d
  98. # ✓ dashboard at http://localhost
  99. ```
  100. Point any OTel SDK at `http://localhost/api/otel/v1/traces` (or `/metrics`, `/logs`) and traces start flowing. See the [self-hosting docs](https://docs.tracewayapp.com/server/docker-compose) for production deployment, TLS, and storage configuration.
  101. Prefer a single container with no external databases? The [SQLite image](https://docs.tracewayapp.com/server/sqlite) is the smallest deployment. The [DuckDB image](https://docs.tracewayapp.com/server/duckdb) keeps the same zero-dependency setup but adds a columnar telemetry store for far more dashboard headroom. Run either with `docker compose -f docker-compose.sqlite.yml up -d` or `-f docker-compose.duckdb.yml`.
  102. **Docker images are cryptographically signed with Cosign.**
  103. ### Embedded mode (inside your Go app)
  104. Run Traceway inside your Go process. No Docker, no external databases, SQLite under the hood:
  105. ```bash
  106. go get github.com/tracewayapp/traceway/backend/v2
  107. ```
  108. ```go
  109. import tracewaybackend "github.com/tracewayapp/traceway/backend/v2"
  110. func main() {
  111. go tracewaybackend.Run(
  112. tracewaybackend.WithPort(8082),
  113. tracewaybackend.WithDefaultUser("admin@localhost.com", "admin"),
  114. tracewaybackend.WithDefaultProject("My App", "opentelemetry", "dev-token"),
  115. )
  116. // ... start your app, point its OTel exporter to http://localhost:8082/api/otel/v1/traces
  117. }
  118. ```
  119. Open `http://localhost:8082`, log in, and hit your app to see traces appear. Full walkthrough in the [embedded mode guide](https://docs.tracewayapp.com/learn/embedded-mode), or check the [working example](./examples/embedded-backend-otel).
  120. ## Supported Integrations
  121. Traceway integrates with the tools you already use. Backends report over **OTLP/HTTP**, so any OpenTelemetry SDK works. Browser and mobile apps use the Traceway SDKs.
  122. > View the full list in the [documentation](https://docs.tracewayapp.com/client). Missing a framework? [Open an issue](https://github.com/tracewayapp/traceway/issues) to request it.
  123. ### Backend
  124. OpenTelemetry is the integration path for every backend language. Point your OTLP exporter at Traceway and you are done.
  125. <table>
  126. <tbody>
  127. <tr>
  128. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/otel"><img src="./docs/public/otel.png" height="28" alt="OpenTelemetry" /><br/><b>OpenTelemetry</b></a></td>
  129. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/otel/nodejs"><img src="./docs/public/node.png" height="28" alt="Node.js" /><br/><b>Node.js</b></a></td>
  130. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/otel/nestjs"><img src="./docs/public/nestjs.png" height="28" alt="NestJS" /><br/><b>NestJS</b></a></td>
  131. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/otel/nextjs"><img src="./docs/public/nextjs.png" height="28" alt="Next.js" /><br/><b>Next.js</b></a></td>
  132. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/otel/hono"><img src="./docs/public/hono.png" height="28" alt="Hono" /><br/><b>Hono</b></a></td>
  133. </tr>
  134. <tr>
  135. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/otel/cloudflare"><img src="./docs/public/cloudflare.png" height="28" alt="Cloudflare Workers" /><br/><b>Cloudflare</b></a></td>
  136. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/otel/symfony"><img src="./docs/public/symfony.png" height="28" alt="Symfony" /><br/><b>Symfony</b></a></td>
  137. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/otel/laravel"><img src="./docs/public/laravel.png" height="28" alt="Laravel" /><br/><b>Laravel</b></a></td>
  138. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/otel/django"><img src="./docs/public/django.png" height="28" alt="Django" /><br/><b>Django</b></a></td>
  139. </tr>
  140. </tbody>
  141. </table>
  142. Go applications use OpenTelemetry too. Point [opentelemetry-go](https://github.com/open-telemetry/opentelemetry-go) at the same OTLP endpoint. See the [OpenTelemetry guide](https://docs.tracewayapp.com/client/otel).
  143. ### Frontend
  144. > Session Replay is included with every frontend integration, and with Flutter too.
  145. A full-stack framework has two halves and two Traceway projects. Next.js and Remix use the React integration below for the browser, SvelteKit uses Svelte, and Nuxt uses Vue. Their server half is a separate OpenTelemetry project from the table above. See [Project Structure](https://docs.tracewayapp.com/learn/projects).
  146. <table width="100%">
  147. <tbody>
  148. <tr>
  149. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/react"><img src="./docs/public/react.png" height="28" alt="React" /><br/><b>React</b></a></td>
  150. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/vue"><img src="./docs/public/vue.png" height="28" alt="Vue" /><br/><b>Vue</b></a></td>
  151. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/svelte"><img src="./docs/public/svelte.png" height="28" alt="Svelte" /><br/><b>Svelte</b></a></td>
  152. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/jquery"><img src="./docs/public/jquery.png" height="28" alt="jQuery" /><br/><b>jQuery</b></a></td>
  153. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/js-sdk"><img src="./docs/public/javascript.png" height="28" alt="JavaScript" /><br/><b>JavaScript</b></a></td>
  154. </tr>
  155. </tbody>
  156. </table>
  157. ### Mobile
  158. <table>
  159. <tbody>
  160. <tr>
  161. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/flutter"><img src="./docs/public/flutter.png" height="28" alt="Flutter" /><br/><b>Flutter</b></a></td>
  162. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/android"><img src="./docs/public/android.png" height="28" alt="Android" /><br/><b>Android</b></a></td>
  163. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/ios"><img src="./docs/public/ios.png" height="28" alt="iOS" /><br/><b>iOS</b></a></td>
  164. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/react-native"><img src="./docs/public/react.png" height="28" alt="React Native" /><br/><b>React Native</b></a></td>
  165. </tr>
  166. </tbody>
  167. </table>
  168. ### AI
  169. <table>
  170. <tbody>
  171. <tr>
  172. <td align="center" width="150"><a href="https://docs.tracewayapp.com/client/openrouter"><img src="./docs/public/openrouter.png" height="28" alt="OpenRouter" style="filter: contrast(0.5);" /><br/><b>OpenRouter</b></a></td>
  173. </tr>
  174. </tbody>
  175. </table>
  176. ## Screenshots
  177. <table width="100%">
  178. <tr>
  179. <td width="50%" valign="top"><b>Logs: trace-linked search</b><br><img src="./.github/screenshots/logs.png" alt="Logs" /></td>
  180. <td width="50%" valign="top"><b>Span waterfall</b><br><img src="./.github/screenshots/span-waterfall.png" alt="Spans" /></td>
  181. </tr>
  182. <tr>
  183. <td width="50%" valign="top"><b>Metrics: application dashboard</b><br><img src="./.github/screenshots/metrics.png" alt="Metrics" /></td>
  184. <td width="50%" valign="top"><b>Exceptions: fingerprinted & ranked</b><br><img src="./.github/screenshots/issues.png" alt="Exceptions" /></td>
  185. </tr>
  186. </table>
  187. ## Tech Stack
  188. | Component | Technology |
  189. | ------------- | ----------------------------------------------------- |
  190. | Backend | Go 1.26, Gin |
  191. | Frontend | SvelteKit 2, Svelte 5, Tailwind CSS v4 |
  192. | Telemetry DB | ClickHouse (standalone), SQLite or DuckDB (embedded) |
  193. | Relational DB | PostgreSQL (standalone) or SQLite (embedded) |
  194. | Ingest | OTLP/HTTP (Protobuf + JSON) for traces, metrics, logs |
  195. ## Project Structure
  196. | Directory | Description |
  197. | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  198. | `backend/` | Go/Gin API server: OTLP ingest, REST API, notifications, migrations |
  199. | `frontend/` | SvelteKit 2 dashboard SPA |
  200. | `cli/` | Agent-first `traceway` command line for querying exceptions, logs, endpoints, and metrics |
  201. | `skills/` | Agent skills (`/traceway-setup`, `/traceway`, `/traceway-learn`) for Claude Code, Cursor, Codex, and any SKILL.md-compatible agent |
  202. | `docs/` | Documentation site (Nextra) |
  203. | `examples/` | Working examples: [embedded mode](./examples/embedded-backend-otel) and OTel-instrumented apps ([Express](./examples/express-otel), [NestJS](./examples/nestjs-otel), [Next.js](./examples/nextjs-otel), [Hono](./examples/hono-otel)) |
  204. | `website/` | Landing page |
  205. ## Build Tags
  206. Storage is selected on two axes: the telemetry store and the transactional (relational) store.
  207. | Tag | Purpose |
  208. | ------------------ | --------------------------------------------------------------------------------------------------------------- |
  209. | _(none)_ | SQLite storage on both axes: embedded mode, zero dependencies. This is the default. |
  210. | `telemetry_duckdb` | DuckDB telemetry store: embedded mode with a columnar engine. Requires `CGO_ENABLED=1`. |
  211. | `transactional_pg telemetry_ch` | ClickHouse (telemetry) + PostgreSQL (config) for standalone server mode. |
  212. | `localdist` | Embeds frontend from `static/dist/` instead of `static/frontend/`. Used by traceway-cloud to inject billing UI. |
  213. ```bash
  214. # Embedded mode (SQLite, default)
  215. cd backend && go build ./cmd/traceway
  216. # Embedded mode with DuckDB telemetry
  217. cd backend && CGO_ENABLED=1 go build -tags telemetry_duckdb ./cmd/traceway
  218. # Standalone server (ClickHouse + PostgreSQL)
  219. cd backend && go build -tags "transactional_pg telemetry_ch" ./cmd/traceway
  220. ```
  221. ## Running Tests
  222. ```bash
  223. # SQLite tests (default, no tags needed)
  224. cd backend && go test -v -count=1 ./app/repositories/...
  225. # ClickHouse + PostgreSQL tests (requires Docker)
  226. ./scripts/test-backend-pgch.sh
  227. # DuckDB telemetry tests
  228. cd backend && CGO_ENABLED=1 go test -tags telemetry_duckdb -v -count=1 ./app/repositories/...
  229. # OTEL trace converter tests (no DB required)
  230. cd backend && go test -v -count=1 ./app/controllers/otelcontrollers/
  231. # Update OTEL golden files after intentional converter changes
  232. cd backend && go test -v -count=1 ./app/controllers/otelcontrollers/ -args -update
  233. ```
  234. ## Documentation
  235. Full documentation at **[docs.tracewayapp.com](https://docs.tracewayapp.com)**:
  236. - [**Client SDKs**](https://docs.tracewayapp.com/client): OpenTelemetry, Go, Node.js, Python, and more
  237. - [**Self-Hosting**](https://docs.tracewayapp.com/server): Docker Compose and production deployment
  238. - [**Concepts**](https://docs.tracewayapp.com/learn): How tracing, exception fingerprinting, metrics, and alerts work
  239. - [**Real User Monitoring**](https://docs.tracewayapp.com/learn/rum): Page speed, sessions, replay and errors from real visitors, plus [best practices](https://docs.tracewayapp.com/learn/rum-best-practices) for setting up a frontend app
  240. - [**Embedded Mode**](https://docs.tracewayapp.com/learn/embedded-mode): Run Traceway inside your Go app
  241. - [**Kubernetes**](https://docs.tracewayapp.com/learn/kubernetes): Instrument a whole cluster with the manifests in [`examples/kubernetes`](./examples/kubernetes)
  242. - [**Organization Overview**](https://docs.tracewayapp.com/learn/organization-overview): Servers, issues, monitors, and on-call pages across every project, one sidebar click apart
  243. - [**SLOs**](https://docs.tracewayapp.com/learn/slos): Objectives, error budgets and burn-rate alerting over endpoints, spans, tasks, monitors, metrics and crash-free sessions
  244. ## Community
  245. Traceway is built in the open, and the **[Discord community](https://discord.gg/RZq9NT62nc)** is where it happens. Come say hi, whether you're kicking the tires, running it in production, or just curious. We use it to:
  246. - 🗣️ **Talk through ideas**: feature requests, integration asks, roadmap input
  247. - 🛟 **Help each other out**: setup, OTel wiring, deployment questions
  248. - 🚀 **Show & tell**: share what you're building and how you're using Traceway
  249. - 🐛 **Catch bugs early**: report issues and get fast feedback from maintainers
  250. - 👀 **Get the inside scoop**: sneak peeks at what's shipping next
  251. <p>
  252. <a href="https://discord.gg/RZq9NT62nc"><img alt="Join the Traceway Community on Discord" src="https://img.shields.io/badge/Join%20the%20Community-on%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" /></a>
  253. </p>
  254. ## Contribute
  255. Contributions are welcome. Pull requests get reviewed and merged. If you're not sure where to start or want to discuss an idea first, [open an issue](https://github.com/tracewayapp/traceway/issues) or drop by the [community Discord](https://discord.gg/RZq9NT62nc) and we'll talk it through.
  256. ## Links
  257. - [Website](https://tracewayapp.com)
  258. - [Documentation](https://docs.tracewayapp.com)
  259. - [Traceway Cloud](https://cloud.tracewayapp.com): managed hosting (same MIT code, run by us)
  260. - [Community Discord](https://discord.gg/RZq9NT62nc): chat with the team and other users

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.