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.
| View | What it answers |
|---|---|
| Overview | Throughput, p50 / p95 duration, failure rate, apdex and user misery over time, and every transaction (sortable, searchable, filtered by operation and release) |
| Transaction summary | One 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 Vitals | LCP, INP, CLS, FCP and TTFB per page: p75 coloured good / needs improvement / poor, the split, and the p75 trend |
| Queries | Every database query (values taken out so the same query groups together): calls, avg / p95 time, share of the time spent |
| Outbound HTTP | Calls to other services by host and endpoint: p95, failure rate, time spent |
| Assets | Scripts, stylesheets and images pages loaded, by load time |
| Spans | Search every span by operation (db, http.client, ui.*), description, minimum duration, status or tag:value |
| Trace | The 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 (
transactionenvelope items) and span streaming (spanitems, 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-traceandbaggagebetween 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
pageloadtransaction (Navigation Timing, resource loads, long tasks, marks and measures, fetch / XHR calls) with LCP, FCP and TTFB, and aui.webvitalsreport with CLS and INP when the page is hidden; - a
navigationtransaction for every in-app route change; sentry-trace,baggageand W3Ctraceparentheaders 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.servertransactions and continuesentry-trace/baggage/traceparentfrom the caller (the web SDK sends them). - Outgoing calls:
fetchandhttp/httpsbecomehttp.clientspans (diagnostics_channel, nothing patched) and get trace headers (http/httpsfrom Node 22.14). - Queries:
pgandmysql2becomedbspans andquerybreadcrumbs. mysql2 3.20+ publishesmysql2:query/mysql2:executetracing channels;pgand older mysql2 are wrapped byinstrument(). 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
transactionmessages inPOST /api/v1/sdk/server/batch(a Sentry transaction event undertransaction, its id asmessageId), stored byingestServerTraces(). 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 fromQueryExecuted,Http::calls ashttp.clientspans with trace headers, and reports what the exception handler reports. - Elsewhere:
traceRequest()(from$_SERVERor a PSR-7 request) plussetRoute();instrumentPdo($pdo)for prepared statements,recordQuery()for ORM query events; a Guzzle middleware for outgoing calls;startSpan(),continueTrace()andgetTraceHeaders()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,cancelledorunknown(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.
| Issue | Found when |
|---|---|
| N+1 Query | 5 or more sibling database spans run the same query (different values), together 50 ms or more |
| Slow DB Query | one query takes 1 s or more |
| Consecutive HTTP | 3 or more sequential outbound calls of 500 ms or more each that would save 2 s or more run in parallel |
| N+1 API Call | 10 or more sibling calls to the same endpoint with different ids, averaging 50 ms or more |
| Large Render Blocking Asset | on 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 Asset | a script or stylesheet of 512 KB or more is sent without gzip / brotli and takes 500 ms or more |
| Long Main Thread Tasks | long 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-Limitswith categorytransactionorspan) 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:transactionandspanenvelope 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) andingestServerTraces()(server SDKtransactionmessages).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).