Error Tracking
Sentry-compatible: change the DSN, keep the SDK. Issues, source maps with sentry-cli, alerts.
Error Tracking speaks Sentry's protocol. The official Sentry SDKs (JavaScript, Next.js, Node,
Python, Go, and the rest) send to it unmodified, and sentry-cli and withSentryConfig upload
source maps to it. Errors are grouped into issues with readable stack traces, usually within a
second of happening. Events are stored in Germany, on Deutsche Cloud's own machines.
Coming from Sentry
- Create a project under Error Tracking and copy its DSN.
- Replace the DSN in
Sentry.init({ dsn })(orSENTRY_DSN). Nothing else in the SDK changes. - For source maps, create a token on the project's Setup tab and put it in
SENTRY_AUTH_TOKEN. The token carries the Deutsche Cloud URL and your organization, sosentry-cliandwithSentryConfigsend to Deutsche Cloud without any other change. Your existingorgandprojectsettings may stay as they are. - Optional: set
sentryUrl: 'https://errors.<your Deutsche Cloud domain>'inwithSentryConfig. It changes nothing about uploads, but it stops the bundler plugin from sending its own telemetry to sentry.io.
A tunnel route (an app that forwards browser envelopes through its own server) keeps working: the
envelope endpoint is https://errors.<domain>/api/<project number>/envelope/, and the DSN has no
path, so the endpoint derived from it is right. With withSentryConfig({ tunnelRoute }) nothing
changes either: the route forwards to whatever the DSN names. Next.js builds with Turbopack or
webpack upload the same way, and server, edge and browser stack traces are all source-mapped.
Evaluating side by side
To compare before switching, send to both for a while. In the browser
(instrumentation-client.ts), a second client that receives every envelope of the first is the
simplest way; on the server, the same works with NodeClient and makeNodeTransport:
import * as Sentry from '@sentry/nextjs';
Sentry.init({ dsn: process.env.SENTRY_DSN }); // your Sentry project, unchanged
const second = new Sentry.BrowserClient({
dsn: process.env.NEXT_PUBLIC_ERRORS_DSN, // this project's DSN
transport: Sentry.makeFetchTransport,
stackParser: Sentry.defaultStackParser,
integrations: [],
});
Sentry.getClient()?.on('beforeEnvelope', (envelope) => void second.getTransport()?.send(envelope));What does not come over
- History. Existing issues, their resolved or ignored state, assignees and comments stay in Sentry. Issues start fresh here, and grouping is close to Sentry's but not identical, so one Sentry issue may become two here or the other way round.
- Not available yet: inbound filters (browser extensions, legacy browsers, localhost, by
message or release), server-side data scrubbing (keep
sendDefaultPii: falseand scrub inbeforeSend), custom alert rules (alerts are new issue, regression and escalating, at most every 30 minutes per issue), the parts of Sentry's API beyond reading issues and events (so IDE plugins and Jira or Grafana integrations do not work yet; the Sentry MCP server's search and issue tools do, see below), suspect commits, release health, performance monitoring, Session Replay, profiling, cron monitors, and native crash reports (minidumps) and CSP reports. - Performance and Replay. Traces are kept (see Traces); span streaming
(
traceLifecycle: "stream") is not supported yet and shows nothing. Replays are refused with a one-hour rate limit for that category, so the Replay integration can be removed.
What is received
| Item | What happens |
|---|---|
event (errors, messages) |
Grouped into issues, stored for the project's retention |
attachment with its event (≤ 1 MiB) |
Stored with the event |
client_report |
Recorded on the project's Stats tab (what the SDK dropped and why) |
transaction (with its spans) |
Stored for the project's retention: the trace view and the Transactions tab |
session, sessions |
Release health: the Releases tab, kept 90 days (a Node.js server's process-wide session is counted, not kept) |
profile, profile_chunk |
Profiling: the flame graph of a transaction, from the trace view and an error's event (kept up to 30 days) |
span (span streaming), replay_*, check_in, log, feedback |
Not supported yet: answered with a one-hour rate limit for that category, so SDKs stop spending CPU and bandwidth on it |
Limits: an event up to 1 MiB, a request up to 20 MiB (decompressed). Bodies may be gzip, deflate,
brotli or zstd. The SDK authenticates with the DSN key in the X-Sentry-Auth header, in the
query string, or in the envelope header (tunnels).
Rate limits and the monthly cap
- Per project and per key: an optional events-per-minute limit (project Settings and each key).
- Per organization: the
errors.events-per-minutequota (20 000 by default). - Monthly cap: the
errors.events-per-monthquota (1 000 000 by default). It guards your spending and is raised under Service quotas. - Transactions have their own budget, so traffic in traces never holds up errors: the
errors.transactions-per-minute(20 000) anderrors.transactions-per-month(1 000 000) quotas. A refused transaction names only thetransactioncategory, so SDKs keep sending errors.
Over a limit, the ingest answers 429 with Retry-After and X-Sentry-Rate-Limits, which every
SDK honours: it pauses sending, and drops what it would have sent meanwhile. SDKs do not retry
a refused event. Per-minute limits are counted on each ingest machine, so the effective ceiling
can be up to twice the setting.
If the ingest is overloaded, a request waits up to two seconds for room before it is refused.
Traces
With tracesSampleRate above 0 in Sentry.init (0.1 is a good start), every sampled pageload,
navigation and server request arrives as a transaction with its spans, and the browser's and the
server's transactions of one request share a trace.
- An error's Trace field opens the trace: every transaction of it with its spans on one time
axis, the server's request under the browser's
fetchthat made it, and the error marked on the span it happened in. A server whose clock differs from the browser's is drawn where its caller's span starts, and the page says by how much it was off. Web vitals (LCP, FCP, CLS, TTFB) of a pageload are shown with it. - The project's Transactions tab lists transactions by name and operation over 24 hours or 7
days: the count, extrapolated from the sample rate (the sampled count beside it), p50, p75 and
p95 duration, and the failure rate (transactions whose status is not
ok). A name the SDK took from the raw URL (a Next.js App Router pageload, for one) is listed by its shape: a path segment that looks like an id (a number, a UUID or hex string, 25 characters or more) shows as*, so/orders/4810and/orders/4811are the one row/orders/*. Open one for its slowest examples. - Request cookies, credential headers and query strings (in URLs and span data) are not stored, nor is the client's address.
- Traces are not billed yet: what they take up counts towards the project's storage.
Alert rules
A project alerts on its own, as set in Settings → Default alerts: mail to the organization's owners and admins, and one webhook, on a new issue, a regression or a comeback. Alert rules add other conditions:
| When | Fires when |
|---|---|
| New issue / regression | as the default alerts do, with the rule's own filters and recipients |
| An issue gets many events | an issue reaches N events within M minutes |
| An issue affects many users | an issue reaches N distinct users within M minutes |
| A release's crash-free sessions drop | a release's crash-free sessions over the last hour fall below X %, with at least S sessions |
A rule can filter by level, environment and title, and it can mail people (the owners and admins, other addresses, or both). It can also post to a webhook as Slack, Microsoft Teams (Adaptive Card), Discord or Deutsche Cloud's signed JSON. The format is picked from the URL unless you choose one. A rule fires at most once per issue (or release) within its quiet period, 30 minutes by default, and Send a test checks its mail and webhooks right away. Recently fired lists the last 50 firings with what was sent. Thresholds are checked once a minute.
Database queries
The project's Queries tab lists the statements your app ran, taken from the db spans of its
sampled transactions. The SDKs' database integrations (Postgres, MySQL, Prisma and others) create
those spans on their own. Statements are grouped by their text without values, so WHERE id = 7
and WHERE id = 8 are one statement. For each one the tab shows:
- Time share: its share of all database time in the project.
- Calls, total, mean and slowest call.
- N+1: the transactions that ran it five or more times one after another under the same
parent. That is usually a loop that should be one query: a join, or
WHERE id IN (…).
A statement opens its own page with the slowest calls, the N+1 transactions and the projects that ran it. Each example opens its trace. When the statement ran on one of your organization's managed databases, the page links to the same statement in the database's query insights, and that page links back. In a trace, a db span's details link to its statement too.
Only the statement without its values is kept, never the values themselves.
Profiling
A profiler samples the call stack about a hundred times a second while a transaction runs. The transaction's flame graph then shows where the time went: callers on top, the functions they called below, and each frame as wide as its share of the samples. Open it from a profiled transaction in the trace view (marked profiled), or from the Profile field of an error's event. Below the graph, the slowest functions are listed by self time.
Turn it on next to tracing:
- Node.js (and the Next.js server): install
@sentry/profiling-node, addnodeProfilingIntegration(), and setprofileSessionSampleRate: 1withprofileLifecycle: 'trace'. The olderprofilesSampleRateworks too. - Browser: add
browserProfilingIntegration()and setprofileSessionSampleRate. The page must be served with the response headerDocument-Policy: js-profiling. Without it, the browser refuses to profile and the SDK quietly turns profiling off. Frames are source-mapped with the same uploads as errors. - Python: set
profile_session_sample_rate=1.0andprofile_lifecycle="trace"insentry_sdk.init.
Continuous profiles: the Profiles tab
A profiler can also run on its own, not per transaction: with profileLifecycle: 'manual' and
Sentry.profiler.startProfiler() (or profile_lifecycle="manual" and
sentry_sdk.profiler.start_profiler() in Python) it sends a chunk a minute that belongs to no
transaction. The project's Profiles tab shows them:
- A window: the last 15 minutes, hour or day, or a custom one of up to 7 days; drag across a spike in the samples-per-minute bars to make it the window. Filter by environment, release, runtime (Node.js, browser, Python) and, when several processes send, by profiler.
- One flame graph over every chunk in the window, on the busiest thread or the one you pick. Only my code keeps your frames (the same in-app rule as error frames) and counts library time as one outside your code frame. A window longer than about two hours merges an even sample of its chunks; the shares stay the same and the tab says how many were merged.
- Slowest functions by self time, with total time, share and
file:line. Click one to find it in the graph. Compare with the previous window adds the share each function had in the window just before.
The same data from the API: GET /errors/api/projects/{id}/profiles (the chunks, filters and
samples per minute) and …/profiles/flamegraph (the merged tree and the functions), as
dcloud errors profiles list and dcloud errors profiles flamegraph in the CLI. Both need
errors:GetEvents on the project.
Profiles are kept for the project's retention, at most 30 days. They have their own quotas,
errors.profiles-per-minute (2 000) and errors.profiles-per-month (500 000). A continuous
profiler sends one chunk a minute per process. A refused profile names only the profile
categories, so errors and traces keep flowing. Profiling is not billed yet.
Release health
Set release in Sentry.init (the bundler plugins set it for you) and the project's Releases
tab shows, per release, over 24 hours or 14 days:
- Crash-free sessions: sessions without an unhandled error. A session is one visit in the browser (a page load, or a navigation in a single-page app) and one request on a Node.js server. Both are sent by default.
- Crash-free users: users none of whose sessions crashed. Only users the app names
(
Sentry.setUser) are counted. The id is kept as a keyed hash, never as given. - Adoption: the release's share of the project's sessions in the range.
- New issues: issues first seen in the release. The release name opens its issues.
A rate is rounded down, so a release with any crash never reads 100 %. Sessions are kept for 90 days, whatever the project's retention. A Node.js server also sends one session for its whole process. That session is counted on Stats but not kept, because its requests already count. Release health is not billed.
Grouping
Events are grouped after source maps are applied, so two builds of the same code (with different chunk hashes and minified names) form one issue. The first rule that applies wins:
- Your fingerprint (
scope.setFingerprint([...])). Supports{{ default }},{{ transaction }},{{ type }},{{ value }},{{ function }},{{ module }},{{ level }},{{ message }}and{{ tags.<name> }}. - The exception: its type, plus the frames of your own code (module or file, and function).
Library frames (
node_modules, Next.js and React internals, the webpack runtime) are left out. - The crashed thread's stack, or the stack attached to a message.
- The message, with numbers, ids, emails, IP addresses, URLs, paths and quoted strings
replaced, so
user 123 not foundanduser 456 not foundare one issue.
The issue's Grouping tab shows what its fingerprint was computed from.
Source maps
Upload with debug IDs, which is what withSentryConfig, the bundler plugins and
sentry-cli sourcemaps inject + upload do. Frames are matched to their maps by debug ID. Legacy
uploads by release and URL (~/static/js/app.js.map) work as well. A frame is named after the
function that encloses its line in your original source, also when the minifier inlined that
function into its caller: the frame then reads totalOf (inlined into onClick).
A map is applied when the event arrives. A map uploaded later does not change events that already arrived, or how they were grouped. A frame whose map was missing at that moment is marked no source map on the issue page, and its minified position is kept: upload the maps for that release before the next deploy.
Connect an app
An app deployed here does not need a DSN or a token pasted anywhere. On the app's Environment page, Error Tracking → Connect (or the project's Setup page, Connect an app):
- At every build and rollout the app gets
SENTRY_DSNandNEXT_PUBLIC_SENTRY_DSN,SENTRY_ENVIRONMENT(the app's environment, elseproduction) andSENTRY_RELEASE(the deployment's commit). The browser variable can be renamed (VITE_SENTRY_DSN,PUBLIC_SENTRY_DSN) and any of them left out. - Every build also gets
SENTRY_ORG,SENTRY_PROJECT,SENTRY_URL, and aSENTRY_AUTH_TOKENminted for that build: it may upload source maps to this project only, expires after 30 minutes and is revoked as soon as the build ends, whatever its outcome. The deployment's build log says which token it got and whether source maps arrived. - A variable the app defines itself always wins, so an app that still sends to another Sentry keeps its own settings.
- Connect & rebuild rebuilds the live commit, so the DSN reaches the browser bundle.
With Railpack (no Dockerfile) nothing else is needed. With a Dockerfile, declare the variables the browser bundle needs and mount the token as a secret in the build step:
ARG NEXT_PUBLIC_SENTRY_DSN
ARG NEXT_PUBLIC_SENTRY_ENVIRONMENT
ARG SENTRY_RELEASE
ARG SENTRY_ORG
ARG SENTRY_PROJECT
ARG SENTRY_URL
RUN --mount=type=secret,id=SENTRY_AUTH_TOKEN,env=SENTRY_AUTH_TOKEN npm run buildThe token is a BuildKit secret, never a build argument, so it cannot end up in the image.
The DSN is filed in Secrets as a managed entry (ERRORS_<PROJECT>_DSN, group
error-tracking): read-only there, with every app and CI environment that uses it in its flow.
It is on a key of its own (Managed on the Setup page), so rotating it never touches a DSN you
pasted somewhere by hand.
Rotate key
Setup → Managed key → Rotate key (or POST /errors/api/projects/{id}/rotate-key):
- a new key; the managed secret's next version holds its DSN;
- every connected app is rebuilt and redeployed (the old DSN is inlined in its browser bundle, so reusing the image would keep sending with it);
- the previous key keeps accepting events until the grace is over (default 24 hours, 10 minutes to 7 days) and every connected app runs a build made after the rotation. A rebuild that fails holds the revocation. Revoke previous key now ends it early.
Apps that run an image or a compose file built elsewhere get the new DSN at run time, but their browser bundles keep the old one until you rebuild them; the rotation lists them.
CI environments
A repository's CI environment can be connected too (Setup → Connect a CI environment). A job
that runs in that environment with permissions: id-token: write exchanges its identity token
for an upload token, the DSN, the environment and the release. Pull-request runs get nothing, and
the token is revoked when the run ends.
permissions:
id-token: write
contents: read
jobs:
build:
runs-on: ubuntu-latest
environment: production # the connected environment
steps:
- uses: actions/checkout@v4
- name: Error Tracking upload token (no stored secret)
run: |
AUD=$(jq -rn --arg a 'https://errors.<root>' '$a|@uri')
OIDC_TOKEN=$(curl -sS --fail-with-body \
-H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUD" | jq -r .value)
OUT=$(curl -sS --fail-with-body -X POST 'https://console.platform-development.deutschecloud.app/errors/api/upload-token/exchange' \
-H 'content-type: application/json' \
-d "$(jq -n --arg t "$OIDC_TOKEN" '{webIdentityToken: $t}')")
TOKEN=$(jq -r .data.token <<<"$OUT")
echo "::add-mask::$TOKEN"
{
echo "SENTRY_AUTH_TOKEN=$TOKEN"
echo "NEXT_PUBLIC_SENTRY_DSN=$(jq -r .data.dsn <<<"$OUT")"
echo "SENTRY_RELEASE=$(jq -r .data.release <<<"$OUT")"
} >> "$GITHUB_ENV"
- run: npm ci && npm run buildThe audience is the Error Tracking URL, not the console's: a token minted for the STS is refused here.
Builds on GitHub Actions
A workflow on GitHub's own runners gets a short token the same way, through
workload identity federation: register GitHub under IAM →
Identity providers, create a role whose trust policy names your repository and whose policy
allows errors:UploadSourceMaps, errors:ListProjects and errors:ListReleases on the project.
The job trades GitHub's token for a temporary access key, and that for a project-only upload
token of at most 15 minutes (POST /errors/api/projects/{id}/upload-token):
permissions:
id-token: write
contents: read
jobs:
build:
runs-on: ubuntu-latest
env:
EWS_API_URL: https://console.platform-development.deutschecloud.app
EWS_ROLE_RN: rn:ews::<org-id>:iam:role/<role-id>
steps:
- uses: actions/checkout@v4
- name: Error Tracking upload token (OIDC, no stored secret)
run: |
AUD=$(jq -rn --arg a "$EWS_API_URL" '$a|@uri')
OIDC_TOKEN=$(curl -sS --fail-with-body \
-H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUD" | jq -r .value)
CREDS=$(curl -sS --fail-with-body -X POST "$EWS_API_URL/iam/api/sts/assume-role-with-web-identity" \
-H 'content-type: application/json' \
-d "$(jq -n --arg role "$EWS_ROLE_RN" --arg t "$OIDC_TOKEN" '{roleRn: $role, webIdentityToken: $t, durationSeconds: 900}')")
KEY=$(jq -r .data.accessKey <<<"$CREDS")
echo "::add-mask::$KEY"
OUT=$(curl -sS --fail-with-body -X POST "$EWS_API_URL/errors/api/projects/<project-id>/upload-token" \
-H "Authorization: EWS-ACCESS-KEY $KEY" -H 'content-type: application/json' \
-d '{"ttlSeconds": 900}')
TOKEN=$(jq -r .data.token <<<"$OUT")
echo "::add-mask::$TOKEN"
echo "SENTRY_AUTH_TOKEN=$TOKEN" >> "$GITHUB_ENV"
- run: npm ci && npm run buildThe manual token (Setup → Source maps → Create token) stays for builds that can do neither.
Issues
- Default view: unresolved issues, newest activity first. Sort by first seen, events or users. Filter by status, level and environment.
- Search uses Sentry's syntax:
is:resolved,level:error,environment:production,release:1.2.3,assigned:me, any tag asbrowser:"Chrome 131", and free text over the title and where it happened. - Resolve: a new event reopens the issue as regressed and alerts.
- Resolve in the next release: only an event from a newer release reopens it.
- Ignore: for an hour, for a day, until 100 more events, or forever. When it comes back, it is escalating and alerts.
- Users affected counts
user.id, else email, else username. When an event names no user, it counts by a key derived from the sender's address that changes every day. The address itself is not stored unless the project's Keep client IP addresses is on.
Alerts
For a new issue, a regression, or an ignored issue that comes back, at most once per issue every 30 minutes:
- Email to the organization's owners and admins (switchable), plus addresses you add.
- Webhook: a JSON
POST(type: ews.errors.issue.created | regressed | escalating). A Slack incoming-webhook URL gets Slack's message format.
Retention and deletion
Events are kept 30, 60 or 90 days (project Settings). Resolved and ignored issues with no events left go with them. Deleting a project revokes its keys within seconds and deletes its issues and events.
Price
| What | Price |
|---|---|
| Error events, first 10 000 a month | free |
| up to 1 000 000 a month | €0.15 per 1 000 |
| up to 10 000 000 | €0.08 per 1 000 |
| beyond | €0.04 per 1 000 |
| Stored events, attachments, source maps | €0.10 per GB-month |
| Trace spans, first 1 000 000 a month | free |
| beyond | €2.00 per million, metered, not charged yet |
| Profile hours, first 10 a month | free |
| beyond | €0.03 per hour, metered, not charged yet |
The tiers count accepted error events per organization and calendar month. Refused events and sessions are not billed. Traces are measured in spans: every span of an accepted transaction, the transaction's own included. Profiling is measured in profile hours: the length of every transaction profile and continuous-profiling chunk. For now both are metered, not charged yet. Your usage and what it would cost appear under Billing → Usage, and you will be told before charging starts.
API, CLI, MCP
The service is errors (/errors/api), with IAM actions errors:ListProjects, CreateProject,
UpdateProject, DeleteProject, ListIssues, UpdateIssue, DeleteIssue, GetEvents,
UploadSourceMaps and ListReleases, all on the project's RN
(rn:ews:de1:<org>:errors:project/<id>).
dcloud errors projects create --name web --platform javascript-nextjs
dcloud errors issues list --id <project id> --query "is:unresolved level:error"
dcloud errors events latest --issue-id WEB-1AAn issue is named by its short id everywhere: WEB-1A is what the console shows, what alert mails
and webhooks carry, and what the console URL (/errors/issues/WEB-1A), the API and the CLI accept.
The plain number (46) works too.
Sentry's own API is served at https://errors.<domain>/api/0/ for sentry-cli and Sentry API
clients: auth info, organizations, projects and keys, releases (create, finalize, deploys,
commits), chunk upload, artifact bundle assembly, and release files, and the issue and event
read API:
| Endpoint | What |
|---|---|
GET organizations/{org}/issues/ |
Issues, with Sentry's search syntax, sort, statsPeriod, paging |
GET organizations/{org}/issues/{id or short id}/ |
One issue |
GET organizations/{org}/issues/{id}/events/latest/ |
Its latest event (also oldest or an event id), source-mapped |
GET organizations/{org}/events/?dataset=errors&field=… |
Error events as rows, or grouped with count(), count_unique(user), last_seen(), first_seen() |
GET organizations/{org}/events/validate/ |
Whether such a search is supported |
GET organizations/{org}/environments/ |
The environments seen |
The events search understands level:, environment:, release:, issue: (short id),
error.type:, user.id:, user.email:, user.username:, transaction: and free text over the
title. Anything else is answered with an error naming what is supported, never silently ignored.
The Sentry MCP server (@sentry/mcp-server) works with it: search_issues, search_errors,
get_issue_details, find_organizations and find_projects were run against it. Point it here
and give it a token from a project's Setup tab:
{
"mcpServers": {
"sentry": {
"command": "npx",
"args": ["-y", "@sentry/mcp-server"],
"env": {
"SENTRY_HOST": "errors.<your Deutsche Cloud domain>",
"SENTRY_AUTH_TOKEN": "<the token>",
"DO_NOT_TRACK": "1"
}
}
}
}DO_NOT_TRACK stops the MCP server's own telemetry to sentry.io. Links it prints
(https://errors.<domain>/organizations/…/issues/WEB-1A) open the issue in the console.