Docs

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 EngineCloud At launch

View as Markdown
On this page
  1. Spans
  2. How a trace connects
  3. When a span has failed
  4. Requests that never finish
  5. What a trace stores, and what it does not
  6. Counting and keeping
  7. Example: the failed payment
  8. Reference

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:

FieldMeaning
NameWhat the step is: POST /api/checkout, SELECT carts.
KindWhat 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.
ServiceWhich part of your app ran it, such as shop-api. The browser is browser.
Start and durationWhen it began and how long it took.
StatusWhether it succeeded or failed. In a partial trace, a step can also be still running.
AttributesA 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.
ParentThe 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.

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:

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. What each SDK traces automatically is in Node and Next.js.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close