---
title: Traces module
description: Distributed tracing for OpenTelemetry-style spans, service maps, and request waterfalls.
section: Modules
order: 9
updatedAt: 2026-05-07
slug: modules/traces
---
# Traces module

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.

## What it captures

- Trace id, span id, and parent span id
- Service name, operation name, and span kind
- Start and end timestamps
- Status code and status message
- Attributes, resource attributes, and events

## Ingest

```
POST /api/traces/ingest
```

The JSON path is the first supported transport. OTLP protobuf support is still planned.

## Storage

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.

## Reads

| Endpoint | Returns |
| --- | --- |
| `GET /api/traces/status` | Module health |
| `GET /api/traces?project_id=...` | Recent traces |
| `GET /api/traces/{traceId}` | A trace waterfall |

Product page: [Traces](/product/modules/traces).