Spring Boot

The OpenTelemetry Java agent with byte code instrumentation can cover most of your needs when instrumenting Spring Boot applications.

The OpenTelemetry Spring Boot starter can help you in the following cases:

• with Spring Boot Native image applications for which the OpenTelemetry Java agent does not work
• the startup overhead of the OpenTelemetry Java agent exceeds your requirements
• the OpenTelemetry Java agent might not work if your application already uses another Java monitoring agent

The opentelemetry-java-examples/spring-native repository contains an example of a Spring Boot Native image application instrumented using the OpenTelemetry Spring Boot starter.

The rest of this page documents the OpenTelemetry starter that works with Spring Boot 2.0 and 3.0.

OpenTelemetry Spring starter

Configuration

Dependency management

A Bill of Material (BOM) ensures that versions of dependencies (including transitive ones) are aligned.

Importing the opentelemetry-bom and opentelemetry-instrumentation-bom-alpha BOMs when using the OpenTelemetry starter is important to ensure version alignment across all OpenTelemetry dependencies.

The following example shows how to import both BOMs using Maven:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.opentelemetry</groupId>
            <artifactId>opentelemetry-bom</artifactId>
            <version>1.34.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>io.opentelemetry.instrumentation</groupId>
            <artifactId>opentelemetry-instrumentation-bom-alpha</artifactId>
            <version>2.0.0-alpha</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

With Gradle and Spring Boot, you have two ways to import a BOM.

You can use the Gradle’s native BOM support by adding dependencies:

plugins {
  id("java")
  id("org.springframework.boot") version "3.2.O"
}

dependencies {
  implementation(platform(SpringBootPlugin.BOM_COORDINATES))
  implementation(platform("io.opentelemetry:opentelemetry-bom:1.34.1"))
  implementation(platform("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:2.0.0-alpha"))
}

The other way with Gradle is to use the io.spring.dependency-management plugin and to import the BOMs in dependencyManagement:

plugins {
  id("java")
  id("org.springframework.boot") version "3.2.O"
  id("io.spring.dependency-management") version "1.1.0"
}

dependencyManagement {
  imports {
    mavenBom("io.opentelemetry:opentelemetry-bom:1.34.1")
    mavenBom("io.opentelemetry.instrumentation:opentelemetry-instrumentation-bom-alpha:2.0.0-alpha")
  }
}

OpenTelemetry Starter dependency

Add the dependency given below to enable the OpenTelemetry starter.

The OpenTelemetry starter uses OpenTelemetry Spring Boot autoconfiguration. For details concerning supported libraries and features of the OpenTelemetry autoconfiguration, see the configuration README.

• Maven (pom.xml)
• Gradle (gradle.build)

<dependencies>
	<dependency>
		<groupId>io.opentelemetry.instrumentation</groupId>
		<artifactId>opentelemetry-spring-boot-starter</artifactId>
	</dependency>
</dependencies>

dependencies {
	implementation("io.opentelemetry.instrumentation:opentelemetry-spring-boot-starter")
}

Disable data export

Additional instrumentations

JDBC Instrumentation

You have two ways to enable the JDBC instrumentation with the OpenTelemetry starter.

If your application does not declare DataSource bean, you can update your application.properties file to have the data source URL starting with jdbc:otel: and set the driver class to io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver.

spring.datasource.url=jdbc:otel:h2:mem:db
spring.datasource.driver-class-name=io.opentelemetry.instrumentation.jdbc.OpenTelemetryDriver

You can also wrap the DataSource bean in an io.opentelemetry.instrumentation.jdbc.datasource.OpenTelemetryDataSource:

import io.opentelemetry.instrumentation.jdbc.datasource.JdbcTelemetry;

@Configuration
public class DataSourceConfig {

	@Bean
	public DataSource dataSource(OpenTelemetry openTelemetry) {
		DataSourceBuilder dataSourceBuilder = DataSourceBuilder.create();
		//Data source configurations
		DataSource dataSource = dataSourceBuilder.build();
		return JdbcTelemetry.create(openTelemetry).wrap(dataSource);
	}

}

With the datasource configuration, you need to add the following dependency:

• Maven (pom.xml)
• Gradle (gradle.build)

<dependencies>
	<dependency>
		<groupId>io.opentelemetry.instrumentation</groupId>
		<artifactId>opentelemetry-jdbc</artifactId>
	</dependency>
</dependencies>

dependencies {
	implementation("io.opentelemetry.instrumentation:opentelemetry-jdbc")
}

Logging Instrumentation

To enable the logging instrumentation for Logback you have to add the OpenTelemetry appender in your logback.xml or logback-spring.xml file:

<?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>

For Log4j 2, you have to add the OpenTelemetry appender to your log4j2.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<Configuration status="WARN" packages="io.opentelemetry.instrumentation.log4j.appender.v2_17">
	<Appenders>
		<OpenTelemetry name="OpenTelemetryAppender"/>
	</Appenders>
	<Loggers>
		<Root>
			<AppenderRef ref="OpenTelemetryAppender" level="All"/>
		</Root>
	</Loggers>
</Configuration>

You can find more configuration options for the OpenTelemetry appender in the documentation of the Logback and Log4j instrumentation libraries.

Other Instrumentation

You can configure other instrumentations with OpenTelemetry instrumentations libraries.