From c693d3d2bc5c16f9e805ccda3bf875e9764029a2 Mon Sep 17 00:00:00 2001 From: Kasper Borg Nissen Date: Wed, 13 May 2026 12:46:44 +0200 Subject: [PATCH 1/7] first draft of project proposal for the OTel support maturity model Signed-off-by: Kasper Borg Nissen --- projects/otel-support-maturity-model.md | 179 ++++++++++++++++++++++++ 1 file changed, 179 insertions(+) create mode 100644 projects/otel-support-maturity-model.md diff --git a/projects/otel-support-maturity-model.md b/projects/otel-support-maturity-model.md new file mode 100644 index 000000000..499fc652b --- /dev/null +++ b/projects/otel-support-maturity-model.md @@ -0,0 +1,179 @@ +# OpenTelemetry Support Maturity Model + +## Background and description + +OpenTelemetry has become the de facto standard for producing telemetry in cloud native systems, and a growing number of cloud native projects emit their telemetry through it. This proposal is about the maturity of *that* support: how well projects across the ecosystem integrate with OpenTelemetry. It is not about the maturity of OpenTelemetry itself. The aim is to give the ecosystem a shared way to talk about what "supports OpenTelemetry" really means in any given project, and to make the bar for that support easier to see and harder to fudge. + +Users expect projects to plug into OpenTelemetry pipelines cleanly, follow semantic conventions, correlate signals, and behave predictably across environments. But support is rarely all-or-nothing. Projects mature unevenly: integration surfaces, semantics, configuration, trace modeling, and multi-signal workflows tend to evolve on different timelines, and today there is no structured way to describe how that mixed picture looks. + +Nearly half of respondents in the latest CNCF survey report using OpenTelemetry in production. At that scale, the distance between "supports OpenTelemetry" as a binary label and what it actually delivers in a given project has turned into real friction, especially for platform teams that need to integrate across many projects at once. In practice, that means hitting projects where traces flow via OTLP but metrics are still Prometheus-only, where semantic conventions are several versions out of date, or where the standard `OTEL_*` configuration is quietly ignored in favor of project-specific flags. Each integration becomes its own learning curve, and what works for one project rarely carries cleanly to the next. + +The idea was discussed openly in [community issue #3247](https://github.com/open-telemetry/community/issues/3247), where maintainers, end-user representatives, and other contributors signalled interest in turning it into a formal project. The OpenTelemetry Governance Committee then asked that it go through the formal proposal process. The timing is reinforced by OpenTelemetry reaching CNCF Graduated status: now that it has graduated, "supports OpenTelemetry" becomes a claim that users and downstream projects increasingly take at face value. A descriptive maturity model is one way to keep that claim honest. + +### Current challenges + +- Support is described as present or absent, with no way to say how deep, consistent, or intentional it actually is. Users cannot evaluate what "supports OpenTelemetry" means for a given project. +- Different projects implement OpenTelemetry support at very different depths. Some push traces via OTLP while metrics stay Prometheus-only. Some use outdated semantic conventions. Some ignore standard `OTEL_*` environment variables. Adopters discover these inconsistencies after the fact. +- Maintainers who want to improve their OpenTelemetry support lack a structured way to identify gaps or prioritize work. "Better telemetry" stays an ad-hoc conversation, project by project. +- Platform teams building stacks across multiple CNCF projects cannot easily compare integration effort. Every project gets evaluated from scratch. +- Existing community efforts, such as the [Instrumentation Score](https://github.com/instrumentation-score/) specification for rule-based signal-quality checks and the [OpenTelemetry Ecosystem Explorer](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer) for component discovery and cataloging, address adjacent concerns but operate independently. Nothing connects design intent, evolution patterns, and signal quality into a coherent picture. + +### Goals, objectives, and requirements + +The goal of this project is to develop and publish a descriptive maturity model for OpenTelemetry support in cloud native projects (and potentially beyond), giving the community a shared framework for evaluating and discussing how that support evolves. + +Objectives: + +1. Define a multi-dimensional maturity model that captures how OpenTelemetry support typically evolves across the dimensions listed below. +2. Validate the model against real projects by applying it to cloud native projects in different categories (ingress controllers, service meshes, application runtimes, and so on), and check whether the dimensions and levels hold up in practice. +3. Publish the model as an OpenTelemetry community resource (for example on opentelemetry.io), with explicit positioning as a descriptive tool, not a certification, compliance, or ranking program. +4. Develop evaluation guidance, including question-based checklists, so reviewers can apply the model consistently across projects. +5. Position the model as complementary to other ecosystem efforts (Instrumentation Score, Ecosystem Explorer), and describe how those tools relate to each other. + +Dimensions in scope: + +The draft model evaluates OpenTelemetry support across seven dimensions. The wording, granularity, and number of dimensions are open for community refinement during the project. The current draft covers: + +1. **Integration Surface**: how users connect a project to their observability pipelines, and how strongly telemetry is coupled to specific tools or vendors. +2. **Semantic Conventions**: how consistently telemetry meaning aligns with OpenTelemetry semantic conventions, and how domain-specific extensions are introduced and stewarded. +3. **Resource Attributes & Configuration**: how identity, scope, and configuration are handled across environments, including correct use of resource attributes and standard `OTEL_*` configuration. +4. **Trace Modeling & Context Propagation**: how traces are structured and how context flows through synchronous and asynchronous execution paths. +5. **Multi-Signal Observability**: how traces, metrics, and logs are supported together and correlated. +6. **Audience & Signal Quality**: who telemetry is designed for, how noisy it is by default, and how well it communicates meaningful system behavior. +7. **Stability & Change Management**: how telemetry evolves over time and how changes are communicated and managed once users depend on it. + +Each dimension is described across four global maturity levels: Level 0 (Instrumented), Level 1 (OpenTelemetry-Aligned), Level 2 (OpenTelemetry-Native), and Level 3 (OpenTelemetry-Optimized). There is no overall maturity score by design; each dimension stands on its own. + +What this project explicitly is not: + +- A specification, standard, or policy proposal. +- A certification or conformance program. +- A ranking or comparison mechanism for CNCF projects. +- A requirement for cloud native or OpenTelemetry projects. + +Why now: + +- Adoption has reached a point where the quality and consistency of OpenTelemetry support matters as much as its presence. +- OpenTelemetry just reached CNCF Graduated status, which raises what users and downstream projects assume "supports OpenTelemetry" means. A shared vocabulary is easier to establish now than to retrofit later. +- The draft framework has already been applied to real projects (Kubernetes ingress controllers including Traefik, Istio Gateway, Contour, Emissary, and kgateway). That exercise sharpened the boundary between project maturity and Collector pipeline capability, tightened the Level 3 definition for Semantic Conventions, clarified what is expected at the source versus what can be derived in the pipeline for Resource Attributes, and produced a question-based evaluation appendix. +- Conversations with project maintainers (Dapr, kgateway, and others) show that going through the model can lead to real changes, including upstream dependency work that kicked off as a direct result of an evaluation. +- The OpenTelemetry Governance Committee has indicated that this work should go through the formal project process for broader community input. +- The work fits the wider goal of strengthening OpenTelemetry's role as an integration layer across CNCF, and picks up a thread from the cross-project collaboration track at Maintainer Summit NA. + +## Deliverables + +1. **Maturity model document**: a published, community-reviewed maturity model describing OpenTelemetry support across the defined dimensions and global maturity levels. This includes: + - Global maturity level definitions (Level 0: Instrumented, Level 1: OpenTelemetry-Aligned, Level 2: OpenTelemetry-Native, Level 3: OpenTelemetry-Optimized). + - Per-dimension descriptions with characteristics and example scenarios at each level. + - Guidance on how to use the model (for maintainers, contributors, users, and platform teams). + - Explicit positioning relative to other community efforts (Instrumentation Score, Ecosystem Explorer). + - A clear statement on the boundary between project-emitted telemetry and downstream Collector pipeline capabilities. +2. **Evaluation checklist / reference guide**: a question-based evaluation checklist for each dimension and maturity level, designed for consistent, repeatable assessments. The current draft already includes an appendix that will be refined and validated through further use. +3. **Category assessment**: application of the model to at least one category of cloud native projects (for example ingress controllers, service meshes, or application runtimes) to capture the current state of OpenTelemetry support across that space. This both validates the model and demonstrates its value. +4. **Publication on opentelemetry.io**: the maturity model and supporting materials published as community documentation on the OpenTelemetry website, with clear positioning as a descriptive framework maintained by the community. +5. **Companion blog post(s)**: blog post(s) announcing the project and explaining the model's purpose to the broader community. + +Note: this project does not propose changes to the OpenTelemetry Specification or Semantic Conventions. No OTEPs are required. The deliverables are documentation and guidance artifacts. + +## Staffing / Help Wanted + +### Industry outreach (Optional) + +The following people and groups should be aware of this effort. Some have already been engaged; the rest are targets for outreach: + +- **Cloud native project maintainers**: initial conversations have taken place with maintainers of Traefik, Linkerd, Dapr, and kgateway. Further outreach is needed for maintainers in other categories (databases, service meshes, CI/CD tools, and so on). +- **CNCF TAG Operational Resilience**: as the TAG responsible for observability guidance across CNCF, their input matters. +- **CNCF TCG Platform Engineering**: the maturity model is structurally inspired by the [CNCF Platform Engineering Maturity Model](https://tag-app-delivery.cncf.io/whitepapers/platform-eng-maturity-model/), which was developed by WG Platform Engineering under TAG App Delivery. +- **CNCF TAG Developer Experience**: can provide input and help validate the current status of projects. +- **OpenTelemetry End User SIG**: end users have the strongest perspective on what "OpenTelemetry support" should mean in practice. +- **Observability vendors and platform teams**: companies building on OpenTelemetry that work across many CNCF projects can offer practical feedback. + +### SIG + +This project is cross-cutting. It touches documentation, semantic conventions, ecosystem tooling, and end-user concerns. Two viable paths: + +- Lead under an existing SIG (for example SIG Communications or SIG End User), with explicit coordination touchpoints to SIG Docs and SIG Semantic Conventions. +- Form a dedicated working group with representation from multiple SIGs. + +Recommendation: discuss with TC and GC during proposal review. A working group under SIG Communications, mirroring how the Ecosystem Explorer project is organized, seems like a sensible fit given the documentation- and ecosystem-facing nature of the deliverables. + +### Required staffing + +#### Project Lead(s) + +- **Kasper Borg Nissen** ([@kaspernissen](https://github.com/kaspernissen)), Dash0: author of the draft maturity model. Has been developing and validating the framework through blog posts, talks, and direct engagement with cloud native projects. +- _Seeking one additional co-lead_: ideally from a different company and with complementary expertise (for example semantic conventions, OpenTelemetry SDK development, or an end-user/platform team perspective). + +#### Interested contributors + +The following people publicly expressed interest in contributing during the discussion on [issue #3247](https://github.com/open-telemetry/community/issues/3247). Specific roles and commitments will be confirmed as part of the proposal review: + +- **Michael Hausenblas** ([@mhausenblas](https://github.com/mhausenblas)): end-user perspective; committed to participating as an OpenTelemetry end user. +- **Mauricio Salatino** ([@salaboy](https://github.com/salaboy)): cross-project experience (Dapr, Knative); willing to help develop checklists and evaluations. +- **Mehmet Baykara** ([@mbaykara](https://github.com/mbaykara)): working on an adjacent observability maturity model effort; willing to compare notes, review dimension wording, and contribute enterprise/customer adoption examples. +- **Severin Neumann** ([@svrnm](https://github.com/svrnm)): SIG Communications / Docs perspective; expressed support for hosting on opentelemetry.io and helped frame the ownership question. +- **Henrik Rexed** ([@henrikrexed](https://github.com/henrikrexed)): provided detailed feedback on the developer-facing actionability of the model and on the per-signal scoring trade-off; willing to do a thorough pass on the document. + +_Additional contributors actively sought:_ + +- **Assessment authors**: contributors willing to apply the model to CNCF projects they maintain or use, so the set of reference assessments grows beyond ingress controllers. +- **Documentation contributors**: contributors to help shape the model for publication on opentelemetry.io. +- **Semantic conventions reviewers**: reviewers from SIG Semantic Conventions to align the semantic conventions dimension with the project's direction, including Weaver-based workflows. + +### Sponsorship + +#### TC Sponsor + +_To be confirmed._ Seeking a TC sponsor with interest in ecosystem integration, instrumentation quality, or cross-project OpenTelemetry support. + +#### GC Liaison + +_To be confirmed._ Seeking a GC liaison to keep the project healthy and the scope true to the proposal. + +## Expected Timeline + +The project is structured in three phases. + +### Phase 1: Community review and model refinement (Month 1–2) + +- Submit the project proposal for GC/TC review. +- Solicit community feedback on the draft maturity model through the proposal PR and community meetings. +- Refine dimensions, maturity levels, and evaluation checklists based on feedback. +- Recruit additional contributors, confirm staffing, and agree on SIG ownership. + +### Phase 2: Validation and documentation (Month 3–4) + +- Apply the refined model to at least one category of CNCF projects. +- Develop the model into publishable documentation for opentelemetry.io. +- Coordinate with SIG Docs on publication format and placement. +- Coordinate with related efforts (Instrumentation Score, Ecosystem Explorer) on complementary positioning. + +### Phase 3: Publication and handoff (Month 5–6) + +- Publish the maturity model and category assessment on opentelemetry.io. +- Establish ongoing maintenance ownership (SIG or working group). +- Decide whether the project transitions to ongoing SIG work or wraps up. + +## Labels (Optional) + +- `area/maturity-model` +- `area/ecosystem` + +## GitHub Project (Post-Approval) + +_To be set up after approval._ + +## SIG Meetings, Roadmap, and Other Info (Post-Approval) + +_To be set up after approval._ + +## Related work and references + +- [Community issue #3247: Draft proposal — OpenTelemetry Support Maturity Model for CNCF projects](https://github.com/open-telemetry/community/issues/3247) +- [Draft maturity model document](https://docs.google.com/document/d/1KvRtYqdSR1ii-SLV2wEv0MH-j9Mh5xA5u7f51kO6xpw/edit?usp=sharing) +- [CNCF Platform Engineering Maturity Model](https://tag-app-delivery.cncf.io/whitepapers/platform-eng-maturity-model/) (structural inspiration) +- [Instrumentation Score](https://github.com/instrumentation-score/) (complementary: rule-based signal quality checks) +- [OpenTelemetry Ecosystem Explorer](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer) (complementary: component discovery and cataloging) +- [OpenTelemetry Ecosystem Integrations](https://opentelemetry.io/ecosystem/integrations/) (23+ CNCF projects listed) +- [OpenTelemetry Weaver](https://github.com/open-telemetry/weaver) (tooling referenced for semantic extensions at Level 3) +- [Prometheus Conformance Program](https://github.com/cncf/prometheus-conformance) (reference for a possible future, separate conformance effort) From 75501fbe710906b0fa00df6d03e054791c77f941 Mon Sep 17 00:00:00 2001 From: Kasper Borg Nissen Date: Wed, 13 May 2026 12:51:54 +0200 Subject: [PATCH 2/7] tighten the proposal a bit Signed-off-by: Kasper Borg Nissen --- projects/otel-support-maturity-model.md | 9 --------- 1 file changed, 9 deletions(-) diff --git a/projects/otel-support-maturity-model.md b/projects/otel-support-maturity-model.md index 499fc652b..2a4b2b794 100644 --- a/projects/otel-support-maturity-model.md +++ b/projects/otel-support-maturity-model.md @@ -51,15 +51,6 @@ What this project explicitly is not: - A ranking or comparison mechanism for CNCF projects. - A requirement for cloud native or OpenTelemetry projects. -Why now: - -- Adoption has reached a point where the quality and consistency of OpenTelemetry support matters as much as its presence. -- OpenTelemetry just reached CNCF Graduated status, which raises what users and downstream projects assume "supports OpenTelemetry" means. A shared vocabulary is easier to establish now than to retrofit later. -- The draft framework has already been applied to real projects (Kubernetes ingress controllers including Traefik, Istio Gateway, Contour, Emissary, and kgateway). That exercise sharpened the boundary between project maturity and Collector pipeline capability, tightened the Level 3 definition for Semantic Conventions, clarified what is expected at the source versus what can be derived in the pipeline for Resource Attributes, and produced a question-based evaluation appendix. -- Conversations with project maintainers (Dapr, kgateway, and others) show that going through the model can lead to real changes, including upstream dependency work that kicked off as a direct result of an evaluation. -- The OpenTelemetry Governance Committee has indicated that this work should go through the formal project process for broader community input. -- The work fits the wider goal of strengthening OpenTelemetry's role as an integration layer across CNCF, and picks up a thread from the cross-project collaboration track at Maintainer Summit NA. - ## Deliverables 1. **Maturity model document**: a published, community-reviewed maturity model describing OpenTelemetry support across the defined dimensions and global maturity levels. This includes: From 21fa996b85aa83651b7aaf4e5f04fe27a5dcc9ae Mon Sep 17 00:00:00 2001 From: Kasper Borg Nissen Date: Wed, 13 May 2026 13:15:25 +0200 Subject: [PATCH 3/7] update .cspell.yaml Signed-off-by: Kasper Borg Nissen --- .cspell.yaml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/.cspell.yaml b/.cspell.yaml index 4bc03856a..87d7633f9 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -297,3 +297,13 @@ words: - Vitor - vtex - yahn + - Baykara + - Dapr + - Hausenblas + - Kasper + - kgateway + - Mehmet + - Nissen + - Rexed + - Salatino + - touchpoints From de357affda0ad6d2ef93f76bb87e926f1ed774ee Mon Sep 17 00:00:00 2001 From: Kasper Borg Nissen Date: Fri, 15 May 2026 06:56:51 +0200 Subject: [PATCH 4/7] add Michael Hausenblas as Co-lead Signed-off-by: Kasper Borg Nissen --- projects/otel-support-maturity-model.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/projects/otel-support-maturity-model.md b/projects/otel-support-maturity-model.md index 2a4b2b794..2ffdf19d9 100644 --- a/projects/otel-support-maturity-model.md +++ b/projects/otel-support-maturity-model.md @@ -93,13 +93,12 @@ Recommendation: discuss with TC and GC during proposal review. A working group u #### Project Lead(s) - **Kasper Borg Nissen** ([@kaspernissen](https://github.com/kaspernissen)), Dash0: author of the draft maturity model. Has been developing and validating the framework through blog posts, talks, and direct engagement with cloud native projects. -- _Seeking one additional co-lead_: ideally from a different company and with complementary expertise (for example semantic conventions, OpenTelemetry SDK development, or an end-user/platform team perspective). +- **Michael Hausenblas** ([@mhausenblas](https://github.com/mhausenblas)): brings the end-user perspective through his role at an end-user organization, and has committed to co-leading the project. #### Interested contributors -The following people publicly expressed interest in contributing during the discussion on [issue #3247](https://github.com/open-telemetry/community/issues/3247). Specific roles and commitments will be confirmed as part of the proposal review: +The following people publicly expressed interest in contributing during the discussion on [issue #3247](https://github.com/open-telemetry/community/issues/3247) and on this PR. Specific roles and commitments will be confirmed as part of the proposal review: -- **Michael Hausenblas** ([@mhausenblas](https://github.com/mhausenblas)): end-user perspective; committed to participating as an OpenTelemetry end user. - **Mauricio Salatino** ([@salaboy](https://github.com/salaboy)): cross-project experience (Dapr, Knative); willing to help develop checklists and evaluations. - **Mehmet Baykara** ([@mbaykara](https://github.com/mbaykara)): working on an adjacent observability maturity model effort; willing to compare notes, review dimension wording, and contribute enterprise/customer adoption examples. - **Severin Neumann** ([@svrnm](https://github.com/svrnm)): SIG Communications / Docs perspective; expressed support for hosting on opentelemetry.io and helped frame the ownership question. From 9d6cb87a26e1c9708911d6417c26a17007a97654 Mon Sep 17 00:00:00 2001 From: Kasper Borg Nissen Date: Fri, 14 Aug 2026 10:30:52 +0200 Subject: [PATCH 5/7] docs: reframe OTel support proposal around self-assessment and guides --- .cspell.yaml | 22 +-- projects/otel-support-maturity-model.md | 169 ---------------------- projects/otel-support-self-assessment.md | 171 +++++++++++++++++++++++ 3 files changed, 183 insertions(+), 179 deletions(-) delete mode 100644 projects/otel-support-maturity-model.md create mode 100644 projects/otel-support-self-assessment.md diff --git a/.cspell.yaml b/.cspell.yaml index 87d7633f9..8b1707784 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -18,6 +18,7 @@ ignoreRegExpList: - GitHub Handle in YML words: - Abinet + - Akamas - Alain - Alff - Arize @@ -25,13 +26,16 @@ words: - Ashpole - automations - Baeyens + - Baykara - calendar-localization-ptbr + - Casto - Causely - Cheler - Ciukaj - Collibra - Coralogix - Cortez + - Dapr - DASD - Debele - Díaz @@ -50,6 +54,8 @@ words: - faas - gitter - grafana + - Graziano + - Hausenblas - Hostmetrics - hostmetricsreceiver - Instrgen @@ -57,7 +63,9 @@ words: - Joaquín - Kanal - Karlie + - Kasper - keptn + - kgateway - Kuba - kubecon - k8sclusterreceiver @@ -71,6 +79,8 @@ words: - maintainership - Makefiles - Marylia + - Mehmet + - Nissen - observiq - opentelemetry - opentelemetrybot @@ -89,7 +99,9 @@ words: - Liudmila - Mathieu - Nale + - Rexed - REXX + - Salatino - scaphandre - Sysplex - acramsay @@ -297,13 +309,3 @@ words: - Vitor - vtex - yahn - - Baykara - - Dapr - - Hausenblas - - Kasper - - kgateway - - Mehmet - - Nissen - - Rexed - - Salatino - - touchpoints diff --git a/projects/otel-support-maturity-model.md b/projects/otel-support-maturity-model.md deleted file mode 100644 index 2ffdf19d9..000000000 --- a/projects/otel-support-maturity-model.md +++ /dev/null @@ -1,169 +0,0 @@ -# OpenTelemetry Support Maturity Model - -## Background and description - -OpenTelemetry has become the de facto standard for producing telemetry in cloud native systems, and a growing number of cloud native projects emit their telemetry through it. This proposal is about the maturity of *that* support: how well projects across the ecosystem integrate with OpenTelemetry. It is not about the maturity of OpenTelemetry itself. The aim is to give the ecosystem a shared way to talk about what "supports OpenTelemetry" really means in any given project, and to make the bar for that support easier to see and harder to fudge. - -Users expect projects to plug into OpenTelemetry pipelines cleanly, follow semantic conventions, correlate signals, and behave predictably across environments. But support is rarely all-or-nothing. Projects mature unevenly: integration surfaces, semantics, configuration, trace modeling, and multi-signal workflows tend to evolve on different timelines, and today there is no structured way to describe how that mixed picture looks. - -Nearly half of respondents in the latest CNCF survey report using OpenTelemetry in production. At that scale, the distance between "supports OpenTelemetry" as a binary label and what it actually delivers in a given project has turned into real friction, especially for platform teams that need to integrate across many projects at once. In practice, that means hitting projects where traces flow via OTLP but metrics are still Prometheus-only, where semantic conventions are several versions out of date, or where the standard `OTEL_*` configuration is quietly ignored in favor of project-specific flags. Each integration becomes its own learning curve, and what works for one project rarely carries cleanly to the next. - -The idea was discussed openly in [community issue #3247](https://github.com/open-telemetry/community/issues/3247), where maintainers, end-user representatives, and other contributors signalled interest in turning it into a formal project. The OpenTelemetry Governance Committee then asked that it go through the formal proposal process. The timing is reinforced by OpenTelemetry reaching CNCF Graduated status: now that it has graduated, "supports OpenTelemetry" becomes a claim that users and downstream projects increasingly take at face value. A descriptive maturity model is one way to keep that claim honest. - -### Current challenges - -- Support is described as present or absent, with no way to say how deep, consistent, or intentional it actually is. Users cannot evaluate what "supports OpenTelemetry" means for a given project. -- Different projects implement OpenTelemetry support at very different depths. Some push traces via OTLP while metrics stay Prometheus-only. Some use outdated semantic conventions. Some ignore standard `OTEL_*` environment variables. Adopters discover these inconsistencies after the fact. -- Maintainers who want to improve their OpenTelemetry support lack a structured way to identify gaps or prioritize work. "Better telemetry" stays an ad-hoc conversation, project by project. -- Platform teams building stacks across multiple CNCF projects cannot easily compare integration effort. Every project gets evaluated from scratch. -- Existing community efforts, such as the [Instrumentation Score](https://github.com/instrumentation-score/) specification for rule-based signal-quality checks and the [OpenTelemetry Ecosystem Explorer](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer) for component discovery and cataloging, address adjacent concerns but operate independently. Nothing connects design intent, evolution patterns, and signal quality into a coherent picture. - -### Goals, objectives, and requirements - -The goal of this project is to develop and publish a descriptive maturity model for OpenTelemetry support in cloud native projects (and potentially beyond), giving the community a shared framework for evaluating and discussing how that support evolves. - -Objectives: - -1. Define a multi-dimensional maturity model that captures how OpenTelemetry support typically evolves across the dimensions listed below. -2. Validate the model against real projects by applying it to cloud native projects in different categories (ingress controllers, service meshes, application runtimes, and so on), and check whether the dimensions and levels hold up in practice. -3. Publish the model as an OpenTelemetry community resource (for example on opentelemetry.io), with explicit positioning as a descriptive tool, not a certification, compliance, or ranking program. -4. Develop evaluation guidance, including question-based checklists, so reviewers can apply the model consistently across projects. -5. Position the model as complementary to other ecosystem efforts (Instrumentation Score, Ecosystem Explorer), and describe how those tools relate to each other. - -Dimensions in scope: - -The draft model evaluates OpenTelemetry support across seven dimensions. The wording, granularity, and number of dimensions are open for community refinement during the project. The current draft covers: - -1. **Integration Surface**: how users connect a project to their observability pipelines, and how strongly telemetry is coupled to specific tools or vendors. -2. **Semantic Conventions**: how consistently telemetry meaning aligns with OpenTelemetry semantic conventions, and how domain-specific extensions are introduced and stewarded. -3. **Resource Attributes & Configuration**: how identity, scope, and configuration are handled across environments, including correct use of resource attributes and standard `OTEL_*` configuration. -4. **Trace Modeling & Context Propagation**: how traces are structured and how context flows through synchronous and asynchronous execution paths. -5. **Multi-Signal Observability**: how traces, metrics, and logs are supported together and correlated. -6. **Audience & Signal Quality**: who telemetry is designed for, how noisy it is by default, and how well it communicates meaningful system behavior. -7. **Stability & Change Management**: how telemetry evolves over time and how changes are communicated and managed once users depend on it. - -Each dimension is described across four global maturity levels: Level 0 (Instrumented), Level 1 (OpenTelemetry-Aligned), Level 2 (OpenTelemetry-Native), and Level 3 (OpenTelemetry-Optimized). There is no overall maturity score by design; each dimension stands on its own. - -What this project explicitly is not: - -- A specification, standard, or policy proposal. -- A certification or conformance program. -- A ranking or comparison mechanism for CNCF projects. -- A requirement for cloud native or OpenTelemetry projects. - -## Deliverables - -1. **Maturity model document**: a published, community-reviewed maturity model describing OpenTelemetry support across the defined dimensions and global maturity levels. This includes: - - Global maturity level definitions (Level 0: Instrumented, Level 1: OpenTelemetry-Aligned, Level 2: OpenTelemetry-Native, Level 3: OpenTelemetry-Optimized). - - Per-dimension descriptions with characteristics and example scenarios at each level. - - Guidance on how to use the model (for maintainers, contributors, users, and platform teams). - - Explicit positioning relative to other community efforts (Instrumentation Score, Ecosystem Explorer). - - A clear statement on the boundary between project-emitted telemetry and downstream Collector pipeline capabilities. -2. **Evaluation checklist / reference guide**: a question-based evaluation checklist for each dimension and maturity level, designed for consistent, repeatable assessments. The current draft already includes an appendix that will be refined and validated through further use. -3. **Category assessment**: application of the model to at least one category of cloud native projects (for example ingress controllers, service meshes, or application runtimes) to capture the current state of OpenTelemetry support across that space. This both validates the model and demonstrates its value. -4. **Publication on opentelemetry.io**: the maturity model and supporting materials published as community documentation on the OpenTelemetry website, with clear positioning as a descriptive framework maintained by the community. -5. **Companion blog post(s)**: blog post(s) announcing the project and explaining the model's purpose to the broader community. - -Note: this project does not propose changes to the OpenTelemetry Specification or Semantic Conventions. No OTEPs are required. The deliverables are documentation and guidance artifacts. - -## Staffing / Help Wanted - -### Industry outreach (Optional) - -The following people and groups should be aware of this effort. Some have already been engaged; the rest are targets for outreach: - -- **Cloud native project maintainers**: initial conversations have taken place with maintainers of Traefik, Linkerd, Dapr, and kgateway. Further outreach is needed for maintainers in other categories (databases, service meshes, CI/CD tools, and so on). -- **CNCF TAG Operational Resilience**: as the TAG responsible for observability guidance across CNCF, their input matters. -- **CNCF TCG Platform Engineering**: the maturity model is structurally inspired by the [CNCF Platform Engineering Maturity Model](https://tag-app-delivery.cncf.io/whitepapers/platform-eng-maturity-model/), which was developed by WG Platform Engineering under TAG App Delivery. -- **CNCF TAG Developer Experience**: can provide input and help validate the current status of projects. -- **OpenTelemetry End User SIG**: end users have the strongest perspective on what "OpenTelemetry support" should mean in practice. -- **Observability vendors and platform teams**: companies building on OpenTelemetry that work across many CNCF projects can offer practical feedback. - -### SIG - -This project is cross-cutting. It touches documentation, semantic conventions, ecosystem tooling, and end-user concerns. Two viable paths: - -- Lead under an existing SIG (for example SIG Communications or SIG End User), with explicit coordination touchpoints to SIG Docs and SIG Semantic Conventions. -- Form a dedicated working group with representation from multiple SIGs. - -Recommendation: discuss with TC and GC during proposal review. A working group under SIG Communications, mirroring how the Ecosystem Explorer project is organized, seems like a sensible fit given the documentation- and ecosystem-facing nature of the deliverables. - -### Required staffing - -#### Project Lead(s) - -- **Kasper Borg Nissen** ([@kaspernissen](https://github.com/kaspernissen)), Dash0: author of the draft maturity model. Has been developing and validating the framework through blog posts, talks, and direct engagement with cloud native projects. -- **Michael Hausenblas** ([@mhausenblas](https://github.com/mhausenblas)): brings the end-user perspective through his role at an end-user organization, and has committed to co-leading the project. - -#### Interested contributors - -The following people publicly expressed interest in contributing during the discussion on [issue #3247](https://github.com/open-telemetry/community/issues/3247) and on this PR. Specific roles and commitments will be confirmed as part of the proposal review: - -- **Mauricio Salatino** ([@salaboy](https://github.com/salaboy)): cross-project experience (Dapr, Knative); willing to help develop checklists and evaluations. -- **Mehmet Baykara** ([@mbaykara](https://github.com/mbaykara)): working on an adjacent observability maturity model effort; willing to compare notes, review dimension wording, and contribute enterprise/customer adoption examples. -- **Severin Neumann** ([@svrnm](https://github.com/svrnm)): SIG Communications / Docs perspective; expressed support for hosting on opentelemetry.io and helped frame the ownership question. -- **Henrik Rexed** ([@henrikrexed](https://github.com/henrikrexed)): provided detailed feedback on the developer-facing actionability of the model and on the per-signal scoring trade-off; willing to do a thorough pass on the document. - -_Additional contributors actively sought:_ - -- **Assessment authors**: contributors willing to apply the model to CNCF projects they maintain or use, so the set of reference assessments grows beyond ingress controllers. -- **Documentation contributors**: contributors to help shape the model for publication on opentelemetry.io. -- **Semantic conventions reviewers**: reviewers from SIG Semantic Conventions to align the semantic conventions dimension with the project's direction, including Weaver-based workflows. - -### Sponsorship - -#### TC Sponsor - -_To be confirmed._ Seeking a TC sponsor with interest in ecosystem integration, instrumentation quality, or cross-project OpenTelemetry support. - -#### GC Liaison - -_To be confirmed._ Seeking a GC liaison to keep the project healthy and the scope true to the proposal. - -## Expected Timeline - -The project is structured in three phases. - -### Phase 1: Community review and model refinement (Month 1–2) - -- Submit the project proposal for GC/TC review. -- Solicit community feedback on the draft maturity model through the proposal PR and community meetings. -- Refine dimensions, maturity levels, and evaluation checklists based on feedback. -- Recruit additional contributors, confirm staffing, and agree on SIG ownership. - -### Phase 2: Validation and documentation (Month 3–4) - -- Apply the refined model to at least one category of CNCF projects. -- Develop the model into publishable documentation for opentelemetry.io. -- Coordinate with SIG Docs on publication format and placement. -- Coordinate with related efforts (Instrumentation Score, Ecosystem Explorer) on complementary positioning. - -### Phase 3: Publication and handoff (Month 5–6) - -- Publish the maturity model and category assessment on opentelemetry.io. -- Establish ongoing maintenance ownership (SIG or working group). -- Decide whether the project transitions to ongoing SIG work or wraps up. - -## Labels (Optional) - -- `area/maturity-model` -- `area/ecosystem` - -## GitHub Project (Post-Approval) - -_To be set up after approval._ - -## SIG Meetings, Roadmap, and Other Info (Post-Approval) - -_To be set up after approval._ - -## Related work and references - -- [Community issue #3247: Draft proposal — OpenTelemetry Support Maturity Model for CNCF projects](https://github.com/open-telemetry/community/issues/3247) -- [Draft maturity model document](https://docs.google.com/document/d/1KvRtYqdSR1ii-SLV2wEv0MH-j9Mh5xA5u7f51kO6xpw/edit?usp=sharing) -- [CNCF Platform Engineering Maturity Model](https://tag-app-delivery.cncf.io/whitepapers/platform-eng-maturity-model/) (structural inspiration) -- [Instrumentation Score](https://github.com/instrumentation-score/) (complementary: rule-based signal quality checks) -- [OpenTelemetry Ecosystem Explorer](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer) (complementary: component discovery and cataloging) -- [OpenTelemetry Ecosystem Integrations](https://opentelemetry.io/ecosystem/integrations/) (23+ CNCF projects listed) -- [OpenTelemetry Weaver](https://github.com/open-telemetry/weaver) (tooling referenced for semantic extensions at Level 3) -- [Prometheus Conformance Program](https://github.com/cncf/prometheus-conformance) (reference for a possible future, separate conformance effort) diff --git a/projects/otel-support-self-assessment.md b/projects/otel-support-self-assessment.md new file mode 100644 index 000000000..000bda2e5 --- /dev/null +++ b/projects/otel-support-self-assessment.md @@ -0,0 +1,171 @@ +# OpenTelemetry Support Self-Assessment and Maintainer Guidance + +## Background and description + +OpenTelemetry has become the de facto standard for producing telemetry in cloud native systems, and a growing number of projects across the ecosystem emit their telemetry through it. But "supports OpenTelemetry" has become a binary claim that hides enormous variance in what a project actually delivers, and adopters absorb the cost of that variance when they integrate. + +This project aims to help maintainers close that gap themselves. It has two parts: opt-in tooling a maintainer can run against their own project's telemetry to get a factual report of what is emitted and where the gaps are, and maintainer-facing guidance on what good OpenTelemetry support looks like for different classes of projects. + +> **Revision note.** An earlier version of this proposal described a descriptive maturity model with 0–3 levels per dimension, applied by this project to other cloud native projects and published as a comparative assessment. Review feedback made clear that OpenTelemetry should not be in the business of evaluating or labeling other projects, which is also consistent with CNCF guidance that projects avoid judging one another. That framing has been removed. The proposal now centers on self-assessment tooling and maintainer guidance, with the original dimensions retained only as internal scaffolding for what the tooling checks and the guides cover. See the discussion on [PR #3435](https://github.com/open-telemetry/community/pull/3435). + +Support is rarely all-or-nothing. Projects mature unevenly: integration surfaces, semantics, configuration, trace modeling, and multi-signal workflows tend to evolve on different timelines. In practice, adopters hit projects where traces flow via OTLP but metrics are still Prometheus-only, where semantic conventions are several versions out of date, or where standard `OTEL_*` configuration is quietly ignored in favor of project-specific flags. Each integration becomes its own learning curve, and what works for one project rarely carries cleanly to the next. + +Nearly half of respondents in the latest CNCF survey report using OpenTelemetry in production. At that scale, and now that OpenTelemetry has reached CNCF Graduated status, the claim "supports OpenTelemetry" is increasingly taken at face value. Without guidance, projects will keep arriving at their own definitions of what it means, and adopters will keep discovering the differences after the fact. + +The idea originated in [community issue #3247](https://github.com/open-telemetry/community/issues/3247) and was refined substantially through review on [PR #3435](https://github.com/open-telemetry/community/pull/3435). + +### Current challenges + +- There is no shared definition of what "supports OpenTelemetry" means, so projects define it for themselves and adopters cannot tell what a given claim covers. +- Maintainers who want to improve their OpenTelemetry support have no way to check their project's actual telemetry output against current conventions and expectations. Gaps are found by users, not by maintainers. +- Maintainers also lack guidance on what good looks like for their kind of project. The considerations for a library differ substantially from those for a database, a message broker, or a gateway, and generic advice does not carry across those classes. +- Instrumentation quality problems surface late. Semantic convention drift, missing resource attributes, unsupported standard configuration, and inconsistent context propagation are all discoverable from a project's own telemetry, but nothing packages those checks for maintainers today. +- Existing community efforts, such as the [Instrumentation Score](https://github.com/instrumentation-score/) specification for rule-based signal-quality checks and the [OpenTelemetry Ecosystem Explorer](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer) for component discovery and cataloging, address adjacent concerns. Neither gives a maintainer an actionable, project-level answer to "what is missing in my integration, and what should I do next?" + +### Goals, objectives, and requirements + +The goal of this project is to make it easier for maintainers of projects outside OpenTelemetry to build and improve high-quality OpenTelemetry support, by giving them tooling they run themselves and guidance written for their kind of project. + +Objectives: + +1. **Opt-in self-assessment tooling.** Build tooling a maintainer runs against their own project's emitted telemetry, producing a factual report: what signals are emitted, which semantic conventions are followed, which standard configuration is honored, and where the gaps are. The output is diagnostic information and next steps, not a score, and it belongs to whoever ran it. +2. **Maintainer-facing guidance by project type.** Publish guides covering what good OpenTelemetry support looks like, the common pitfalls, and how to get there, differentiated by class of project (see Deliverables). +3. **Ground the guidance in real cases.** Work with maintainers who want help, use what those engagements surface to decide what the guides and the tooling need to cover, and feed improvements back upstream. +4. **Position clearly relative to adjacent efforts.** Reuse [Instrumentation Score](https://github.com/instrumentation-score/) rules where they apply rather than duplicating them, coordinate with the [Ecosystem Explorer](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer), and stay aligned with SIG Semantic Conventions tooling, including Weaver-based workflows. + +#### What this project explicitly is not + +This is worth stating plainly, because an earlier draft of this proposal was read otherwise: + +- **OpenTelemetry does not evaluate, score, rank, or label other projects as part of this work.** No assessment of a third-party project is produced or published by this project. The tooling is run by maintainers on their own projects, and the results are theirs to use or share as they see fit. +- It is not a certification, conformance, or badging program. +- It is not a comparison mechanism, an industry analysis, or an input to one. +- It is not a specification, standard, or policy proposal, and it is not a requirement for any project. +- It does not propose changes to the OpenTelemetry Specification or Semantic Conventions. No OTEPs are required. + +#### Assessment dimensions (internal scaffolding) + +The earlier draft organized OpenTelemetry support into seven dimensions. Those dimensions are retained as internal structure for deciding what the tooling checks and what the guides must cover. They are not a public grading rubric, and the associated 0–3 maturity levels have been dropped. + +1. **Integration surface**: how users connect a project to their observability pipelines, and how strongly telemetry is coupled to specific tools or vendors. +2. **Semantic conventions**: how consistently telemetry meaning aligns with OpenTelemetry semantic conventions, and how domain-specific extensions are introduced and stewarded. +3. **Resource attributes and configuration**: how identity, scope, and configuration are handled across environments, including correct use of resource attributes and standard `OTEL_*` configuration. +4. **Trace modeling and context propagation**: how traces are structured and how context flows through synchronous and asynchronous execution paths. +5. **Multi-signal observability**: how traces, metrics, and logs are supported together and correlated. +6. **Audience and signal quality**: who telemetry is designed for, how noisy it is by default, and how well it communicates meaningful system behavior. +7. **Stability and change management**: how telemetry evolves over time and how changes are communicated and managed once users depend on it. + +The wording, granularity, and number of dimensions remain open for refinement as the tooling and guides are built. If a dimension does not earn its place in either deliverable, it should be dropped. + +## Deliverables + +1. **Self-assessment tooling.** Tooling a maintainer can point at their project's telemetry output and get back a report covering emitted signals, semantic convention alignment, resource attributes, standard configuration support, and context propagation, with concrete next steps and links into the guides. Delivered incrementally, starting with a prototype validated against volunteer projects. Requirements: + - Deterministic and objective. Where a check cannot be made automatically and objectively, it belongs in a guide, not in the tool's output. + - No score, grade, or level in the output. + - Run locally by the maintainer. This project does not host, collect, or publish results. + - Reuses existing rule sets, notably Instrumentation Score, rather than restating them. + +2. **Maintainer guides by project type.** Guidance on what good OpenTelemetry support looks like, with common pitfalls and worked examples: + - **Libraries**: adding native instrumentation, API-vs-SDK boundaries, and what to expose to the embedding application. + - **Services and infrastructure components** (databases, message brokers, proxies and gateways, controllers): emitting OTLP, writing and stewarding federated semantic conventions, and exposing standard configuration. + + OpenTelemetry Collector distributions are deliberately out of scope here; that class is covered by the separate Collector certification effort. + +3. **Publication on opentelemetry.io.** The guides published as community documentation, coordinated with SIG Docs on format and placement. + +4. **Companion blog post(s).** Announcing the guidance and tooling to the broader community, aimed at maintainers of projects that integrate with OpenTelemetry. + +## Staffing / Help Wanted + +### SIG + +No new SIG is proposed. A working group will be formed under **SIG Communications**, mirroring how the [Ecosystem Explorer project](./ecosystem-explorer.md) is organized, with SIG Communications meetings used for project updates and coordination. + +Coordination touch points: + +- **SIG Semantic Conventions**, on convention alignment, federated conventions, and Weaver-based tooling. +- **SIG Docs / Communications**, on publication of the guides. +- **Instrumentation Score** and **Ecosystem Explorer** maintainers, on complementary positioning and rule reuse. + +### Required staffing + +#### Project Lead(s) + +- **Kasper Borg Nissen** ([@kaspernissen](https://github.com/kaspernissen)), Dash0: author of the original draft; has been developing and validating the underlying framework through blog posts, talks, and direct engagement with cloud native projects. +- **Graziano Casto** ([@graz-dev](https://github.com/graz-dev)), Akamas: proposed the opt-in self-assessment framing that this revision is built around, and has volunteered to co-drive the work. Also Tech Lead in CNCF TAG Developer Experience, which is a useful channel for validating the guides with maintainers. + +_Pending confirmation:_ **Michael Hausenblas** ([@mhausenblas](https://github.com/mhausenblas)) volunteered to co-lead the earlier version of this proposal. Given the change in scope, he is being asked whether he wants to continue in that role. + +#### Interested contributors + +The following people expressed interest during the discussion on [issue #3247](https://github.com/open-telemetry/community/issues/3247) and [PR #3435](https://github.com/open-telemetry/community/pull/3435). Specific roles will be confirmed as the working group forms: + +- **Mauricio Salatino** ([@salaboy](https://github.com/salaboy)): cross-project experience (Dapr, Knative); has already started work on evaluation automation, which maps directly onto the self-assessment tooling deliverable. +- **Severin Neumann** ([@svrnm](https://github.com/svrnm)): SIG Communications / Docs perspective; supports hosting the guidance on opentelemetry.io and framed the ownership question. +- **Henrik Rexed** ([@henrikrexed](https://github.com/henrikrexed)): provided detailed feedback on developer-facing actionability; willing to do a thorough review pass. +- **Mehmet Baykara** ([@mbaykara](https://github.com/mbaykara)): working on an adjacent observability maturity effort; willing to compare notes and contribute adoption examples. + +_Additional contributors actively sought:_ + +- **Tooling contributors** to build and validate the self-assessment prototype. +- **Guide authors**, particularly maintainers who have added native instrumentation to a library or a data service and can write up what they learned. +- **Volunteer projects** willing to run the prototype against their own telemetry and give feedback on whether the report is actionable. + +### Sponsorship + +#### TC Sponsor + +_To be confirmed._ Per review feedback, this project would benefit from a TC sponsor at the guiding or leading level, since the work touches semantic conventions, docs, and ecosystem tooling across several SIGs. + +#### GC Liaison + +_To be confirmed._ + +### Industry outreach (Optional) + +- **Cloud native project maintainers**: conversations have taken place with maintainers of Traefik, Linkerd, Dapr, and kgateway, several of which led to upstream changes. These engagements are the source material for the first guides. Further outreach is needed across other classes of projects. +- **OpenTelemetry End User SIG**: end users have the strongest perspective on what "OpenTelemetry support" should mean in practice. +- **CNCF TAG Operational Resilience** and **CNCF TAG Developer Experience**: relevant for observability guidance and for validating the guides against maintainer needs. + +## Expected Timeline + +### Phase 1: Scope confirmation and staffing (Month 1–2) + +- Establish the working group under SIG Communications and use its meetings for coordination. +- Confirm leads, contributors, TC sponsor, and GC liaison. +- Agree the checklist content per project class: what the tooling can verify objectively, and what belongs in a guide. + +### Phase 2: Prototype and first guide (Month 3–4) + +- Build a self-assessment prototype covering the objectively verifiable checks. +- Validate it against volunteer projects, with maintainer consent, and iterate on whether the report is actionable. +- Draft the first maintainer guide. + +### Phase 3: Publication (Month 5–6) + +- Publish the guides on opentelemetry.io. +- Release the self-assessment tooling for maintainers to run. +- Companion blog post. +- Decide whether the work continues as ongoing SIG Communications work or wraps up. + +## Labels (Optional) + +- `area/ecosystem` + +## GitHub Project (Post-Approval) + +_To be set up after approval._ + +## SIG Meetings, Roadmap, and Other Info (Post-Approval) + +_To be set up after approval._ + +## Related work and references + +- [Community issue #3247: Draft proposal — OpenTelemetry Support Maturity Model for CNCF projects](https://github.com/open-telemetry/community/issues/3247) +- [PR #3435 discussion](https://github.com/open-telemetry/community/pull/3435) (where the scope of this proposal was reframed) +- [Instrumentation Score](https://github.com/instrumentation-score/) (complementary: rule-based signal quality checks) +- [OpenTelemetry Ecosystem Explorer](https://github.com/open-telemetry/opentelemetry-ecosystem-explorer) (complementary: component discovery and cataloging) +- [OpenTelemetry Ecosystem Integrations](https://opentelemetry.io/ecosystem/integrations/) +- [OpenTelemetry Weaver](https://github.com/open-telemetry/weaver) (tooling for semantic convention workflows) +- [OpenTelemetry Collector Distribution definition](https://github.com/open-telemetry/opentelemetry-collector/tree/main/docs#opentelemetry-collector-distribution) From b583bf02a80e9ee19bbfe8cdfab7b635f1361073 Mon Sep 17 00:00:00 2001 From: Kasper Borg Nissen Date: Fri, 14 Aug 2026 12:44:54 +0200 Subject: [PATCH 6/7] Apply suggestion from @graz-dev Co-authored-by: Graziano Casto --- projects/otel-support-self-assessment.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/projects/otel-support-self-assessment.md b/projects/otel-support-self-assessment.md index 000bda2e5..dbe2bf3e0 100644 --- a/projects/otel-support-self-assessment.md +++ b/projects/otel-support-self-assessment.md @@ -92,7 +92,7 @@ Coordination touch points: #### Project Lead(s) - **Kasper Borg Nissen** ([@kaspernissen](https://github.com/kaspernissen)), Dash0: author of the original draft; has been developing and validating the underlying framework through blog posts, talks, and direct engagement with cloud native projects. -- **Graziano Casto** ([@graz-dev](https://github.com/graz-dev)), Akamas: proposed the opt-in self-assessment framing that this revision is built around, and has volunteered to co-drive the work. Also Tech Lead in CNCF TAG Developer Experience, which is a useful channel for validating the guides with maintainers. +- **Graziano Casto** ([@graz-dev](https://github.com/graz-dev)), Akamas: proposed the opt-in self-assessment framing that this revision is built around, and has volunteered to co-drive the work. Also Co-Chair in CNCF TAG Developer Experience, which is a useful channel for validating the guides with maintainers. _Pending confirmation:_ **Michael Hausenblas** ([@mhausenblas](https://github.com/mhausenblas)) volunteered to co-lead the earlier version of this proposal. Given the change in scope, he is being asked whether he wants to continue in that role. From 76768f078b236d51f44e56a4f904d7a3cc0ca920 Mon Sep 17 00:00:00 2001 From: Kasper Borg Nissen Date: Mon, 14 Sep 2026 09:21:21 +0200 Subject: [PATCH 7/7] Update projects/otel-support-self-assessment.md Co-authored-by: Graziano Casto --- projects/otel-support-self-assessment.md | 29 ++++++++++++++++-------- 1 file changed, 19 insertions(+), 10 deletions(-) diff --git a/projects/otel-support-self-assessment.md b/projects/otel-support-self-assessment.md index dbe2bf3e0..a5ed320f2 100644 --- a/projects/otel-support-self-assessment.md +++ b/projects/otel-support-self-assessment.md @@ -59,21 +59,30 @@ The wording, granularity, and number of dimensions remain open for refinement as ## Deliverables -1. **Self-assessment tooling.** Tooling a maintainer can point at their project's telemetry output and get back a report covering emitted signals, semantic convention alignment, resource attributes, standard configuration support, and context propagation, with concrete next steps and links into the guides. Delivered incrementally, starting with a prototype validated against volunteer projects. Requirements: +1. **Project classification model.** A shared taxonomy of project classes, based on where a project sits architecturally with respect to telemetry rather than on what it does functionally. This is the first artifact, because both other deliverables depend on it: the tooling uses it to decide which checks apply to a given project, and the guides are organized around it. Classes are self-declared by the maintainer, never assigned by this project. + +2. **Self-assessment tooling.** Tooling a maintainer can point at their own project's telemetry to get a factual report of what is emitted and where the gaps are, with concrete next steps and links into the guides. Delivered incrementally. + +**Scope for the first iteration: analysis of telemetry the maintainer already has.** The input is a captured OTLP payload produced by the project during something the maintainer already runs. The tool does not start the project, does not generate load, and does not re-run it under varying configuration. This keeps the first iteration deterministic and replayable, makes it usable in CI, and keeps the adoption cost close to zero. + + Explicitly deferred to a later iteration: anything that requires the tool to execute the project or vary its configuration, including whether standard `OTEL_*` configuration is honored and end-to-end propagation across process boundaries. Those are covered in the guides for now, and can be revisited once the payload-level checks have proven useful. + + Requirements: - Deterministic and objective. Where a check cannot be made automatically and objectively, it belongs in a guide, not in the tool's output. - - No score, grade, or level in the output. - - Run locally by the maintainer. This project does not host, collect, or publish results. - - Reuses existing rule sets, notably Instrumentation Score, rather than restating them. + - No score, grade or level in the output, and no aggregate count that invites one. + - Checks observable output, not implementation choices. + - Run locally by the maintainer. This project does not host, collect or publish results. + - Reuses existing rule sets rather than restating them. + - Reports what was *not* checked, so that an empty findings list is not mistaken for a pass. + - Rule-to-class applicability expressed as data, so that classes and rules can be added without code changes. -2. **Maintainer guides by project type.** Guidance on what good OpenTelemetry support looks like, with common pitfalls and worked examples: - - **Libraries**: adding native instrumentation, API-vs-SDK boundaries, and what to expose to the embedding application. - - **Services and infrastructure components** (databases, message brokers, proxies and gateways, controllers): emitting OTLP, writing and stewarding federated semantic conventions, and exposing standard configuration. +3. **Maintainer guides by project type.** Guidance on what good OpenTelemetry support looks like, with common pitfalls and worked examples, organized around the classes above. - OpenTelemetry Collector distributions are deliberately out of scope here; that class is covered by the separate Collector certification effort. +OpenTelemetry Collector distributions are deliberately out of scope here; that class is covered by the separate Collector certification effort. -3. **Publication on opentelemetry.io.** The guides published as community documentation, coordinated with SIG Docs on format and placement. +4. **Publication on opentelemetry.io.** The guides published as community documentation, coordinated with SIG Docs on format and placement. -4. **Companion blog post(s).** Announcing the guidance and tooling to the broader community, aimed at maintainers of projects that integrate with OpenTelemetry. +5. **Companion blog post(s).** Announcing the guidance and tooling to the broader community, aimed at maintainers of projects that integrate with OpenTelemetry. ## Staffing / Help Wanted