How It Works
The developer-facing integration boundary — what the SDK captures, and how a trace reaches your dashboard.
How It Works
Incidentary operates entirely at your service boundary. Here is what happens from the moment you add the middleware to the moment you see a trace in your dashboard.
Integration boundary
Your service
│
│ HTTP request / response
▼
┌──────────────────────────────────┐
│ Incidentary SDK middleware │
│ │
│ 1. Reads/writes trace headers │
│ 2. Creates a causal event │
│ 3. Buffers in process memory │
│ 4. Flushes to Incidentary API │
└──────────────────────────────────┘
│
│ POST /api/v1/ingest/batch
│ (HTTPS, batched, async)
▼
Incidentary API
│
▼
Your dashboardThe SDK operates in-process and asynchronously. It does not block your request path. Events are batched in memory and flushed on a configurable interval (default: 2 seconds) or when the buffer reaches capacity.
What the SDK captures
For each inbound or outbound HTTP call, the middleware records:
| Field | Description |
|---|---|
trace_id | UUID shared across all services in a request chain |
ce_id | Unique ID for this causal event |
parent_ce_id | The upstream causal event that triggered this one |
service_id | Your serviceName config value |
wall_ts_ns | Wall-clock timestamp in nanoseconds |
kind | HTTP_IN or HTTP_OUT |
status | HTTP response status code |
duration_ns | Elapsed time in nanoseconds |
For the complete wire format, including propagation headers and batch payload schema, see Wire Format.
Trace propagation
The SDK propagates trace context between services using HTTP headers:
x-incidentary-trace-id— the trace UUID, stamped on every outbound requestx-incidentary-parent-ce— the CE ID of the upstream span, so Incidentary can reconstruct parent-child relationships
If no trace ID is present on an inbound request, the SDK mints a new one. This is the root span.
Pre-arm window
The SDK captures events continuously, not only when an alert fires. Events within the pre-arm window (default: 5 minutes before an alert) are retained so that when a page comes in, the causal trace is already assembled.
See Pre-Arm for configuration details.
No agent required
There is no sidecar, no daemon, no kernel module. The SDK is a library. You import it, add one middleware line, and set two environment variables. That is the entire installation surface.