Adding Status and Releases table to Instrumentation overview page

[kainawroth]

I'm proposing to add a table to the instrumentation overview page which shows the state of development for all telemetry types by language.

---

Preview: https://deploy-preview-1656--opentelemetry.netlify.app/docs/instrumentation/

[linux-foundation-easycla[bot]]

The committers listed above are authorized under a signed CLA.

• :white_check_mark: login: kainawroth / name: Kai Nawroth (f7bf25faf25583f61791ce7c20dc2627e42990ce)

[cartermp]

Hmm. While potentially helpful (both this and the status page get similar request counts as per https://play.honeycomb.io/opentelemetry-web/datasets/opentelemetry.io/result/ba7ffkzuZB7?useStackedGraphs), I think this should link to each page's status anchor instead. We followed that pattern in the new status page: https://opentelemetry.io/status/ - and we ask maintainers to keep their respective status tables up to date when there are relevant changes. This would require them to also make an update elsewhere.

[svrnm]

@cartermp, @chalin: I am wondering if we can capture those status levels in some kind of variables and make them re-usable throughout the pages where we want to show them at a different place as well?

Otherwise, yes, having an anchor to the one place holding the value should be the preferred way.

[chalin]

Let's discuss this during tomorrow's Comms meeting. @austinlparker had voiced some concerns about having such a summary table, but it seems quite useful to me. A data-driven approach might make sense.

[kainawroth]

@kainawroth could you update the table to instead have a link in each entry to the status page for each respective language? This would accomplish the same goal but only require a single place for people to update the canonical status for each SDK.

@cartermp I'm not sure if I understand correctly. You want me to replace each entry (e.g., Stable) with a link to the status page of each respective language? What would the link text be?

I was also wondering if you have an include-extension which would allow you to have only one place to keep updated but reuse the status throughout your whole documentation.

[kainawroth]

@cartermp Following up on my message from last week. Could you please further specify your request, and do you have or have you considered an include-extension?

[cartermp]

Hey, sorry for no reply here. I think for now, it'd be best to just replace each entry in the table with a link to the anchor for each status section in the language index pages.

What would the link text be?

Probably just "Status" for now. It may also be that a table is not the best way to represent the information too, but I'm not married to any particular thing (table, list, etc.)

We did consider an extension, but it would also involve more work since each status section may need to be rewritten to be a fully uniform UI element (e.g., a table without headers) so that it's easy to pull into a bigger UI element (e.g., a full table). That may be something we'd like to do at some point, but probably not in this PR.

[cartermp]

@kainawroth with https://github.com/open-telemetry/opentelemetry.io/blob/main/data/instrumentation.yaml this can now be more data-driven. How would you feel about updating the table to pull in data from here, similar to https://github.com/open-telemetry/opentelemetry.io/pull/1732?

[kainawroth]

@kainawroth with https://github.com/open-telemetry/opentelemetry.io/blob/main/data/instrumentation.yaml this can now be more data-driven. How would you feel about updating the table to pull in data from here, similar to #1732?

This looks great! I'll apply it as soon as I find some time to read into how to pull individual types of telemetry, e.g. {{% lang_instrumentation_index_head "cpp(what goes here to pull the status of C++ traces?)" /%}}.

Any chance you have a good documentation at hand to save me some web searches?

[svrnm]

@kainawroth have a look here: https://gohugo.io/templates/data-templates/

Also give the existing shortcodes a look, that really helps to undertand how you can build something like that, e.g. https://raw.githubusercontent.com/open-telemetry/opentelemetry.io/main/layouts/shortcodes/lang_instrumentation_index_head.md

[svrnm]

Note that https://github.com/open-telemetry/opentelemetry.io/blob/main/data/instrumentation.yaml is now complete, so we can reuse this data.

@kainawroth any plans to continue with this PR?

[kainawroth]

Note that https://github.com/open-telemetry/opentelemetry.io/blob/main/data/instrumentation.yaml is now complete, so we can reuse this data.

@kainawroth any plans to continue with this PR?

@svrnm Yes, I would still want to move forward with it. I was out on vacation and afterwards busy with work, so I didn't find the time yet to read into making this work in a table. The coming weekend, I will make some room to set up a local Hugo site to test shortcodes. Once I get it to work, I'll apply it to this PR.

[svrnm]

@kainawroth any updates?

[kainawroth]

@kainawroth any updates?

I just added the table as a shortcode and referenced it on the Instrumentation page. It's probably not the most elegant solution code-wise, but it worked on my local machine.

[cartermp]

Nice, I like it! If you'd like a final review, feel free to pull this out of a draft.

[kainawroth]

Nice, I like it! If you'd like a final review, feel free to pull this out of a draft.

I was considering adding the sentence "While the OpenTelemetryLoggerProvider (i.e integration with ILogger is stable, the OTLP Log Exporter is still non-stable." below the table to explain Mixed* for .NET Logs but decided not to, since the status might be used for other languages or telemetry types in the future.

Instead, I added a generic "* For more information, see the language-specific instrumentation page."

[kainawroth]

@cartermp I just checked https://opentelemetry.io/docs/instrumentation/ and realized that I forgot to cancel out the asterisk with a backslash to keep markdown from making it a bullet point.

Line 17 in telemetry_support_table.md should be:

\* For more information, see the language-specific instrumentation page.

[cartermp]

sure thing! Lemme patch that up. Thanks again!