# 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.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/concepts/traces/

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

1. **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 `traceparent` header. It also sends the session's id, so the trace joins the session.
2. **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.
3. **Any other backend joins through OpenTelemetry.** An OTLP/HTTP trace exporter that honours `traceparent` adds its spans to the same trace. See [OpenTelemetry](https://docs.sypnia.com/sdks/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](https://docs.sypnia.com/concepts/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](https://docs.sypnia.com/api/otlp).

## 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](https://docs.sypnia.com/cloud/data-location-and-retention).
- Durations of all requests feed the API numbers in [Performance](https://docs.sypnia.com/concepts/performance), whether or not anyone opens the trace.

## Example: the failed payment

The trace of one click on **Pay**, as Sypnia shows it:

```text
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   <- failed
```

Three 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](https://docs.sypnia.com/api/traces). What each SDK traces automatically is in [Node](https://docs.sypnia.com/sdks/node) and [Next.js](https://docs.sypnia.com/sdks/nextjs).
