search

open-telemetry / opentelemetry-specification

Specifications for OpenTelemetry
https://opentelemetry.io
Apache License 2.0
3.69k stars 886 forks source link

Specify the result of `/schemas` URL in the telemetry schema portion of the specification. #3762

Open svrnm opened 10 months ago

svrnm commented 10 months ago

What are you trying to achieve?

Context:

We see many users looking for a page that provides them with a list of available schemas, either because they want to know what the latest version is or they want to create some automation to crawl the list of published schemas and do something with them.

As of today opentelemetry.io/schemas gives a 404.

What did you expect to see?

There are 2 audiences we want to serve:

@chalin proposed that https://opentelemetry.io/schemas/ provides a response based on the HTTP request:

This means, someone who wants a machine readable format would go to:

$ curl -H "Accept: application/json" https://opentelemetry.io/schemas/
... # JSON data response

Someone who wants a human readable format goes to 

$ curl -H "Accept: text/html" https://opentelemetry.io/schemas/
... # HTML data response

As discussed in the SIG SemConv call today, we would like to see this "list of available schemas" being specified and then later implemented by us (@open-telemetry/docs-approvers) on the website.

Ideally this starts with a simple JSON (or YAML?) file that just lists the available schemas + their URL.

Additional context.

We have a proposal for an intermediate solution at https://github.com/open-telemetry/opentelemetry.io/pull/3469, this would still give a 404 but that specific 404-page would contain the information people are looking for.

cc @chalin @jsuereth @MrAlias @tigrannajaryan

chalin commented 10 months ago

@jsuereth et al. - we can generate the machine-reable format (maybe in YAML given that the schemas are in YAML) on the OTel website side, from the list of schemas obtained from the semconv repo. This is now the human-readable list is produced: https://deploy-preview-3508--opentelemetry.netlify.app/schemas/list/

chalin commented 10 months ago

@jsuereth, @tigrannajaryan, @open-telemetry/specs-semconv-approvers, et al. - here's an implementation of the schema list in YAML:

Is this the format you wanted?

svrnm commented 10 months ago

@jsuereth, @tigrannajaryan, @open-telemetry/specs-semconv-approvers, et al. - here's an implementation of the schema list in YAML:

* [Add `/schemas` in YAML, `/schemas/list` in HTML, and a 404 page for the rest opentelemetry.io#3537](https://github.com/open-telemetry/opentelemetry.io/pull/3537)

Is this the format you wanted?

Thanks, @chalin! @open-telemetry/specs-approvers / @open-telemetry/specs-semconv-approvers the current implementation is a basic list with the version numbers (see the PR), so what we need from you are some suggestions what this list should look like:

chalin commented 9 months ago

During today's Spec SIG meeting, @jsuereth kindly offered to champion an OTEP for the addition of the schema-list to the OTel spec. Thanks Josh! Please cc @svrnm and me on the OTEP so that I can track progress, and link to it here.

chalin commented 9 months ago

@tigrannajaryan @jsuereth: it is my understanding that to move forward we need two things:

While it makes sense to have the schema-list format as part of the OTel spec, IMHO, the actual schema-list file needs to live in the semantic-conventions repo along with the schemas that it lists. Does that make sense?

svrnm commented 4 months ago

using the new labelling, @jsuereth I assume that you are the sponsor of this?

svrnm commented 1 month ago

any updates on this?