Create documentation for mapping ecosystems

[jaydeluca]

We have a handful of issues related to starting the process of introducing new ecosystems:

• Research Python Instrumentation #135
• Research .NET Instrumentation #101
• Research Golang Instrumentation #100
• Research Javascript instrumentation metadata #9
• Prometheus Ecosystem Support #203
• Research GenAI Ecosystem #154

Each of these are being tackled by different people, but we should create a shared knowledge base / guide on how we go about this process so that we have some consistency, and a paved path for future ecosystems as well.

I will post more information here shortly, but if anyone wants to bootstrap a guide under /docs and as other people are working on this problem, please feel free to comment thoughts / brainstorms / questions.

[jaydeluca]

CC @lucacavenaghi97 @Pittu-Sharma @LoveChauhan-18 @mikeblum @MeloveGupta as you have all shown interest in one of the ecosystem expansion issues.

[LoveChauhan-18]

Hi @jaydeluca,

I've been looking into bootstrapping this guide. Based on the current architecture and the parallel research efforts (GenAI, Python, etc.), I've outlined a 4-phase lifecycle for mapping new ecosystems to ensure we maintain consistency and technical rigor.

Here is the proposed structure for the Ecosystem Mapping Guide:

Phase 1: Research & Initiative (The "Soft" Side)

• Mandatory use of the projects/ workspace for auditing upstream sources and documenting findings.
• Defining the initial metadata schema before writing any automation code.

Phase 2: Automation (The "Hard" Side)

• Standardizing on watcher-common base classes in Python.
• Enforcing the "Watcher Contract": Idempotency (preventing redundant registry writes), deterministic output (for CAS), and release detection.

Phase 3: Registry Integration

• Strict adherence to the // layout.
• Handling SNAPSHOT versions for nightly builds vs. stable release tags.

Phase 4: Database & Frontend Visualization

• Extending explorer-db-builder to ingest the new registry paths.
• Closing the loop with JSON Schema validation and shared TypeScript types for the frontend.

Key Technical Focus: I want to emphasize the importance of Content-Addressed Storage (CAS) and stable ordering in the guide. If watchers produce non-deterministic output (like timestamps or unsorted arrays), it busts our hash-based cache in the frontend.

Does this 4-phase structure align with the "paved path" you had in mind? If so, I'll start drafting the detailed markdown under /docs.

[Pittu-Sharma]

Thanks for outlining such a solid 4-phase structure, @LoveChauhan-18! This aligns perfectly with what I've been experiencing while researching the .NET ecosystem mapping (#101).

Since we have a great outline here, I'd be happy to take the lead on drafting the actual Markdown guide under /docs based on these phases. I can open a Draft PR shortly so we have a concrete file to review, iterate on, and collaborate together.

@jaydeluca Does it sound good if I go ahead and bootstrap the initial docs/ecosystem-mapping-guide.md PR using this structure as a starting point?

[LoveChauhan-18]

Thanks for outlining such a solid 4-phase structure, @LoveChauhan-18! This aligns perfectly with what I've been experiencing while researching the .NET ecosystem mapping (#101).

Since we have a great outline here, I'd be happy to take the lead on drafting the actual Markdown guide under /docs based on these phases. I can open a Draft PR shortly so we have a concrete file to review, iterate on, and collaborate together.

@jaydeluca Does it sound good if I go ahead and bootstrap the initial docs/ecosystem-mapping-guide.md PR using this structure as a starting point?

Sound good @Pittu-Sharma, since you have been researching and working on .NET issue, you would be able to understand my 4-phase structure and work on this positively.
Happy to work with you!👌

[MeloveGupta]

Hey @jaydeluca I spent some time going through the codebase to understand how the existing watchers actually work.

On the docs/ directory

There are already several reference docs under docs/ - architecture overview, registry structure, CAS, frontend architecture, watcher/registry consumers. The onboarding guide can link from these rather than repeat them.

On watcher-common (adding to what @LoveChauhan-18 said)

watcher-common provides helpers, not an enforced abstract framework. BaseInventoryManager and BaseRepositoryManager have no @abstractmethod decorators. There's a version_exists() helper that prevents duplicate writes, but watchers must call it themselves, it's not automatic. The Collector watcher doesn't even use BaseInventoryManager, it has its own distribution-aware inventory manager. So the guide should be clear about what's actually inherited vs what each watcher implements from scratch.

On registry layout

The {ecosystem}/{distribution}/v{version}/ pattern isn't universal. ecosystem-registry/configuration/v1.0.0/ has no distribution layer at all. "Distribution" also means different things for Java it's javaagent, for Collector it's core/contrib. The guide should require each new ecosystem to define what its distribution concept maps to before any code is written,
since JS (independent per-package versions) and Python (modular packages) don't map cleanly to the current layout.

On CAS and stable ordering

The hash utility normalizes dict keys recursively but preserves list order, so list ordering is still the watcher's responsibility. ecosystem-automation/AGENTS.md already requires stable arrays explicitly. The guide should call this out with concrete examples of what breaks it like unsorted component scans, unsorted attribute lists, etc.

On CI - one thing that I think worth adding

A new watcher needs five things wired up beyond just the watcher code:

1. Tests in build-and-test.yml
2. Nightly invocation in nightly-registry-update.yml
3. Notification wiring - the nightly workflow opens/closes GitHub issues on watcher failure, new watchers need this too
4. DB builder pipeline for the new registry path
5. build-explorer-database.yml workflow input updated to include the new ecosystem

Without all five, failures are invisible and the frontend never gets the data.

On AGENTS.md

The guide should explicitly reference AGENTS.md and ecosystem-automation/AGENTS.md. Key rules any new watcher must follow:

• Registry files are generated, never edit manually
• No timestamps or non-deterministic output
• No real external API calls in tests
• GitHub Actions pinned to full SHAs
• Schema changes require historical re-extraction

Also While going through the JS research specifically, a few questions came up that I think the guide needs to address per ecosystem.

• JS packages version independently - there's no single "js agent version" to key the registry off. How do we handle that layout?
• The word "distribution" means javaagent for Java and core/contrib for Collector, what does it mean for Python or GenAI?
• For Java the source of truth is one YAML file. For JS it's scattered across package.json, README files, etc. Does the guide say anything about what happens when these disagree?
• Some metadata simply doesn't exist upstream yet - for JS there's no structured telemetry data at all. Should the guide define a minimum viable schema before a watcher is considered "done"?