Performance monitoring

Okapi stores the transactions and spans that Sentry SDKs send, on the same DSN as your errors and logs. You get trace views, a list of expensive database queries, and performance issues for slow queries and N+1 queries. Performance monitoring is for backend services; see What is not included.

Turn on tracing in your SDK¶

Set a trace sample rate when you initialize the SDK. With no sample rate, the SDK sends no traces.

Sentry.init({
  dsn: "https://<public-key>@okapi.example.com/<project-number>",
  tracesSampleRate: 0.2, // send 20% of transactions
});

In JavaScript, the option is tracesSampleRate; in Python, it is traces_sample_rate. Other SDKs use their own name for the same option. Start with a low rate on a busy service: every sampled transaction is stored, and spans use disk.

The SDK sends transactions and spans in envelopes to /api/{project_id}/envelope/. The legacy /store/ endpoint accepts errors only. Okapi's compatibility tests use raw envelopes from @sentry/node 10.65.0 and sentry-sdk (Python) 2.65.0.

What Okapi stores¶

• Spans, with their timing, operation, description and up to 100 scalar attributes each. Database spans also keep a sanitized query text.
• Trace segments, a summary of each transaction: name, duration, status, release and environment.
• Trace IDs on events and logs, so an error and its logs link to the trace they belong to.

Okapi removes known AI prompt, response, system, embedding and tool-content attributes from spans when it processes them. It keeps model, provider, operation and token-count metadata. This filter does not change the raw payload: Okapi writes each payload to its performance queue before processing, and a payload that fails processing stays in the queue until retention removes it. If you must not store some content, configure the SDK to leave it out.

All of this is in your Postgres database. Back up the whole database as usual (see Backups).

The Performance pages¶

A project's Performance section has four pages:

• Overview — transactions, throughput, error rate and p50, p75 and p95 latency, a transaction-rate chart, the slowest and highest-throughput transactions, expensive queries, and recently active performance issues.
• Traces — search traces by time, duration, status, release or environment, and open one as a waterfall of its spans, with the errors and logs of the same trace.
• Queries — normalized database queries, sorted by total duration, count, mean, p95, maximum or latest seen.
• Performance Issues — the slow-query and N+1 issues that Okapi found.

Performance issues¶

Okapi checks each trace with two detectors:

A finding becomes a performance issue, grouped like an error issue: repeats add occurrences to the same issue. You can resolve, unresolve, ignore and snooze a performance issue. A resolved performance issue that occurs again is a regression.

Performance issues stay after their raw traces expire, until you delete the project. An occurrence whose trace has expired shows "Trace sample expired".

Alerts on performance issues¶

On a project's Alerts page, create a rule and set Source to Performance. Two triggers are available:

• New issue occurs (performance_new_issue) — a detector opens a new performance issue.
• Resolved issue comes back (performance_regression) — a resolved performance issue occurs again.

Choose a detector (All detectors, Slow query or N+1 query). Performance rules do not use the error filters, and they exist on project Alerts pages only, not on views. They deliver like any other rule: personal rules to email and the in-app inbox, team rules to notification channels. A webhook payload carries the trigger name as its kind.

Retention and volume¶

Raw spans, trace segments and performance issue occurrences are kept for OKAPI_TRACE_RETENTION_DAYS days (default 14). 0 turns off pruning of performance data. The downloaded compose file does not pass this variable; set it in an override file (see Setting variables the compose file does not list).

On self-host, span volume has no quota. Spans count toward the per-DSN ingest rate limit: each further block of 100 spans in a request costs one more token (see OKAPI_INGEST_RATE_LIMIT in Installation). A separate safety limit, OKAPI_APM_QUEUE_LIMIT (default 100000 pending items), sheds only transactions and spans when the performance backlog is full, so errors and logs keep flowing.

For agents¶

Over MCP, search_traces, get_trace, list_expensive_queries, search_performance_issues and get_performance_issue read this data with the read role. update_performance_issue triages a performance issue with the triage role.

What is not included¶

Okapi does not accept OpenTelemetry (OTLP) data. It has no browser performance dashboards or web-vitals analytics, no profiling, no database query plans, no custom detectors, and no tail or dynamic sampling.

Next: Views — named sets of projects you read and alert on as one.