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

  1. Create a project under Error Tracking and copy its DSN.
  2. Replace the DSN in Sentry.init({ dsn }) (or SENTRY_DSN). Nothing else in the SDK changes.
  3. 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, so sentry-cli and withSentryConfig send to Deutsche Cloud without any other change. Your existing org and project settings may stay as they are.
  4. Optional: set sentryUrl: 'https://errors.<your Deutsche Cloud domain>' in withSentryConfig. 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: false and scrub in beforeSend), 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-minute quota (20 000 by default).
  • Monthly cap: the errors.events-per-month quota (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) and errors.transactions-per-month (1 000 000) quotas. A refused transaction names only the transaction category, 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 fetch that 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/4810 and /orders/4811 are 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, add nodeProfilingIntegration(), and set profileSessionSampleRate: 1 with profileLifecycle: 'trace'. The older profilesSampleRate works too.
  • Browser: add browserProfilingIntegration() and set profileSessionSampleRate. The page must be served with the response header Document-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.0 and profile_lifecycle="trace" in sentry_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:

  1. Your fingerprint (scope.setFingerprint([...])). Supports {{ default }}, {{ transaction }}, {{ type }}, {{ value }}, {{ function }}, {{ module }}, {{ level }}, {{ message }} and {{ tags.<name> }}.
  2. 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.
  3. The crashed thread's stack, or the stack attached to a message.
  4. The message, with numbers, ids, emails, IP addresses, URLs, paths and quoted strings replaced, so user 123 not found and user 456 not found are 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_DSN and NEXT_PUBLIC_SENTRY_DSN, SENTRY_ENVIRONMENT (the app's environment, else production) and SENTRY_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 a SENTRY_AUTH_TOKEN minted 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 build

The 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):

  1. a new key; the managed secret's next version holds its DSN;
  2. 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);
  3. 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 build

The 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 build

The 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 as browser:"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-1A

An 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.

Did this page help you?