OpenTelemetry OpenTelemetry instrumentation 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 with Grafana Agent (for Grafana Cloud or Grafana OSS stack).

Compatibility

Installation

Add the following dependency to your build.gradle (maven):

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

Next, register the OpenTelemetry logback appender in logback-spring.xml (or logback.xml):

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <appender name="console" class="ch.qos.logback.core.ConsoleAppender">
    <encoder>
      <pattern>
        %d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n
      </pattern>
    </encoder>
  </appender>
  <appender name="OpenTelemetry"
            class="io.opentelemetry.instrumentation.logback.appender.v1_0.OpenTelemetryAppender">
  </appender>

  <root level="INFO">
    <appender-ref ref="console"/>
    <appender-ref ref="OpenTelemetry"/>
  </root>
</configuration>

Finally, configure your application.yaml or application.properties either for Grafana Cloud or Grafana Agent.

Grafana Cloud

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

application.yaml:

spring:
  application:
    name: demo-app

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

Grafana Agent

application.yaml:

spring:
  application:
    name: demo-app

• How to configure the Grafana Agent
• Reference of all configuration properties

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

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

Configuration

• 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.

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.)