The Grafana OpenTelemetry Distribution for Java: Optimized for Application Observability

The OpenTelemetry project provides many different components and instrumentations that support different languages and telemetry signals. However, new users often find it hard to pick the right ones and configure them properly for their specific use cases. For this reason, OpenTelemetry defines the concept of a distribution, which is a tailored and customized version of OpenTelemetry components.

Here at Grafana Labs, we are all-in on OpenTelemetry. That’s why we are excited to announce the public preview of the Grafana OpenTelemetry distributions for Java and .NET. And while these are the first of our OTel distros, they won’t be the last, as we plan to expand our focus to ensure other languages have a great instrumentation experience, too.

In this blog, we’ll focus on our Grafana OpenTelemetry Distribution for Java. We’ll talk about its benefits and our commitment to upstream, and we’ll show you how to get started today. So let’s dive in!

Note: If .NET is your preferred language, check out our companion piece with specific guidance for getting started with the Grafana OpenTelemetry Distribution for .NET.

Why use the Grafana OpenTelemetry distributions?

Our Grafana OpenTelemetry distributions can be used with any OpenTelemetry compatible databases, and they have been optimized for Grafana Cloud Application Observability, our solution for monitoring applications and minimizing mean time to repair (MTTR). They require only minimal setup and configuration and make it very easy to emit telemetry data from your application.

Our distributions:

• Bundle useful instrumentations
• Populate resource attributes and telemetry required for Application Observability
• Allow you to quickly drop telemetry that is not used by Grafana Cloud, thus saving on observability costs

These capabilities allow for a seamless experience while also helping to reduce costs. Furthermore, we test our releases against Grafana Cloud Application Observability to make sure every release is stable and predictable.

In this tutorial, we will show you how to send telemetry directly to Grafana Cloud, bypassing the setup of Grafana Agent or an OpenTelemetry Collector. However, for production uses, we recommend running Grafana Agent or an OpenTelemetry Collector for reliability.

How to get started with the Grafana OpenTelemetry Distribution for Java

You can easily get started with our Java distribution with no changes to the applications. 

Step 1: Download the instrumentation agent

Download the Grafana OpenTelemetry Distribution for Java: grafana-opentelemetry-java.jar.

Step 2: Run the Java application

1. Click Details in the Grafana section on https://grafana.com/profile/org.

2. Copy Instance ID and the last part of Zone into the command below (e.g. prod-eu-west-0 from EU Belgium - gcp europe-west1 - eu - prod-eu-west-0).

3. On the left menu, click on Security, then API Keys.

4. Click on Add API Key (MetricsPublisher role) and copy the key into the command below.

5. Choose a Service Name to identify the service (e.g., cart).

6. Optionally, add attributes to filter data:

   • deployment.environment: Name of the deployment environment (staging or production)
   • service.namespace: A namespace to group similar services (e.g., shop would create shop/cart in Grafana Cloud Application Observability)
   • service.version: The application version, to see if a new version has introduced a bug
   • service.instance.id: The unique instance; for example, the pod name (a UUID is generated by default)

Add the -javaagent option to the Java command with the following environment variables (example Dockerfile):

Copy

export GRAFANA_CLOUD_INSTANCE_ID=<Instance ID>
export GRAFANA_CLOUD_ZONE=<Zone>
export GRAFANA_CLOUD_API_KEY=<Copied API Key>
export OTEL_SERVICE_NAME=<Service Name>
export OTEL_RESOURCE_ATTRIBUTES=deployment.environment=<Environment>,service.namespace=<Namespace>,service.version=<Version>
java -javaagent:path/to/grafana-opentelemetry-java.jar -jar myapp.jar

Finally, make a few requests to the service. This will generate activity and make sure there are no errors sending data to Grafana Cloud. It might take up to five minutes for data to appear.

Step 3: Observe the service in Application Observability in Grafana Cloud

In Grafana, replace the path of the URL with /a/grafana-app-observability-app/services or:

1. Click on the menu icon in the top left corner
2. Open the Observability menu
3. Click on Application

For detailed installation instructions and the troubleshooting guide, refer to the project README.

Committed to upstream OpenTelemetry

While we are launching these Grafana distributions, we are committed to the upstream OpenTelemetry project. Our distributions serve as lightweight wrappers over the upstream OpenTelemetry instrumentation, offering cost controls and easy integration with Grafana Cloud Application Observability. This means you can start with the Grafana distribution, but migrate to upstream OpenTelemetry instrumentations easily if you choose. (For more information, see our Java docs.) This allows you to use the OpenTelemetry APIs, as well as the same knowledge and skills, if you switch to upstream offerings.

Conversely, you can use our distributions with any OpenTelemetry compatible databases and vendors, including Grafana OSS and Grafana Enterprise.

Finally, our aim is to invest in new features upstream before pulling them into our distributions. This benefits the wider community and ensures that all our products work well with the upstream SDKs and not just the Grafana distributions.

Tell us what you think

Chat with us on our Grafana Labs Community Slack channel. To invite yourself to the Grafana Slack, visit https://slack.grafana.com and join the #application-observability channel.

You can also ask questions or file issues for bugs, enhancements, and feature suggestions on the project pages for Java and .NET.

Grafana Cloud is the easiest way to get started with metrics, logs, traces, and dashboards. We have a generous forever-free tier and plans for every use case. Sign up for free now!