# Profile your code

Turn on the Sentry SDK's profiler, then see where a transaction spent its time as a flame graph, or merge a process's continuous profiles over a window.

A flame graph shows callers on top and the functions they called below, each frame as wide as its
share of the samples. Frames are source-mapped with the same uploads as errors. Replace
_project-id_ with the project's id and _event-id_ with a transaction's event id.

## Turn on the profiler

Turn on tracing first (see [View traces and transactions](view-traces-and-transactions.md)), then:

- **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`. Serve the
  page with the response header `Document-Policy: js-profiling`; without it the browser refuses to
  profile.
- **Python**: set `profile_session_sample_rate=1.0` and `profile_lifecycle="trace"` in
  `sentry_sdk.init`.

For a profiler that runs on its own rather than with each transaction, use
`profileLifecycle: 'manual'` and `Sentry.profiler.startProfiler()` (in Python
`profile_lifecycle="manual"` and `sentry_sdk.profiler.start_profiler()`). A continuous profiler
sends a profile chunk a minute per process; the **Profiles** tab merges those chunks.

Profiles are kept for the project's retention, at most 30 days. They have their own quotas, and a
refused profile names only the profile categories, so errors and traces keep flowing (see
[Quotas](quotas.md)). Profile hours are metered (see [What is Error Tracking?](what-is.md)).

## Prerequisites

- Permission for `errors:GetEvents` on the project. Without it, the **Profiles** tab says "You can
  see this project but not its profiles."
- To read one transaction's profile through the API or the CLI, `errors:GetEvents` on the service,
  `rn:ews:de1:<organization id>:errors:*` (without it, `403`); the console's profile page needs it
  only on the project.
- In the console, also `errors:ListProjects` on the project to open it (without it the project is
  not found).

## See a transaction's profile

**Console**
1. Open a trace, and choose a transaction the waterfall marks as profiled. Or open an issue whose
   event shows a **Profile**, and choose **Flame graph**.

The page shows the transaction's flame graph and, below it, its 25 slowest functions by self time.
When the transaction has no profile, it says "No profile was received for this transaction."

**CLI**
```sh
dcloud errors profiles get event-id
```

**API**
```http
GET /errors/api/profiles/event-id
```

The answer has the call `tree`, the 100 slowest `functions` (self and total milliseconds) and
`kind`: `transaction` (its own profile), `continuous` (the chunks that cover it) or null when it
has none.

## Merge continuous profiles over a window

**Console**
1. Open the project, then the **Profiles** tab.
2. Choose **15 min**, **1 h**, **24 h** or **Custom** (up to 7 days).
3. (Optional) Under **Environment**, **Release** or **Runtime**, choose a value. **Profiler** and
   **Thread** appear when the window has more than one; **Thread** shows **Busiest** until you
   choose one.
4. (Optional) Turn on **Only my code** to keep your own frames and count library time as one frame.
5. (Optional) Under **Slowest functions**, turn on **Compare with the previous window**.

**Samples per minute** shows when profiles arrived. The **Flame graph** merges at most 120
one-minute profiles; a longer window is sampled evenly, and the shares stay the same.

**CLI**
```sh
dcloud errors profiles list project-id --window 24h --runtime node
dcloud errors profiles flamegraph project-id --window 24h --my-code 1 --compare 1
```

**API**
```http
GET /errors/api/projects/project-id/profiles/flamegraph?window=custom&from=2026-11-17T00:00:00Z&to=2026-11-18T00:00:00Z
```

`400` for a custom window without `from` and `to`, ending before it starts, or longer than 7 days.

## Related

- [View traces and transactions](view-traces-and-transactions.md)
- `errors.profiles.flamegraph` · `dcloud errors profiles list`
