From 2555b43c9952c38435457104ffdc8ab616c899e9 Mon Sep 17 00:00:00 2001 From: svrnm Date: Mon, 29 Jul 2024 18:23:40 +0200 Subject: [PATCH 1/3] Project proposal: Registry Next Generation Signed-off-by: svrnm --- projects/registry-ng.md | 58 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 projects/registry-ng.md diff --git a/projects/registry-ng.md b/projects/registry-ng.md new file mode 100644 index 000000000..33d2f7566 --- /dev/null +++ b/projects/registry-ng.md @@ -0,0 +1,58 @@ +# <> + +## Background and description + +Add any background that may be needed to introduce the scope of this project. + +### Current challenges +List the current challenges that this project aims to solve. Focus on the problem here, how it affects users and what the downsides are if nothing is done, rather than the solution. + +### Goals, objectives, and requirements +Describe the aim of this project, including the goals, objectives and requirements needed to solve the challenges presented in the previous section. Include here the motivations for starting the project now, as opposed to later. Call out the benefits for the OpenTelemetry project when this project is completed. + +## Deliverables + +A description of what this project is planning to deliver, or is in the process of delivering. This includes all OTEPs and their associated prototypes. + +In general, OTEPs are not accepted unless they come with working prototypes available to review in at least two languages. Please discuss these requirements with a TC member before submitting an OTEP. + +## Staffing / Help Wanted + +Who is currently planning to work on the project? If a project requires specialized domain expertise, please list it here. If a project is missing a critical mass of people in order to begin work, please clarify. + +### Required staffing + +Projects cannot be started until the following participants have been identified: +* Every project needs a project lead, who is willing to bottom line the project and address any issues which are not handled by other project members. +* At least two sponsoring TC or GC members. Sponsors are dedicated to attending meetings, reviewing proposals, and in general being aware of the state of the project and its technical details. Sponsors guide the project through the spec process, keep the tracking issue up to date, and help to ensure that relevant community members provide input at the appropriate times. +* A GC liaison to facilitate this SIG's health and ensure project scope remains true to the project description. If a GC member is also a sponsor for this project, they are by default the GC liaison (see [GC check-ins](https://github.com/open-telemetry/community/blob/main/gc-check-ins.md)). +* Engineers willing to write prototypes in at least two languages (if relevant to project). Languages should be fairly different from each other (for example: Java and Python). +* Maintainers or approvers from those languages committed to reviewing the prototypes. + +## Timeline + +What is the expected timeline the project will aim to adhere to, and what resources and deliverables will be needed for each portion of the timeline? If the project has not been started, please describe this timeline in relative terms (one month in, two weeks later, etc). If a project has started, please include actual dates. + +## Labels + +Issues should be properly labeled to indicate what parts of the specification it is focused on. List here the labels applicable to this project. + +## Project Board + +Once approved, a project should be managed using a GitHub project board (see [open projects](https://github.com/orgs/open-telemetry/projects?query=is%3Aopen)). This project board should be pre-populated with issues that cover all known deliverables, organized by timeline milestones. + +Any [member](https://github.com/open-telemetry/community/blob/main/community-membership.md) associated with the project can create the board. Once created, the creator of the board should: + +- Assign `Admin` privileges on the project to the relevant project members (using a new or existing GitHub team). +- Change the visibility of the project to `Public` in order to share project status and priorities outside of the OpenTelemetry organization. +- Configure project workflows to automatically add issues and PRs to the board based on repositories and labels. + +Once created, please add a link to the project board here. + +## SIG Meetings and Other Info + +Once a project is started, its corresponding SIG should meet regularly for discussion. These meeting times should be posted on the [OpenTelemetry public calendar](https://github.com/open-telemetry/community#calendar) and automatically recorded. + +Any relevant information related to the SIG (e.g. sponsors, meeting times, Slack channels, meeting notes, etc.) must be publicly available in the [community](https://github.com/open-telemetry/community) SIG tables, which can be updated via the [sigs.yml](https://github.com/open-telemetry/community/blob/main/sigs.yml) file and running `make table-generation`. + +See [How to create and configure meetings](https://github.com/open-telemetry/community/blob/main/docs/how-to-handle-public-calendar.md) for updating the public calendar or open an issue in the community repository so it's taken care of. From 90c0f9371f8605e1e81f5b17babc69f094fd4562 Mon Sep 17 00:00:00 2001 From: svrnm Date: Wed, 31 Jul 2024 18:13:23 +0200 Subject: [PATCH 2/3] write more words Signed-off-by: svrnm --- .cspell.yaml | 1 + projects/registry-data-quality.md | 103 ++++++++++++++++++++++++++++++ projects/registry-ng.md | 58 ----------------- 3 files changed, 104 insertions(+), 58 deletions(-) create mode 100644 projects/registry-data-quality.md delete mode 100644 projects/registry-ng.md diff --git a/.cspell.yaml b/.cspell.yaml index c00853515..f54502ef4 100644 --- a/.cspell.yaml +++ b/.cspell.yaml @@ -116,6 +116,7 @@ words: - mateuszrzeszutek - mayur - mayurkale + - mdatagen - mdelfabro - mhausenblas - mirabella diff --git a/projects/registry-data-quality.md b/projects/registry-data-quality.md new file mode 100644 index 000000000..c16e33911 --- /dev/null +++ b/projects/registry-data-quality.md @@ -0,0 +1,103 @@ +# OpenTelemetry Registry Data Quality Improvements + +## Background and description + +The [OpenTelemetry registry](https://opentelemetry.io/ecosystem/registry/) has been a part of the OpenTelemetry project from the start: +inherited from the [OpenTracing registry](https://opentracing.io/registry/) it provides an entry point for end users to find all the +building blocks they need for observability. + +The registry is a part of the [OpenTelemetry website](https://opentelemetry.io/) and currently maintained by SIG Communications as part +of that. + +Although hidden under `Ecosystem > Registry` in the navigation, the registry is among the top 10 pages YTD +([based on Google Analytics Data](https://lookerstudio.google.com/s/qhPHQtyfRbU)). + +In the last months SIG Comms implemented a set of changes to the registry, to make it more user-friendly and easier to find: + +- [A semi-automatic semi-complete scanner](https://github.com/open-telemetry/opentelemetry.io/pull/1920) +- [Rework of the design](https://github.com/open-telemetry/opentelemetry.io/pull/3730), including a new search engine, badges, quick installation instructions +- [A daily run workflow that keeps package versions up-to-date](https://github.com/open-telemetry/opentelemetry.io/pull/3840) +- [A JSON schema definition to verify registry entry format](https://github.com/open-telemetry/opentelemetry.io/pull/4805) +- [Included the registry in many pages, including the sidebar navigation for all languages and the collector](https://github.com/open-telemetry/opentelemetry.io/pull/3932) + +Overall, the registry is in a good shape and is slowly turning into a place that people use for it's original intend. + +### Current challenges + +While being reworks in incremental steps in the last few months, the registry is still facing a set of challenges, that require a bigger +review and eventually a collaboration across many SIGs to be addressed: + +1. Besides the update of package versions, the maintenance is a manual process: + 1. Packages from different project repositories are either detected by a semi-automatic scanner, that needs to be run + manually, or by SIGs reporting new entries themselves. + 2. After a package has been added to the registry, it is a manual process to verify if the package is still available and + if the meta-data is still correct. +2. Packages lack a lot of information, and the information available is sometimes of bad quality. Metadata that might be available + for packages is not in a human readable format, or in the case of the collector (`mdatagen`-data) not consumed by the registry. +3. [Vendors](https://opentelemetry.io/ecosystem/vendors/), [Integrations](https://opentelemetry.io/ecosystem/integrations/), [Adopters](https://opentelemetry.io/ecosystem/adopters/) and [Distributions](https://opentelemetry.io/ecosystem/distributions/) are separated out into their own pages, and entries on these pages are also hard to maintain and verify. +4. Adding an entry to the registry requires the addition of a YAML file, in a pre-defined format, that until recently has not been enforced consistently. + +All these issues are mostly related to the quality of the data, i.e. what is available, what is outdated, how detailed is the data +and how useable is that data. If we address those issues end users will see the registry as a valuable place and will use +it to find the building blocks they need, and by reaching that state, we can use the registry to accomplish other goals, like + +- making end users aware of non-otel-community created components they can use. Combined with a system to label "good quality" + packages, we can go from building everything as a community to endorsing good work. +- having a complete overview ourselves of the components that exist within the project and outside in the wider ecosystem +- having a single place that allows end users not only to learn what is available, but also what they get from using a + certain component (stability levels, supported signals, exported trace/metric/log names) +- having a central place with all the names and versions, that can be used in different places of the registry. +- communicating certain preferences of our project, i.e. by tagging instrumentations as "native" or "first party" we can + indicate that native instrumentations are best, vs having instrumentation libraries. + +### Goals, objectives, and requirements + +The goal of this project is to improve the quality of the data in the registry in a way, that it is + +- complete for project-owned components (collector, instrumentation libraries, exporters, resource detectors, loggers) +- always up-to-date for all components (versions, deprecation, deletions) +- fine-grained, meaningful and of consistent quality (not only some basic names and description, but meta data like stability, signals, etc.) +- labelled in a way that we can communicate certain preferences (native, "by first party", etc.) +- kept up-to-date by automatic workflows + +The goal of this particular project is _only_ about the data quality and tooling that helps to build and keep the data up-to-date. +Changing the software of the registry is out of scope, except it will be helpful to accomplish any of the objectives mentioned above. + +To accomplish this goal, this project requires support from all SIGs delivering software artifacts, consumed by end users, this includes +especially the [Implementation SIGs](https://github.com/open-telemetry/community/?tab=readme-ov-file#implementation-sigs), since this +project will create some standards to make data readable, that might need to be implemented across the project + +## Deliverables + +To accomplish the goals mentioned above this project, will create the following deliverables + +- A machine-readable meta-data format and schema, that contains all the potential details of a registry entry. This may build on top of `mdatagen`, + but as part of the project other existing formats will be reviewed for consideration. +- Tooling to read that data from different sources (pull or push, tbd) to keep the registry up-to-date +- A tagging and labelling system to highlight components that fit into certain criteria + +## Staffing / Help Wanted + +GC/TC sponsors: + +- `` +- `` + +Contributors: + +- `` + +**Note**: there is no goal to create a new SIG for this. This is a (hopefully) mid-term living group of people collaborating to accomplish this goal, +or this may be part of an existing SIG (Comms, Project Infra, ...), but with some dedicated resources. + +## Timeline + +`` + +## Project Board + +`` + +## SIG Meetings and Other Info + +`` diff --git a/projects/registry-ng.md b/projects/registry-ng.md deleted file mode 100644 index 33d2f7566..000000000 --- a/projects/registry-ng.md +++ /dev/null @@ -1,58 +0,0 @@ -# <> - -## Background and description - -Add any background that may be needed to introduce the scope of this project. - -### Current challenges -List the current challenges that this project aims to solve. Focus on the problem here, how it affects users and what the downsides are if nothing is done, rather than the solution. - -### Goals, objectives, and requirements -Describe the aim of this project, including the goals, objectives and requirements needed to solve the challenges presented in the previous section. Include here the motivations for starting the project now, as opposed to later. Call out the benefits for the OpenTelemetry project when this project is completed. - -## Deliverables - -A description of what this project is planning to deliver, or is in the process of delivering. This includes all OTEPs and their associated prototypes. - -In general, OTEPs are not accepted unless they come with working prototypes available to review in at least two languages. Please discuss these requirements with a TC member before submitting an OTEP. - -## Staffing / Help Wanted - -Who is currently planning to work on the project? If a project requires specialized domain expertise, please list it here. If a project is missing a critical mass of people in order to begin work, please clarify. - -### Required staffing - -Projects cannot be started until the following participants have been identified: -* Every project needs a project lead, who is willing to bottom line the project and address any issues which are not handled by other project members. -* At least two sponsoring TC or GC members. Sponsors are dedicated to attending meetings, reviewing proposals, and in general being aware of the state of the project and its technical details. Sponsors guide the project through the spec process, keep the tracking issue up to date, and help to ensure that relevant community members provide input at the appropriate times. -* A GC liaison to facilitate this SIG's health and ensure project scope remains true to the project description. If a GC member is also a sponsor for this project, they are by default the GC liaison (see [GC check-ins](https://github.com/open-telemetry/community/blob/main/gc-check-ins.md)). -* Engineers willing to write prototypes in at least two languages (if relevant to project). Languages should be fairly different from each other (for example: Java and Python). -* Maintainers or approvers from those languages committed to reviewing the prototypes. - -## Timeline - -What is the expected timeline the project will aim to adhere to, and what resources and deliverables will be needed for each portion of the timeline? If the project has not been started, please describe this timeline in relative terms (one month in, two weeks later, etc). If a project has started, please include actual dates. - -## Labels - -Issues should be properly labeled to indicate what parts of the specification it is focused on. List here the labels applicable to this project. - -## Project Board - -Once approved, a project should be managed using a GitHub project board (see [open projects](https://github.com/orgs/open-telemetry/projects?query=is%3Aopen)). This project board should be pre-populated with issues that cover all known deliverables, organized by timeline milestones. - -Any [member](https://github.com/open-telemetry/community/blob/main/community-membership.md) associated with the project can create the board. Once created, the creator of the board should: - -- Assign `Admin` privileges on the project to the relevant project members (using a new or existing GitHub team). -- Change the visibility of the project to `Public` in order to share project status and priorities outside of the OpenTelemetry organization. -- Configure project workflows to automatically add issues and PRs to the board based on repositories and labels. - -Once created, please add a link to the project board here. - -## SIG Meetings and Other Info - -Once a project is started, its corresponding SIG should meet regularly for discussion. These meeting times should be posted on the [OpenTelemetry public calendar](https://github.com/open-telemetry/community#calendar) and automatically recorded. - -Any relevant information related to the SIG (e.g. sponsors, meeting times, Slack channels, meeting notes, etc.) must be publicly available in the [community](https://github.com/open-telemetry/community) SIG tables, which can be updated via the [sigs.yml](https://github.com/open-telemetry/community/blob/main/sigs.yml) file and running `make table-generation`. - -See [How to create and configure meetings](https://github.com/open-telemetry/community/blob/main/docs/how-to-handle-public-calendar.md) for updating the public calendar or open an issue in the community repository so it's taken care of. From 9052e4fda4e800b735e9515ac12cbf2a21e36ed0 Mon Sep 17 00:00:00 2001 From: Severin Neumann Date: Wed, 4 Sep 2024 09:07:33 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Pablo Baeyens --- projects/registry-data-quality.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/projects/registry-data-quality.md b/projects/registry-data-quality.md index c16e33911..c8b2fb220 100644 --- a/projects/registry-data-quality.md +++ b/projects/registry-data-quality.md @@ -20,11 +20,11 @@ In the last months SIG Comms implemented a set of changes to the registry, to ma - [A JSON schema definition to verify registry entry format](https://github.com/open-telemetry/opentelemetry.io/pull/4805) - [Included the registry in many pages, including the sidebar navigation for all languages and the collector](https://github.com/open-telemetry/opentelemetry.io/pull/3932) -Overall, the registry is in a good shape and is slowly turning into a place that people use for it's original intend. +Overall, the registry is in a good shape and is slowly turning into a place that people use for its original intent. ### Current challenges -While being reworks in incremental steps in the last few months, the registry is still facing a set of challenges, that require a bigger +While being reworked in incremental steps in the last few months, the registry is still facing a set of challenges, that require a bigger review and eventually a collaboration across many SIGs to be addressed: 1. Besides the update of package versions, the maintenance is a manual process: