{
  "slug": "modules/traces",
  "title": "Traces module",
  "description": "Distributed tracing for OpenTelemetry-style spans, service maps, and request waterfalls.",
  "url": "https://cuitty.com/docs/modules/traces",
  "markdown_url": "https://cuitty.com/docs/modules/traces.md",
  "json_url": "https://cuitty.com/docs/modules/traces.json",
  "frontmatter": {
    "title": "Traces module",
    "description": "Distributed tracing for OpenTelemetry-style spans, service maps, and request waterfalls.",
    "order": 9,
    "section": "Modules",
    "updatedAt": "2026-05-07"
  },
  "headings": [
    {
      "depth": 1,
      "slug": "traces-module",
      "text": "Traces module"
    },
    {
      "depth": 2,
      "slug": "what-it-captures",
      "text": "What it captures"
    },
    {
      "depth": 2,
      "slug": "ingest",
      "text": "Ingest"
    },
    {
      "depth": 2,
      "slug": "storage",
      "text": "Storage"
    },
    {
      "depth": 2,
      "slug": "reads",
      "text": "Reads"
    }
  ],
  "body_markdown": "# Traces module\n\nThe traces module accepts OTLP-style JSON spans and stores them in PostgreSQL tables keyed by project, trace id, and timestamp for request waterfall and service-map views.\n\n## What it captures\n\n- Trace id, span id, and parent span id\n- Service name, operation name, and span kind\n- Start and end timestamps\n- Status code and status message\n- Attributes, resource attributes, and events\n\n## Ingest\n\n```\nPOST /api/traces/ingest\n```\n\nThe JSON path is the first supported transport. OTLP protobuf support is still planned.\n\n## Storage\n\nSelf-hosted installs use stock PostgreSQL. High-volume span tables are partitioned by timestamp, and the portal reads rollup tables for summary views so trace detail remains available without requiring a PostgreSQL extension.\n\n## Reads\n\n| Endpoint | Returns |\n| --- | --- |\n| `GET /api/traces/status` | Module health |\n| `GET /api/traces?project_id=...` | Recent traces |\n| `GET /api/traces/{traceId}` | A trace waterfall |\n\nProduct page: [Traces](/product/modules/traces).",
  "body_html": "<h1 id=\"traces-module\">Traces module</h1>\n<p>The traces module accepts OTLP-style JSON spans and stores them in PostgreSQL tables keyed by project, trace id, and timestamp for request waterfall and service-map views.</p>\n<h2 id=\"what-it-captures\">What it captures</h2>\n<ul>\n<li>Trace id, span id, and parent span id</li>\n<li>Service name, operation name, and span kind</li>\n<li>Start and end timestamps</li>\n<li>Status code and status message</li>\n<li>Attributes, resource attributes, and events</li>\n</ul>\n<h2 id=\"ingest\">Ingest</h2>\n<pre class=\"astro-code github-dark\" style=\"background-color:#24292e;color:#e1e4e8; overflow-x: auto;\" tabindex=\"0\" data-language=\"plaintext\"><code><span class=\"line\"><span>POST /api/traces/ingest</span></span></code></pre>\n<p>The JSON path is the first supported transport. OTLP protobuf support is still planned.</p>\n<h2 id=\"storage\">Storage</h2>\n<p>Self-hosted installs use stock PostgreSQL. High-volume span tables are partitioned by timestamp, and the portal reads rollup tables for summary views so trace detail remains available without requiring a PostgreSQL extension.</p>\n<h2 id=\"reads\">Reads</h2>\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n<table><thead><tr><th>Endpoint</th><th>Returns</th></tr></thead><tbody><tr><td><code>GET /api/traces/status</code></td><td>Module health</td></tr><tr><td><code>GET /api/traces?project_id=...</code></td><td>Recent traces</td></tr><tr><td><code>GET /api/traces/{traceId}</code></td><td>A trace waterfall</td></tr></tbody></table>\n<p>Product page: <a href=\"/product/modules/traces\">Traces</a>.</p>",
  "links_out": [
    "/product/modules/traces"
  ]
}