This page outlines the docs team's approach to documenting OpenTelemetry examples.
Background
In New Relic documentation for OpenTelemetry (OTel), we provide examples aimed to demonstrate the most common configurations we expect users to use. Historically, the docs site contained these examples on the docs site. However, in May 2024, a joint effort with Relics working on OTel, we decided to migrate these examples from the docs site to the newrelic-opentelemetry-examples repo. For example, here’s a PR where we moved all the infrastructure examples: PR #17742.
Why we support this change
The reasons for this migration are:
- Reduce redundancy across both the repo and docs site: Keeping multiple copies encourages (and almost guarantees) diverging sources of truth and bit rot.
- Make it easier to consume the examples: Writing examples with text, like “Put X content in a file call Y”, is a bad developer experience since it's time consuming and error prone. It's much better to clone a repo, update an environment variable or two, and run a command.
- Emphasis on working code examples for use internally and externally: Internally, the data from these examples are the source of truth on top of which we build product experiences. Externally, these examples are the source of truth on how you do a particular thing with New Relic and OpenTelemetry (stray away from this path and results may vary).
- Reduce maintenance burden: Both the OTel and docs team are small, with a lot of surface area.
How we handle requests for future OTel examples
Going forward, all OTel examples are created and maintained in the newrelic-opentelemetry-examples repo, with a reference mentioned on the docs site.
To propose a new example (per the contribution guidelines), please follow these steps:
- Open an issue for discussion: Before submitting a pull request, open an issue in the newrelic-opentelemetry-examples repository. This allows the OTel team to discuss and ensure your example aligns with the team’s focus areas.
- Demonstrate measurable value: Our focus is on examples that directly translate to user success. Ideally, these will showcase:
- Actionable dashboards: The example should provide a ready-to-use dashboard for visualizing your data.
- Curated experiences: Going beyond dashboards, consider including pre-configured entity synthesis or other elements that enhance the value proposition.