OpenTelemetry Instrumentation Java Grafana OpenTelemetry Starter

Automatic Instrumentation of Spring Boot 3.x Applications with Grafana OpenTelemetry Starter

The grafana-opentelemetry-starter makes it easy to use Metrics, Traces, and Logs with OpenTelemetry in Grafana Cloud or the Grafana OSS stack.

Compatibility

Logging is supported with Logback and Log4j2 (a separate appender is added automatically, leaving your console or file appenders untouched).

Getting Started

Look for the most recent version of grafana-opentelemetry-starter and add it to your build.gradle

groovy

implementation 'com.grafana:grafana-opentelemetry-starter:1.3.1'

… or pom.xml

xml

<dependency>
    <groupId>com.grafana</groupId>
    <artifactId>grafana-opentelemetry-starter</artifactId>
    <version>1.3.1</version>
</dependency>

Configuration

Finally, configure your application.yaml (or application.properties) either for Grafana Cloud OTLP Gateway or Grafana Agent.

Grafana Cloud OTLP Gateway

⚠️ Please use the Grafana Agent configuration for production use cases.

The easiest setup is to use the Grafana Cloud OTLP Gateway, because you don’t need to run any service to transport the telemetry data to Grafana Cloud. The Grafana Cloud OTLP Gateway is a managed service that is available in all Grafana Cloud plans.

If you’re just getting started with Grafana Cloud, you can sign up for permanent free plan.

1. Click on “Details” button in the “Grafana” section on your Grafana Cloud account
2. Copy “Instance ID” and “Zone” into the application.yaml below
3. On the left side, click on “Security” and then on “API Keys”
4. Click on “Create API Key” (MetricsPublisher role) and copy the key into the application.yaml below

application.yaml:

yaml

spring:
  application:
    name: demo-app

grafana:
  otlp:
    cloud:
      zone: <Grafana Zone>
      instanceId: <Grafana Instance ID>
      apiKey: <Grafana API key>

Grafana Agent

The Grafana Agent is a single binary that can be deployed as a sidecar or daemonset in Kubernetes, or as a service in your network. It provides an endpoint where the application can send its telemetry data to. The telemetry data is then forwarded to Grafana Cloud or a Grafana OSS stack.

application.yaml:

yaml

spring:
  application:
    name: demo-app

• How to configure the Grafana Agent
• Refer to the Properties section for details about configuration properties

If you have changed the configuration of the Grafana Agent, you can specify the endpoint and protocol explicitly. This example uses the default values - it is equivalent to the example above:

yaml

spring:
  application:
    name: demo-app
grafana:
  otlp:
    onprem:
      endpoint: http://localhost:4317
      protocol: grpc

Grafana Dashboard

Once you’ve started your application, you can use this Spring Boot Dashboard

Getting Help

If anything is not working, or you have questions about the starter, we’re glad to help you on our community chat (#opentelemetry).

Reference

• All configuration properties are described in the reference.
• The grafana.otlp.cloud and grafana.otlp.onprem properties are mutually exclusive.
• As usual in Spring Boot, you can use environment variables to supply some of the properties, which is especially useful for secrets, e.g. GRAFANA_OTLP_CLOUD_API_KEY instead of grafana.otlp.cloud.apiKey.
• In addition, you can use all system properties or environment variables from the SDK auto-configuration - which will take precedence.

Troubleshooting

When you start the application, you will also get a log output of the configuration properties as they are translated into SDK properties.

For example, if you set the spring.application.name in application.yaml, you will get the following log output:

11:53:07.724 [main] INFO  c.g.o.OpenTelemetryConfig - using config properties: {otel.exporter.otlp.endpoint=https://otlp-gateway-prod-eu-west-0.grafana.net/otlp, otel.logs.exporter=otlp, otel.traces.exporter=otlp, otel.exporter.otlp.headers=Authorization=Basic NTUz..., otel.exporter.otlp.protocol=http/protobuf, otel.resource.attributes=service.name=demo-app, otel.metrics.exporter=otlp}

(The otel.exporter.otlp.headers field is abbreviated for security reasons.)

If you still don’t see your logs, traces and metrics in Grafana, even though the configuration looks good, you can turn on debug logging to what data the application is emitting.