Traces
How Sypnia follows one request from a click in the browser to your API and the database calls behind it, and what a trace stores.
This page is for anyone who wants to see where a request spent its time or where it failed. Traces are part of the open-source engine and work the same on Sypnia Cloud.
A trace is the path of one request across your app: from the browser to your API to the database calls and services behind it, with how long each step took and whether it failed.
Spans
A trace is made of spans. A span is one step. Every span has the same shape, whatever produced it:
| Field | Meaning |
|---|---|
| Name | What the step is: POST /api/checkout, SELECT carts. |
| Kind | What sort of step: a request as the browser saw it, a request a service handled, a database call, a call to another service, or an internal step. |
| Service | Which part of your app ran it, such as shop-api. The browser is browser. |
| Start and duration | When it began and how long it took. |
| Status | Whether it succeeded or failed. In a partial trace, a step can also be still running. |
| Attributes | A limited set of details, such as the route or the status code: up to 64 for each span, with values of up to 256 characters. |
| Parent | The span that caused it. This is what gives a trace its tree shape. |
Database calls are spans like any other. The shape is compatible with OpenTelemetry, so spans from a Sypnia SDK and spans from an OpenTelemetry exporter sit in the same trace.
How a trace connects
- The browser SDK starts it. When the page calls your API, the SDK creates a trace id and sends it with the request in the standard W3C
traceparentheader. It also sends the session’s id, so the trace joins the session. - Your server continues it. The Node and Next.js SDKs read the header and trace every incoming request automatically. You do not place any calls by hand. They record the request and the database and service calls it makes.
- Any other backend joins through OpenTelemetry. An OTLP/HTTP trace exporter that honours
traceparentadds its spans to the same trace. See OpenTelemetry.
A request that does not start in a browser, such as a webhook or a scheduled job, is a trace of its own, started by the server.
A trace connects parts of one project. Send your frontend and your backend to the same project.
When a span has failed
A call has failed when it gets no answer, answers 400, or answers 500 or above. A request your server received has failed when it answers 500 or above, or throws. Spans that arrive through OpenTelemetry have failed when their status is ERROR or they carry an exception.
Other answers, such as 401, 404 or 409, are answers, not failures.
A failed span is a failure in the sense of Problems: the deepest failed span of a trace decides which problem the trace belongs to.
Requests that never finish
A request that is still running after 20 seconds is reported at that moment as a partial trace: the spans that finished, and the calls still in flight with how long they had been running (Node and Next.js SDKs).
- If the request finishes later, its full trace replaces the partial one.
- If it never finishes, because the platform killed it, the partial trace is all there is. It counts as a server failure and opens a problem titled like «Timeout: POST /api/checkout did not finish». The calls that were in flight tell you what it was waiting for.
What a trace stores, and what it does not
Sypnia stores what is needed to see the shape and the timing of a request:
- the name, kind, timing and status of each span,
- the method, route and status code of requests,
- the target of a call: a table name, a service’s host and path,
- a limited set of attributes for each span.
A request your server handled keeps up to 200 of the calls it made, and a trace keeps up to 500 spans. Beyond that the spans are counted and not stored.
It does not store request or response bodies, cookies or headers. Attributes whose name contains authorization, cookie, password, secret or token are dropped at ingest. The exact limits are in the API reference.
Counting and keeping
- On Sypnia Cloud, one trace counts as one event, however many spans it has. The browser’s request and the server’s spans under the same trace id are one trace.
- Traces are kept as long as events. See Data location and retention.
- Durations of all requests feed the API numbers in Performance, whether or not anyone opens the trace.
Example: the failed payment
The trace of one click on Pay, as Sypnia shows it:
click «Pay $64.00» browser
└─ POST /api/checkout 412 ms 400 shop-api
├─ SELECT carts 18 ms ok database
├─ SELECT cart_items 22 ms ok database
└─ POST /v1/payments 340 ms 400 payment service <- failedThree services took part: the browser, the shop’s API and the payment service. The two database calls worked. The call to the payment service answered 400, and it is the deepest failed span, so this trace belongs to the problem about the payment call. The API then answered 400 to the page, which showed nothing, and the customer clicked again.
The trace says where it broke. The problem says why: the request to the payment service had no amount, because the checkout reads cart.total and the release deployed yesterday renamed it to cart.totalCents.
Reference
The fields of a trace and a span are in the API reference. What each SDK traces automatically is in Node and Next.js.