Profiles

SDKs SHOULD collect profile samples at a frequency of 101Hz (roughly once every 10 milliseconds).

The 101Hz value is intentional to avoid lockstep sampling — a condition where profiling samples occur at the same frequency as a loop in the application. (since 2.1.1) 101 was chosen for its primality; 99 (1 below 100) is evenly divisible by several smaller numbers, which could lead to similar lockstep behavior.

SDKs implementing continuous profiling MUST support two lifecycle modes:

Manual mode (profile_lifecycle: 'manual'):

• The profiler is controlled via start_profiler() and stop_profiler().
• Profiling only respects profile_session_sample_rate (independent of spans).
• If the session is sampled, start_profiler() starts the profiler.

Trace mode (profile_lifecycle: 'trace'):

• This mode requires tracing to be enabled. SDKs SHOULD log a warning if profile_lifecycle is set to 'trace' but tracing is disabled.
• The profiler starts automatically when there is at least one active root span and stops when there are no active root spans (letting the current chunk finish).
• Profiling respects both profile_session_sample_rate and the tracing sampling configuration (traces_sample_rate or traces_sampler).
• profile_session_sample_rate is checked first. If the session is not sampled, no profiling will occur.
• (since 2.3.1) Only if a root span is sampled (based on traces_sample_rate / traces_sampler), profiling will start. Profile sampling is re-evaluated for each root span.
• The profiler runs as long as there is at least one sampled root span. If multiple root spans overlap, profiling continues until the last sampled root span finishes.

For continuous profiling (V2), additional context MUST be attached to transaction and span payloads to link them to profile data.

Profile context (.contexts.profile): SDKs MUST include the profiler_id in the profile context of transactions so the profile can be associated back to the transaction.

Trace context (.contexts.trace.data): SDKs MUST include thread.id in the trace context data to identify which thread is associated with the transaction. thread.name MAY be included.

Span data (.spans[].data): SDKs MUST include thread.id in span data. thread.name and profiler_id (to override the trace context value) MAY be included.

A V2 profile chunk exists independently and is sent as a profile_chunk envelope item.

V2 Metadata Fields

Both V1 and V2 formats share the same profile object structure:

Measurements

Measurement values differ between V1 and V2:

• V1: Uses elapsed_since_start_ns (nanoseconds since profile start, uint64 as string) and value (float64).
• V2: Uses timestamp (Unix timestamp in seconds with microsecond precision, float64) and value (float64).

Currently supported measurements: frozen_frame_renders and slow_frame_renders.

Accepted measurement units: nanosecond, ns, hertz, hz, byte, percent.

Relay rejects a V2 profile chunk if any of these conditions are true:

• Chunk data is missing (no frames, no samples, no stacks)
• Required metadata is missing
• Chunk size exceeds 50 MB

SDKs SHOULD validate these conditions before sending.

SDKs SHOULD remove unnecessary data like thread entries without samples from thread_metadata.

A V2 profile chunk MUST be serialized as JSON and sent in an envelope with item type profile_chunk.

(since 2.4.0) The platform item header is REQUIRED for rate limiting and categorization and MUST match the platform field in the payload.

{"event_id":"a229377b82ad4898be7c3a6272d052d9"}
{"type":"profile_chunk", "platform":"node"}
{ /* profile_chunk JSON payload */ }

For V2 continuous profiling, SDKs MUST modify transaction and span payloads to enable profile linking.

Profile context (.contexts.profile):

Trace context data (.contexts.trace.data):

Span data (.spans[].data):

SDKs implementing continuous profiling MUST accept a profileSessionSampleRate configuration option (number, 0.0–1.0, default 0). The sampling decision is made once when the SDK is initialized.

The definition of a profiling session depends on the profiling type:

• Continuous Profiling: The session starts when the SDK is configured and stops when the service terminates. profileSessionSampleRate controls the percentage of service instances with profiling enabled. Sampling is re-evaluated on restart or redeployment.
• UI Profiling: The session corresponds to a user session (SDK initialization to tab close or session end). On mobile, backgrounding and foregrounding starts a new session with re-evaluated sampling. If a trace is active when the app is foregrounded, the existing profiling session continues until the last root span in that trace finishes.

If profilesSampleRate or profilesSampler are configured for transaction-based profiling, profileSessionSampleRate has no effect. SDKs SHOULD log a warning in this case.

Naming SHOULD follow the SDK's language conventions:

• profileSessionSampleRate (JavaScript)
• profile_session_sample_rate (Python)

SDKs implementing continuous profiling MUST accept a profileLifecycle configuration option with values 'trace' or 'manual' (default: 'manual').

See Profile Lifecycle Modes for behavior details.

Naming SHOULD follow the SDK's language conventions:

• profileLifecycle (JavaScript)
• profile_lifecycle (Python)

Mobile SDKs MAY accept a startProfilerOnAppStart configuration option (boolean, default false).

When true, profiling starts as early as possible during app startup, before startProfiler() can be manually called. The profileSessionSampleRate for app start profiling is evaluated on the previous app launch and applied on the next launch, since the sample rate cannot be evaluated at launch time.

Behavior with profileLifecycle:

• 'manual': Profiling starts on startup. The developer MUST call stopProfiler() when startup is complete.
• 'trace': Profiling starts on startup and stops automatically when the root span associated with app startup ends.

Naming SHOULD follow the SDK's language conventions:

• start_profiler_on_app_start (Python)

SDKs implementing continuous profiling SHOULD expose a function to start the profiler:

startProfiler() -> void

This is a no-op if any of the following conditions are met:

• The profiling session is sampled and the profiler is already running.
• The profiling session is not sampled.
• profileLifecycle is set to 'trace' (profiler lifecycle is bound to trace collection).

SDKs SHOULD log a warning in debug mode if this function is called but results in a no-op.

Naming SHOULD follow the SDK's language conventions:

• Sentry.startProfiler() (JavaScript)
• sentry_sdk.start_profiler() (Python)

SDKs implementing continuous profiling SHOULD expose a function to stop the profiler:

stopProfiler() -> void

Behavior depends on profileLifecycle:

• 'manual': Stops the current profiling session. The profiler can be started again by calling startProfiler().
• 'trace': This is a no-op. The profiler stops automatically when there are no active root spans.

SDKs SHOULD log a warning in debug mode if this function is called while profileLifecycle is 'trace'.

Naming SHOULD follow the SDK's language conventions:

• Sentry.stopProfiler() (JavaScript)
• sentry_sdk.stop_profiler() (Python)