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 3, 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.

  • Gradle

  • Maven

dependencyManagement {
	imports {
		mavenBom "io.arconia:arconia-bom:0.18.2"
	}
}
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.arconia</groupId>
            <artifactId>arconia-bom</artifactId>
            <version>0.18.2</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Main Migration

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. The migration will also add the Arconia OpenTelemetry Spring Boot Starter dependency to your project if not already present, and remove the explicit Micrometer/OpenTelemetry dependencies that are now managed by Arconia and no longer needed.

The OpenRewrite recipe is still experimental and might not cover all possible configurations. Always review the changes made by the recipe to ensure they meet your requirements. Please report any issues you find to help us improve the recipe.

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>

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
            <configuration>
                <includeOptional>false</includeOptional>
            </configuration>
        </plugin>
    </plugins>
</build>

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

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.