docs: Add develop-docs with Perfetto profiling documentation

[markushi]

Summary

Introduces a develop-docs/ folder for internal developer documentation.

• README.md — defines the documentation conventions: flat directory structure with filename prefixes (general-, feature-, integration-, platform-, process-), lowercase dash-separated names, same-named folders for embedded assets, present-tense/active-voice writing, and Mermaid for diagrams.
• feature-perfetto-profiling.md — first feature doc, covering the Android Perfetto continuous-profiling pipeline end to end: capturing profile chunks via android.os.ProfilingManager, the meta_length envelope framing, Relay's Perfetto → Sample v2 conversion and object-store routing, and the monolith's storage, serving, and download endpoints.

#skip-changelog

🤖 Generated with Claude Code

[sentry]

📲 Install Builds

Android

🔗 App Name	App ID	Version	Configuration
SDK Size	io.sentry.tests.size	8.49.0 (1)	release

⚙️ sentry-android Build Distribution Settings

[runningcode]

Looks good to me! I only reviewed the README.md in detail.

[runningcode]

this one is README.md though?

[runningcode]

im wondering if a flat structure makes sense given that the repo has so many different modules and areas of concern like java/android/sprint/etc?

but i agree that it is best to start flat and then re-organize later if necessary.

[0xadam-brown]

My vote would be to convert the file prefix convention to subdirectories from the get-go. I'd also favor using subdirectories liberally b/c they encourage organization + could lead to less context bloat for LLMs.

Eg, a fully-fleshed out directory tree for profiling might look like this:

/developdocs
  /feature
    /profiling
      profiling-overview.md
      /types
        /transaction
          transaction-profiling.md
        /continuous
          trace-profiling.md
          perfetto-profiling.md
        /anr
          anr-profiling.md
      /pipeline
        profiling-pipeline.md // Describes the backend profiling pipeline.
      /symbolication
        deobfuscating-profiles.md
      ...

If we really plan to make use of develop-docs, hierarchical organization will pay off quickly.

[runningcode]

link to what Relay is? (im not familiar with it)

[runningcode]

👍

[0xadam-brown]

Thanks for this @markushi 💯 !

A few comments for your consideration; no blockers.

[0xadam-brown]

nit if you want it: "Perfetto is Google's preferred tracing framework for Android" (or something like that).

(Took me a few clicks to figure out how to interpret "system" and "stack", as they could mean a few things and my first guesses were wrong.)

[0xadam-brown]

m (non-blocking): My vote would be to create a separate .md file that discusses the pipeline at a high level. We could reference it from here + describe any quirks Perfetto profiling introduces.

That'd let us explain the pipeline clearly on its own terms + share the discussion across .md files for different profiling types (Perfetto, ANR, etc.). I suspect we'll find that giving folks are clear theory of the pipeline ends up being the most helpful artifact going forward, esp as new profiling types will either need to feed into the pipeline's existing format expectations or require updating those expectations.

---

Generalizing...

Taking a step back, I expect we'll see the following pattern a lot in the develop-docs we use to explain systems / features / integrations:

1. Surface area we collect against (ie, where or when do we collect data)
2. How we collect the data
3. Format of the collected data
4. Backend pipeline (input format expectations Relay expects + output format(s) Relay publishes; major components / services on the write path; major components / services on the read path)

Repeating that framework where it makes sense could be a consistency win. Eg, we could include feature overview .md file that summarizes (1); a more specific .md file could describe (2) - (3) on a per-type basis (eg, perfetto-profiling.md, anr-profiling.md); and a pipeline .md file could capture (4).

Anything not relevant to a particular feature could be omitted, and discussions could be kept as high-level as possible to keep them fresh longer. (Eg, no need to repeat data formats in detail; but mentioning the fact that, say, Perfetto generates protobuf traces is helpful, as is the fact that Relay publishes two formats for continuous profile chunks which all downstream services need to care about, etc.)

[0xadam-brown]

My vote would be to convert the file prefix convention to subdirectories from the get-go. I'd also favor using subdirectories liberally b/c they encourage organization + could lead to less context bloat for LLMs.

Eg, a fully-fleshed out directory tree for profiling might look like this:

/developdocs
  /feature
    /profiling
      profiling-overview.md
      /types
        /transaction
          transaction-profiling.md
        /continuous
          trace-profiling.md
          perfetto-profiling.md
        /anr
          anr-profiling.md
      /pipeline
        profiling-pipeline.md // Describes the backend profiling pipeline.
      /symbolication
        deobfuscating-profiles.md
      ...

If we really plan to make use of develop-docs, hierarchical organization will pay off quickly.

[0xadam-brown]

Suggested change

	- Use a **flat directory structure** for all markdown files, they live live directly in `develop-docs/`.
	- Use a **flat directory structure** for all markdown files, they live directly in `develop-docs/`.