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 OpenTelemetry/OTLP support available in Spring Boot, you can easily migrate to Arconia OpenTelemetry. This page guides you through the migration process, highlighting the necessary changes to your dependencies, configuration, and code.

Arconia BOM

For starters, include the Arconia BOM to your project.

The current version of Arconia doesn’t support Spring Boot 3.5 any longer. If you want to migrate an existing Spring Boot 3.5 application to using Arconia OpenTelemetry, it’s recommended you first upgrade your application to Spring Boot 4.0 (we provide automations for doing that). If that’s not possible, you can use version 0.20.1 of Arconia, which is the latest one still supporting Spring Boot 3.5.

Gradle
Maven

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

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

Next, follow the instructions based on what version of Spring Boot you’re using.

Spring Boot 4.0

Main Migration

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

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 run \
    --recipe-name io.arconia.rewrite.MigrateSpringBoot4_0_OtlpToArconiaOpenTelemetry

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()
            }
        }
    }

    configurations.named("rewrite") {
        canBeConsumed = false
    }
}

Then, run the following command:

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

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

Spring Boot 3.5

Main Migration

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

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 run \
    --recipe-name io.arconia.rewrite.MigrateSpringBoot3OtlpToArconiaOpenTelemetry

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()
            }
        }
    }

    configurations.named("rewrite") {
        canBeConsumed = false
    }
}

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.