Performance monitoring and tracing

Monitor → Performance shows how long your pages, API endpoints and background jobs take, where the time goes, and how often they fail. It takes traces from any Sentry SDK (point its DSN at Guidely, see ../error-monitoring.md) and from Guidely's own SDKs (web, Node and PHP), in the same tables, so a browser page load and the API calls it made show up as one trace.

ViewWhat it answers
OverviewThroughput, p50 / p95 duration, failure rate, apdex and user misery over time, and every transaction (sortable, searchable, filtered by operation and release)
Transaction summaryOne transaction: percentiles over time, duration histogram, suspect spans, spans by self time, slowest and recent events, related issues, tag breakdown, Web Vitals for page loads
Web VitalsLCP, INP, CLS, FCP and TTFB per page: p75 coloured good / needs improvement / poor, the split, and the p75 trend
QueriesEvery database query (values taken out so the same query groups together): calls, avg / p95 time, share of the time spent
Outbound HTTPCalls to other services by host and endpoint: p95, failure rate, time spent
AssetsScripts, stylesheets and images pages loaded, by load time
SpansSearch every span by operation (db, http.client, ui.*), description, minimum duration, status or tag:value
TraceThe waterfall of everything that shares a trace ID, across every project in the workspace, with the errors raised in it and a link to the session replay
Browser (Guidely SDK / @sentry/browser) ── pageload, navigation, fetch spans ──┐   sentry-trace / baggage / traceparent
                                                                              ├─→ PerfTransaction + PerfSpan ─→ hourly / daily rollups ─→ Performance pages
Servers (@guidelytech/node, @sentry/*…) ── http.server, db, http.client ──────┘           │
                                                                                          └─→ N+1 / slow query / … detectors ─→ performance issues (Errors)

Sending traces

Sentry SDKs

Use the project's DSN (Settings → Sentry SDKs (DSN)) and turn tracing on the way Sentry documents it. Nothing else changes:

Sentry.init({ dsn: "https://<key>@<your Guidely API host>/<id>", tracesSampleRate: 0.2, release: "web@2.4.0" });
sentry_sdk.init(dsn="https://<key>@<your Guidely API host>/<id>", traces_sample_rate=0.2)
  • Transactions (transaction envelope items) and span streaming (span items, v1 and v2, used by @sentry/* v10+ by default) are both accepted. Streamed spans are put back together into their transaction when its root span arrives.
  • Distributed tracing works as in Sentry: the SDKs pass sentry-trace and baggage between services; every project in the workspace that reported part of a trace shows in its waterfall.
  • Web Vitals: browser SDKs send LCP, FCP and TTFB on the page load, and INP / CLS as separate spans when the page is hidden. Both count.
  • Old SDKs that post transactions to /api/<id>/store/ work too.

Guidely web SDK

Settings → Privacy & data → Performance (admins), off by default. Turn on Trace page loads and requests and pick a sample rate (percentage of page loads). The web SDK then records:

  • a pageload transaction (Navigation Timing, resource loads, long tasks, marks and measures, fetch / XHR calls) with LCP, FCP and TTFB, and a ui.webvitals report with CLS and INP when the page is hidden;
  • a navigation transaction for every in-app route change;
  • sentry-trace, baggage and W3C traceparent headers on same-origin requests, so a Sentry or OpenTelemetry SDK on your server continues the trace.

Errors the SDK captures during a traced page load link to that trace. Requests to Guidely itself are never traced, query strings are removed from every URL, and nothing is sent without analytics consent. An installation can lower the rate or choose where headers go, but can't trace more than the project allows:

createGuidely({
  projectId: "pk_…",
  tracing: { tracesSampleRate: 0.5, tracePropagationTargets: ["api.example.com", /^\/api\//] },
  // tracing: false turns it off for this install
});

A string target matches anywhere in the URL; a RegExp must match. Without targets, only same-origin requests get headers (cross-origin headers would need CORS changes on the other server).

Guidely Node SDK

@guidelytech/node 0.18+ traces once its own sample rate is set (the web SDK's setting above doesn't apply to it, as with Sentry SDKs). The API is Sentry's (startSpan, continueTrace, tracesSampleRate, tracePropagationTargets); details are in the @guidelytech/node README.

const guidely = new Guidely({ secretKey: process.env.GUIDELY_SECRET_KEY!, environment: "production", tracing: { tracesSampleRate: 0.2 } });
app.use(guidely.expressRequestHandler()); // an http.server transaction per request, named by route
guidely.instrument({ pg }); // db spans for pg (mysql2 3.20+ needs nothing)
// Prisma: new NodeTracerProvider({ spanProcessors: [guidely.openTelemetrySpanProcessor()] }) + PrismaInstrumentation
  • Requests: the Express / Fastify / Koa middlewares record http.server transactions and continue sentry-trace / baggage / traceparent from the caller (the web SDK sends them).
  • Outgoing calls: fetch and http/https become http.client spans (diagnostics_channel, nothing patched) and get trace headers (http/https from Node 22.14).
  • Queries: pg and mysql2 become db spans and query breadcrumbs. mysql2 3.20+ publishes mysql2:query / mysql2:execute tracing channels; pg and older mysql2 are wrapped by instrument(). Prisma's queries come through its OpenTelemetry instrumentation and the SDK's span processor, re-parented under the request so loops show as N+1 queries. Literal values are taken out of the statement before it leaves the process.
  • Transactions are transaction messages in POST /api/v1/sdk/server/batch (a Sentry transaction event under transaction, its id as messageId), stored by ingestServerTraces(). Deploy the server first: older servers reject the whole batch.

Guidely PHP SDK

guidelytech/guidely-php 0.5+ traces the same way, with tracing: new TracingOptions(tracesSampleRate: …) on GuidelyTrack; details are in the guidelytech/guidely-php README.

  • Laravel (10+, Octane included): Laravel::instrument($guidely, $app) records a transaction per request (named by route) and per queued job (continuing the dispatcher's trace through the job payload), every query from QueryExecuted, Http:: calls as http.client spans with trace headers, and reports what the exception handler reports.
  • Elsewhere: traceRequest() (from $_SERVER or a PSR-7 request) plus setRoute(); instrumentPdo($pdo) for prepared statements, recordQuery() for ORM query events; a Guzzle middleware for outgoing calls; startSpan(), continueTrace() and getTraceHeaders() by hand.
  • PHP has no async context, so the active span is a stack per process: request and job transactions stay active until they end, startSpan() callbacks push and pop. Transactions go out with the end-of-request flush.

The numbers

  • Duration percentiles (p50, p75, p95, p99) come from log-scale histograms, accurate to about 5%.
  • Failure rate: transactions whose status isn't ok, cancelled or unknown (errors, timeouts, 4xx and 5xx responses), as in Sentry.
  • Apdex: (satisfied + tolerating / 2) / all, where satisfied is at most the threshold T and tolerating at most 4*T*. T is 300 ms unless you change it (the Apdex button on the Performance page, admins). A new threshold applies to past data as well.
  • User misery: users with a transaction over 4*T*, with Sentry's priors so a handful of users can't push it to 0 or 1. Users are counted per hour, using the threshold set at the time.
  • Throughput: transactions per minute over the period.
  • Self time: a span's duration minus the time covered by its child spans.
  • Web Vitals use Google's thresholds: LCP 2.5 s / 4 s, INP 200 / 500 ms, CLS 0.1 / 0.25, FCP 1.8 / 3 s, TTFB 800 ms / 1.8 s (good up to the first, poor above the second).

Periods up to three days are drawn per hour, longer ones per day (whole UTC days). New transactions show up within a few seconds of the page being refreshed (the pages bring their project's rollups up to date as they load; a worker job does it every minute for everyone else).

Performance issues

New transactions are checked for the problems Sentry reports as performance issues. Each one becomes an issue in Errors (category performance, level warning) with alerts and status like any error, and the issue page shows the offending spans with links to the transaction and the trace.

IssueFound when
N+1 Query5 or more sibling database spans run the same query (different values), together 50 ms or more
Slow DB Queryone query takes 1 s or more
Consecutive HTTP3 or more sequential outbound calls of 500 ms or more each that would save 2 s or more run in parallel
N+1 API Call10 or more sibling calls to the same endpoint with different ids, averaging 50 ms or more
Large Render Blocking Asseton a page load with FCP between 2 and 10 s, a script or stylesheet of 500 KB or more, loaded before FCP, takes a third of FCP or more
Uncompressed Asseta script or stylesheet of 512 KB or more is sent without gzip / brotli and takes 500 ms or more
Long Main Thread Taskslong tasks block the main thread for 1 s or more in one page load or navigation

An issue groups the same problem across transactions (an N+1 query is one issue wherever it runs). Turning error tracking off in Settings → Privacy & data stops performance issues too. Their occurrences don't count toward the errors allowance.

Quotas, retention and storage

  • Every span counts once toward the workspace's spans allowance, the transaction's root span included. When it runs out, Sentry SDKs are told to hold back (X-Sentry-Rate-Limits with category transaction or span) and the transactions are dropped whole.
  • Excluded traffic (Settings → Privacy & data: visitors, accounts, IP ranges) applies to traces too.
  • Transactions and spans are kept for the project's event retention and deleted by the worker every night, with their rollups.

Alerts

Metric alerts read transactionMetric() (server/services/performance-metrics.ts): p50, p75, p95, p99, avg (ms), failure_rate, apdex (0–1), throughput (per minute) and count, for all transactions or one name / op, from the hourly rollups (whole hours).

Code map

  • apps/web/src/server/sentry/handlers/transaction.ts: transaction and span envelope items.
  • apps/web/src/app/api/v1/sdk/traces/: Guidely SDK traces (same format as Sentry transactions).
  • apps/web/src/server/performance/: normalising (normalize.ts), storing (store.ts), problem detectors (detectors.ts) and their issues (issues.ts), rollups and retention (rollups.ts), worker jobs (jobs.ts).
  • apps/web/src/server/services/performance.ts: the dashboard API under /api/v1/projects/:id/performance/….
  • apps/web/src/lib/perf-histogram.ts: the histogram, apdex, user misery and Web Vitals maths.
  • apps/web/src/server/performance/sdk-traces.ts: ingestSdkTraces() (web SDK) and ingestServerTraces() (server SDK transaction messages).
  • packages/sdk-core/src/tracing.ts, web-vitals.ts, trace-propagation.ts: the web SDK side.
  • sdks/php/track/Tracer.php, Span.php, Sql.php, TracedPdoStatement.php, Laravel.php: the PHP SDK side.
  • packages/node/src/tracing/: the Node SDK side: spans and trace headers (span.ts), the tracer and request transactions (tracer.ts), outgoing HTTP (http.ts), pg / mysql2 (db.ts) and the OpenTelemetry span processor (otel.ts).
  • Tables: PerfTransaction, PerfSpan (raw, indexed by trace ID and time), PerfRollup, PerfSpanRollup (hourly and daily), PerfRollupDirty (hours waiting for their rollup).