docs(sdk): Define flamegraph attachments

[philprime]

DESCRIBE YOUR PR

Define the draft event.flamegraph attachment contract in Attachments specification 1.8.0. SDKs send flamegraph.json alongside an event, containing aggregated caller-to-callee trees, a shared frame table, and debug metadata for symbolication. This is a documentation proposal, not an implementation of ingestion or processing support.

Schema Decisions

• Use the View Hierarchy attachment pattern rather than introducing another envelope item type.
• Reuse V2 profile chunk frame objects and debug_meta. Binary identity and address metadata are necessary for later symbolication, including diagnostics captured in a different process run from the uploading SDK. Keep event context on the event rather than defining a second device/OS metadata schema.
• Deduplicate frames and reference them by zero-based indices. Indices must remain within the frame table. Counts stay on node occurrences because one frame can appear in several call paths or recursively.
• Use caller-to-callee paths and allow multiple roots to preserve distinct oldest captured callers. Each tree retains a separate sample population. Thread IDs are optional, and thread_attributed records source attribution when known.

Limits and Processing Decisions

• 10 MiB serialized JSON limit. An assumed starting budget scaled from the 1 MB error-event limit to accommodate roughly ten event-sized contributions. This is a sizing heuristic based on error event, not a measured requirement or an inherited attachment/profiling limit.
• 2,500 input frame-table entries for symbolication. An assumed starting budget scaled from the 250-frame per-thread error-event limit (50 head frames and 200 tail frames), allowing the equivalent of ten maximum-sized thread stacks. This is a sizing heuristic, not an existing profiling limit or a limit on the number of nodes. Deduplicated entries consume the budget once, in frame-index order, before inline expansion. Remaining frames retain their unsymbolicated data rather than being truncated.
• Inline expansion replace each physical-frame occurrence with a logical caller-to-callee chain. Every expanded node inherits the occurrence's count, and its original children attach to the innermost node. Preserve call-path relationships and counts while allowing index remapping.
• Repeatable processing follows profiling's server-side processing-state guard rather than introducing an SDK payload field. Profiling's _should_symbolicate and _symbolicate_profile skip symbolication after processed_by_symbolicator is set. Its sample-result processing replaces frame entries and remaps stacks for inline frames. The flamegraph contract adopts the same once-per-processed-payload principle. A deliberate rerun must start from unexpanded input.

Review focus is agreement on:

• the schema
• the 10 MiB limit
• the 2,500-frame budget and selection order
• the symbolication-state handling.

IS YOUR CHANGE URGENT?

• Urgent deadline (GA date, etc.): YYYY-MM-DD
• Other deadline: YYYY-MM-DD
• No deadline: Not urgent, can wait up to 1 week+

PRE-MERGE CHECKLIST

• Checked Vercel preview for correctness, including links
• PR was reviewed and approved by any necessary SMEs (subject matter experts)
• PR was reviewed and approved by a member of the Sentry docs team

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
develop-docs	Ready	Preview	Oct 2, 2026 1:00pm UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
sentry-docs	Ignored		Oct 2, 2026 1:00pm UTC

[cursor]

The plan checks attachments page loads, SDK section loads, 404s, and client errors. An issue escalates when that page 404s or client errors rise.

Services: develop-docs.

Mention @change-monitor in a comment to update the plan.

Plan

What changed

The Attachments spec page now documents a draft flamegraph attachment contract. Requests to /sdk/telemetry/attachments/ now show event.flamegraph transport, payload, and limits. The change is live after a develop-docs production deploy.

Risk

A compile or render failure can 404 this spec page. A new code block or spec badge can throw a client TypeError. Sibling /sdk/telemetry/ pages share the same MDX renderer. This change does not ingest flamegraphs.

Intended effect

This is a documentation spec. Telemetry cannot prove the new flamegraph text is on the page. A successful load of /sdk/telemetry/attachments/ after deploy is the reachable proxy. Absent looks like zero loads on that path plus a 404, while other SDK pages still load. Traffic is one load per day, so zero loads with no 404 may stay unknown.

Signal	Baseline	Rule	Source
docs.page.load on /sdk/telemetry/attachments/	1 load in 24h	After deploy, one or more loads in a matching window confirms the page still serves. Absent is 0 loads plus a sdk/telemetry 404 while other SDK pages still load.	Sentry metrics, org sentry, project develop-docs. Query: metric.name:docs.page.load AND metric.type:counter AND environment:production AND path:"/sdk/telemetry/attachments/". Window 2026-10-04T09:23:27.930Z to 2026-10-05T09:23:27.930Z
docs.page.load with page_type:sdk	151 loads in 24h	Hold near 151. This shows the SDK section still renders. It does not prove the new flamegraph text.	Same project. Query: metric.name:docs.page.load AND metric.type:counter AND environment:production AND page_type:sdk. Same window

Regression watch

A bad MDX render can 404 this page or throw in the shared spec renderer. Watch client errors first. Then watch 404s on the SDK telemetry family.

Signal	Baseline	Rule	Source
Production error events	33 events, 2.6% of 1277 page loads (TypeError 27 events, 2.1%)	Hold near 2.6%. Escalate if the 24h rate rises above 4% while loads stay near 1277.	Sentry errors, org sentry, project develop-docs. Query: environment:production with count(). TypeError query: error.type:TypeError environment:production. Window 2026-10-04T09:23:27.930Z to 2026-10-05T09:23:27.930Z
docs.page.not_found	4 counts in 24h, 0.3% of 1277 loads. Paths: sdk/foundations 2, self-hosted/backup 1, application-architecture/overview. 1. Attachments path 0	Hold near 4. Escalate if any sdk/telemetry 404 appears, or 24h 404s rise above 8.	Sentry metrics. Query: metric.name:docs.page.not_found AND metric.type:counter AND environment:production grouped by requested_path. Same window
MDX missing-file warnings	0 matching logs in 24h	Stay at 0. Escalate if any warn or error log matches MDX file not found.	Sentry logs. Query: (severity:warn OR severity:error) AND (message:"*MDX file not found*" OR message:"*serverless_bundle_exclusion*") AND environment:production. Same window
docs.page.load on /sdk/telemetry/*	18 loads across 9 paths in 24h. Index 5, errors 3, metrics 2, traces 2, check-ins 2, profiles 1, attachments 1	Hold near 18. Do not treat a single missed attachments load as a regression. Escalate if the whole family falls toward 0 while site loads stay near 1277.	Sentry metrics. Query: metric.name:docs.page.load AND metric.type:counter AND environment:production AND path:*/sdk/telemetry*. Same window

If the error rate rises, check client stacks from code tabs and spec badges on /sdk/telemetry/attachments/.

Not observable

The flamegraph section body, the 1.8.0 spec badge, and the example JSON on the rendered page. Pageload and navigation span duration: production queries for transaction.op:pageload and transaction.op:navigation returned 0 rows. Whether ingest or SDKs honor event.flamegraph. This pull request is documentation only.

[jjbayer]

I assume the flamegraph does not contain sensitive data, i.e. requires no PII scrubbing?

[philprime]

We currently don’t scrub profiling profile chunks, and standard error-event scrubbing excludes source paths and debug metadata.

Therefore I don’t think flamegraphs require a dedicated default scrubber either.