Migrating from Spring Boot OpenTelemetry/OTLP to Arconia OpenTelemetry

Arconia provides unified observability for Spring Boot applications, combining full support for OpenTelemetry API, SDK, and Instrumentation while also providing a seamless integration with Micrometer API and Instrumentation. The goal is to provide a single, unified observability solution for Spring Boot applications that can give you the best of both worlds: the standardization and ubiquity of OpenTelemetry and the robustness and stability of Micrometer.

If you’re currently relying on the partial OpenTelemetry/OTLP support available in Spring Boot, you can easily migrate to Arconia OpenTelemetry and benefit from the full OpenTelemetry API, SDK, and Instrumentation support while also maintaining full support for Micrometer API and Instrumentation.

Dependencies

For starters, include the Arconia OpenTelemetry Spring Boot Starter dependency to your project.

Gradle
Maven

dependencies {
    implementation 'io.arconia:arconia-opentelemetry-spring-boot-starter'
}

dependencyManagement {
	imports {
		mavenBom "io.arconia:arconia-bom:0.14.1"
	}
}

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

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.arconia</groupId>
            <artifactId>arconia-bom</artifactId>
            <version>0.14.1</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Next, you can remove the dependencies you previously used to bring OpenTelemetry support to your Spring Boot application, including the following.

Dependency Why Remove

Dependency	Why Remove
`org.springframework.boot:spring-boot-starter-actuator`	Managed by Arconia OpenTelemetry Spring Boot Starter.
`io.micrometer:micrometer-registry-otlp`	Replaced by the OpenTelemetry SDK-based exporter in Arconia OpenTelemetry Spring Boot Starter.
`io.micrometer:micrometer-tracing-bridge-otel`	Managed by Arconia OpenTelemetry Spring Boot Starter.
`io.opentelemetry:opentelemetry-api`	Managed by Arconia OpenTelemetry Spring Boot Starter.
`io.opentelemetry:opentelemetry-exporter-otlp`	Managed by Arconia OpenTelemetry Spring Boot Starter.
`io.opentelemetry.instrumentation:opentelemetry-logback-appender`	Managed by Arconia OpenTelemetry Spring Boot Starter.
`io.opentelemetry.instrumentation:opentelemetry-micrometer`	Managed by Arconia OpenTelemetry Spring Boot Starter.

org.springframework.boot:spring-boot-starter-actuator

Managed by Arconia OpenTelemetry Spring Boot Starter.

io.micrometer:micrometer-registry-otlp

Replaced by the OpenTelemetry SDK-based exporter in Arconia OpenTelemetry Spring Boot Starter.

io.micrometer:micrometer-tracing-bridge-otel

Managed by Arconia OpenTelemetry Spring Boot Starter.

io.opentelemetry:opentelemetry-api

Managed by Arconia OpenTelemetry Spring Boot Starter.

io.opentelemetry:opentelemetry-exporter-otlp

Managed by Arconia OpenTelemetry Spring Boot Starter.

io.opentelemetry.instrumentation:opentelemetry-logback-appender

Managed by Arconia OpenTelemetry Spring Boot Starter.

io.opentelemetry.instrumentation:opentelemetry-micrometer

Managed by Arconia OpenTelemetry Spring Boot Starter.

Configuration

Spring Boot provides partial support for the OpenTelemetry SDK, including basic autoconfiguration for logs and traces. It also includes an OTLP-compatible exporter for metrics provided by Micrometer.

To ease the migration, Arconia provides an automated OpenRewrite recipe that you can run to convert your existing Spring Boot OpenTelemetry configuration (properties and beans) to the Arconia OpenTelemetry configuration properties.

If you customized the Micrometer OTLP exporter via code, that same code will not work with Arconia OpenTelemetry because the Micrometer OTLP project is not based on the OpenTelemetry API. You can apply equivalent changes directly against the OpenTelemetry API.

There are three ways you can run the migration recipe: Arconia CLI, Gradle OpenRewrite Plugin, or Maven OpenRewrite Plugin.

Arconia CLI

Using the Arconia CLI, you can run the migration recipe as follows:

arconia rewrite \
    --recipe-name io.arconia.rewrite.MigrateSpringBoot3OtlpToArconiaOpenTelemetry \
    --recipe-library io.arconia.migrations:rewrite-arconia

Gradle OpenRewrite Plugin

Using the OpenRewrite Gradle Plugin, you can apply the recipe to your project as follows.

First, create an init.gradle file in your Spring Boot project (root folder) with the following content:

initscript {
    repositories {
        maven { url "https://plugins.gradle.org/m2" }
    }
    dependencies {
        classpath("org.openrewrite:plugin:latest.release")
    }
}

rootProject {
    plugins.apply(org.openrewrite.gradle.RewritePlugin)
    dependencies {
        rewrite("io.arconia.migrations:rewrite-arconia:latest.release")
    }

    afterEvaluate {
        if (repositories.isEmpty()) {
            repositories {
                mavenCentral()
            }
        }
    }
}

Then, run the following command:

./gradlew rewriteRun \
    --init-script init.gradle \
    -DactiveRecipe=io.arconia.rewrite.MigrateSpringBoot3OtlpToArconiaOpenTelemetry

Finally, you can remove the init.gradle file.

Maven OpenRewrite Plugin

Using the OpenRewrite Maven Plugin, you can apply the recipe to your project as follows:

./mvnw -U org.openrewrite.maven:rewrite-maven-plugin:run \
  -Drewrite.recipeArtifactCoordinates=io.arconia.migrations:rewrite-arconia:LATEST \
  -Drewrite.activeRecipes=io.arconia.rewrite.MigrateSpringBoot3OtlpToArconiaOpenTelemetry

Dev Services

If you’re using the Grafana LGTM Testcontainers support in Spring Boot to run a full Grafana observability platform based on OpenTelemetry at development and test time, you can migrate that to the more powerful Arconia Grafana LGTM Dev Service.

First, include the Arconia Grafana LGTM Dev Service dependency to your project.

Gradle
Maven

dependencies {
    testAndDevelopmentOnly "io.arconia:arconia-dev-services-lgtm"
}

<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-dev-services-lgtm</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

Next, you can remove the dependencies you previously used to bring Grafana Testcontainers support to your Spring Boot application, including the following.

Dependency Why Remove

Dependency	Why Remove
`org.springframework.boot:spring-boot-testcontainers`	Managed by Arconia OpenTelemetry Spring Boot Starter.
`org.testcontainers:grafana`	Managed by Arconia OpenTelemetry Spring Boot Starter.

org.springframework.boot:spring-boot-testcontainers

Managed by Arconia OpenTelemetry Spring Boot Starter.

org.testcontainers:grafana

Managed by Arconia OpenTelemetry Spring Boot Starter.

Arconia Dev Services requires no additional configuration or code (e.g. a separate @SpringBootApplication class for configuring Testcontainers). You can therefore remove the Testcontainers configuration you previously added to your test classpath and related Spring Boot application entry point from the test classpath.

Arconia Dev Services are also transparent to the user, meaning that you don’t need to change your development workflow to use it. If you were previously launching the application in development from ./gradlew bootTestRun or ./mvnw spring-boot:test-run, you can drop the special command and run your application as usual: ./gradlew bootRun or ./mvnw spring-boot:run. Furthermore, your integration tests will automatically benefit from the Arconia Dev Services without any additional configuration.

You can keep using other dev services as provided by Spring Boot without conflicts. Arconia Dev Services are designed to be transparent and non-intrusive.