Document ecosystem logging standardization on jido.run

[nshkrdotcom]

Summary

The Jido ecosystem has active work underway to standardize logging, telemetry, redaction, and test-noise posture across decoupled jido_* repos. That work should also be reflected on the jido.run website so the ecosystem presents one coherent observability story.

Reference issue: agentjido/jido#244

Tagging @mikehostetler for direction.

Why this belongs in jido_run

jido_run is the public-facing website, so once the ecosystem starts converging on a logging/telemetry standard, the site likely needs to explain at least some part of it:

• how Jido libraries approach logging by default
• how telemetry, metrics, and tracing fit together
• where the library boundary ends and app/runtime configuration begins
• how downstream repos should think about quiet-by-default behavior, test defaults, and redaction

Without that, the implementation may evolve faster than the public guidance.

Context from agentjido/jido#244

The constraint surfaced there is important:

• not every jido_* repo depends on jido core directly or transitively
• a helper that lives only in core is not automatically an ecosystem-wide answer
• adding a dependency on core purely to share logging helpers would be the wrong coupling in some repos

The broad points already visible from the current docs/research are:

• libraries should stay quiet by default
• high-volume internal activity should primarily be represented as telemetry, not human logs
• expensive log messages should use lazy Logger evaluation
• libraries should not own app/runtime choices such as JSON formatters, log shipping vendors, or error sinks
• test defaults should generally prefer :warning, with explicit capture for lower-level log assertions

Website/documentation approaches to consider

This issue is intentionally not recommending one path yet. These are the main shapes that seem plausible.

1. Add one opinionated ecosystem guide page on the website

Possible shape:

• a dedicated guide on logging, telemetry, metrics, tracing, and test-noise policy
• positioned as the canonical public explainer once the ADR/policy text settles elsewhere

Tradeoffs:

• pros: easy for users to discover, good place to explain concepts and boundaries clearly, supports long-form examples
• cons: risks drifting from the implementation repo ADR if ownership is unclear, may duplicate policy text already living elsewhere

2. Keep the normative policy in a repo ADR and add a shorter website summary page

Possible shape:

• policy/ADR lives in a source repo such as jido
• jido.run carries a concise summary page that links back to the normative source

Tradeoffs:

• pros: reduces duplication, gives one canonical source of truth, keeps the website focused on explanation instead of governance text
• cons: cross-repo ownership can be slightly harder for readers to follow, website users may need to jump between docs layers

3. Distribute the guidance across existing website pages instead of one dedicated page

Possible shape:

• a small section in observability docs
• a small section in configuration docs
• a small section in debugging docs
• repo-specific implementation details left to each package

Tradeoffs:

• pros: integrates guidance into existing reading paths, less intimidating than one large policy page
• cons: easier for the overall standard to become fragmented, harder to see the full logging/telemetry contract in one place

4. Publish only high-level principles on the website and leave mechanics to repo docs

Possible shape:

• the website explains ecosystem principles only
• repo docs cover helper APIs, metadata keys, event taxonomy, redaction behavior, and CI enforcement

Tradeoffs:

• pros: avoids overcommitting the public site to implementation details that may still move, keeps the website durable
• cons: may be too abstract for contributors trying to apply the standard consistently across repos

5. Add a public-facing comparison/matrix page for library vs application responsibilities

Possible shape:

• website page or section that explicitly separates what libraries own vs what applications own
• for example: event names, metadata shape, and redaction defaults in libraries; formatters, sinks, exporters, and routing in applications

Tradeoffs:

• pros: clarifies one of the most important ecosystem governance rules, likely reduces confusion for contributors and adopters
• cons: still needs a deeper companion doc somewhere for details like test defaults, helper APIs, and telemetry taxonomy

Content areas the website may eventually need to cover

Depending on which path is chosen, the public docs may need some combination of:

• quiet-by-default library logging
• lazy logging for expensive messages
• telemetry as the primary internal observability surface
• metrics derived from Telemetry.Metrics
• optional OpenTelemetry integration at the application boundary
• redaction/truncation expectations
• test-time logging defaults
• the boundary between reusable libraries and deployable applications
• eventual cross-repo event taxonomy / metadata namespace if that gets standardized

Open questions

1. Should jido.run host a dedicated logging/observability standard page, or should it only summarize and link to a repo-owned ADR?
2. If there is a website page, should it be normative policy text or an explanatory companion to a source-repo ADR?
3. Should the site document only stable ecosystem principles now, with implementation details added later after the API/taxonomy settle?
4. If the website does cover this, which repo should remain the canonical owner of the underlying policy text?

Related

• Logging and observability standardization across decoupled jido_* repos jido#244