DOCSEARCHbyAlgolia
Submit Docs

Traceway Observability Platform

repository·main·Indexed 20 days ago

https://github.com/tracewayapp/traceway

An OpenTelemetry-native observability platform unifying logs, traces, metrics, session replay, and AI observability. It includes a Source Map Symbolicator Processor for the OpenTelemetry Collector to resolve minified JavaScript stack traces, a pprof ingestion pipeline for CPU profiling, and a disk-bounded cache model for high-performance symbolication.

Tokens
301.7K
Snippets
833
Records
1.2K
Agent score
76%

What's inside Traceway

  1. Overview of traceway-cli capabilities

    main

    The traceway-cli is a Go-based command-line tool designed for querying and mutating data in a Traceway instance (either self-hosted or cloud). It is optimized for both human developers and LLMs (like Claude Code) by providing structured JSON output, stable exit codes, and human-readable tables.

    Core Capabilities (v1):

    • Authentication: Manage sessions via login, logout, and profile management.
    • Project Management: List projects and set a 'current' project per profile.
    • Observability Queries:
      • Exceptions: List, show details, archive, or resolve exceptions.
      • Logs: Query logs by service, severity, and time range.
      • Endpoints: List endpoints with performance metrics (p50, p95, p99) and error rates.
      • Metrics: Query raw metric data.
    • Mutations: Perform actions like archiving or resolving exceptions (requires confirmation or --yes flag).

  2. What is Traceway?

    main

    Traceway is an open-source error tracking and monitoring platform specifically designed for Go applications. It provides real-time visibility into application health through several key features:

    • Exception tracking: Monitor and capture errors as they occur.
    • Endpoint monitoring: Track the health and performance of your API endpoints.
    • Background tasks: Monitor the execution and status of asynchronous tasks.
    • System metrics: Observe system-level performance data.

    For a deeper understanding of the platform's architecture and core abstractions, refer to the Learn section.

  3. What is Traceway?

    main

    Traceway is an OpenTelemetry-native observability platform designed for high-performance telemetry ingestion and analysis. It unifies several observability pillars into a single system:

    • Logs: Structured, trace-linked logs with sub-second search via OTLP/HTTP.
    • Traces: End-to-end span waterfalls.
    • Endpoints: Per-route latency (P50/P95/P99), throughput, and error rate monitoring.
    • Metrics: Host, runtime, and custom metrics with custom widget groups.
    • Exceptions: Normalized, SHA-256 fingerprinted, and source-mapped stack traces.
    • Profiling (experimental): CPU, heap, and goroutine flame graphs (supports native Go pprof and OTLP profiles).
    • Session Replay: Web (JS) and Flutter session replay to visualize user actions before errors.
    • AI Observability: Monitoring LLM costs, tokens, latency, and conversations (supports OpenRouter and OTel-compatible gateways).

    Traceway is built to be OTel-first, meaning you can point any OTLP exporter directly at it without needing a separate Collector or vendor-specific SDKs.

  4. Platform support for React Native

    main

    Traceway supports error tracking across several React Native environments. Note that screen recording is currently not supported on any platform.

    PlatformError TrackingScreen Recording
    iOS (RN ≥ 0.72)YesNo
    Android (RN ≥ 0.72)YesNo
    Expo (SDK 49+)Yes — works in Expo GoNo
    Web (via React Native Web)YesNo

    If you are building a native Android-only app (without React Native), use the Android SDK. For Flutter apps, use the Flutter SDK. For browser-based apps, use the React SDK or generic JS SDK.

  5. Traceway Protocol Overview and Endpoint

    main

    The Traceway protocol is used to report telemetry data to the /api/report endpoint. A single POST request to this endpoint can contain multiple types of data: traces (endpoints and tasks), exceptions (errors and messages), metrics, and (for browser SDKs) sessions with session recordings. This endpoint is the primary ingestion point for all Traceway client SDKs.

    POST /api/report

  6. Supported Integrations for Traceway

    main

    Traceway integrates with various tools by shipping traces, metrics, and logs over OTLP/HTTP. No proprietary SDK is required for most integrations.

    Backend Integrations

    • Go Frameworks: Gin, Chi, Fiber, FastHTTP, net/http, and a Go Generic SDK.
    • Node.js/JS: Node.js, NestJS, Hono.
    • PHP: Symfony, Laravel.
    • Python: Django.
    • Edge/Other: Cloudflare Workers, OpenTelemetry.

    Frontend Integrations

    Note: Session Replay is included with every frontend integration and Flutter.

    • Frameworks: Next.js, React, Vue, Svelte, jQuery, and vanilla JavaScript.

    Mobile Integrations

    • Flutter, Android, iOS, and React Native.

    AI Integrations

    • OpenRouter.

  7. Performance characteristics of Traceway Flutter Session Replay

    main

    The Traceway Flutter Session Replay implementation is designed to provide visual context for exceptions with minimal impact on app performance. Key performance characteristics include:

    • Frame Timing: There is zero measurable frame-time regression at p50 across tested Android device tiers (Pixel 5, Pixel 6, Pixel 8). Jank counts remain flat during normal operation.
    • Memory Overhead: The 15 FPS capture loop adds approximately 14–29 MB of memory in steady-state idle conditions. In worst-case exception burst scenarios (e.g., Pixel 8), peak RSS stays under 70 MB above the baseline.
    • CPU Impact: Encoding is deferred and triggered only upon an exception, preventing the capture timer from competing with the render pipeline during normal operation.
    • Jank during Exceptions: During exception bursts, jank may increase (up to 3x on lower-end devices) due to the encoding work triggered by the exception.

    These metrics suggest the approach is safe for production use with screen recording enabled.

  8. Features of the Traceway JS SDK

    main

    The Traceway JS SDK includes several built-in capabilities for robust error tracking:

    • Automatic batching: Events are batched and sent periodically to reduce network overhead.
    • Retry with backoff: Failed uploads are automatically retried.
    • Stack trace capture: Full stack traces are captured for exceptions.
    • Custom attributes: Attach metadata to exceptions for better debugging.
    • Distributed tracing: Automatically correlates frontend errors with backend requests via fetch instrumentation (manual support is available for Axios).
    • Lightweight: Minimal bundle size impact.

  9. What is symbolication and how does it work?

    main

    Symbolication is the process of converting minified or obfuscated stack traces (e.g., at n (app.min.js:1:5114)) back into human-readable code references (e.g., validateCheckout (checkout.js:48:10)).

    A symbolicator service performs this by taking a minified stack frame (file, line, and column) and matching it against a build artifact, such as a source map (JavaScript), a .dSYM (iOS), or a .symbols file (Dart).

    The core logic can be modeled as:

    Symbolicate(file, line, col) -> (origFile, origLine, origCol, fnName)

  10. Overview of Traceway Rule Types

    main

    Traceway supports several rule types for monitoring your application, categorized by how they are evaluated:

    • On Ingest: Evaluated immediately as data arrives. Use these for immediate error detection or cost control.

      • New Issue: Detects never-before-seen errors.
      • Error Regression: Detects when a previously archived error reappears.
      • AI Trace Cost: Detects single AI traces exceeding a USD cost threshold.

    • Polled: Evaluated periodically over a lookback window. Use these for trend and threshold monitoring.

      • Error Rate / Endpoint Error Rate: Monitors 5xx percentage.
      • Error Count: Monitors total error volume.
      • Endpoint P95 / P99: Monitors latency percentiles.
      • Apdex Drop: Monitors user satisfaction scores.
      • Throughput Drop: Monitors request volume changes against a baseline.
      • Impact Score: Monitors endpoint health transitions (Critical/High/Medium).
      • Task Duration / Task Failure Rate: Monitors background task performance.
      • Metric Threshold: Monitors aggregated system or custom metrics.
      • No Data: Detects silence in telemetry.

  11. What is captured by the Symfony integration

    main

    Once the traceway/opentelemetry-symfony bundle is configured, it automatically captures the following telemetry:

    • Endpoints: Every HTTP request including the method and route template (e.g., GET /users/{id}).
    • Status codes: 2xx, 4xx, and 5xx responses.
    • Exceptions: Unhandled errors including full stack traces.
    • HTTP Metadata: Client IP, body size, and user agent.
    • Database Queries: Doctrine queries (requires doctrine/dbal to be installed).
    • Console Commands: Symfony CLI commands.
    • Messenger Jobs: Dispatched and consumed messages.

  12. Anatomy of a Source Map (Version 3)

    main

    A source map is a JSON object containing the following key fields used for symbolication:

    • version: The source map specification version (currently 3).
    • sources: An array of original file paths, referenced by index.
    • sourcesContent: An array containing the full original source text for each file in sources. This allows tools to display original code without access to the actual source files.
    • names: A flat array of original identifier strings (e.g., function names, variable names). These are referenced by index within the mappings field. Note that names are not deduplicated.
    • mappings: A string containing compressed VLQ-encoded data. It defines "point mappings" that link a specific column in the bundle to a source file index, an original line, an original column, and an optional name index.
    {
  "version": 3,
  "sources": ["../src/user.ts", "../src/index.ts"],
  "sourcesContent": ["export interface User...", "import { validateUser..."],
  "mappings": "MAIO,SAASA,EAAaC,EAAkB,CAC7C,IAAMC,EAAUD,EAAK,KAAK,KAAK,EAC/B,GAAIC,...",
  "names": ["validateUser", "user", "trimmed", "handleSignup", "form", "validateUser"]
}