OpenLit Dev Service

A service providing OpenLit, an AI Observability and Evaluation platform based on OpenTelemetry, for development and testing purposes. It consists of:

  • OpenLit for visualizing and exploring telemetry data from AI applications.

  • ClickHouse as the backend database for storing telemetry data.

It works with Spring Boot libraries that support OpenTelemetry, including:

This Dev Service is mutually exclusive with other OpenTelemetry dev services. If more than one is active at the same time, the application will fail at startup with a clear error message. Disable all but one by setting arconia.dev.services.<name>.enabled=false.

Dependencies

First, you need to add the Dev Service dependency to your project.

  • Gradle

  • Maven

dependencies {
  testAndDevelopmentOnly "io.arconia:arconia-dev-services-openlit"
}
<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-dev-services-openlit</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

You can optionally include the Spring Boot DevTools dependency to enable live reload of your application during development.

  • Gradle

  • Maven

dependencies {
  developmentOnly "org.springframework.boot:spring-boot-devtools"
}
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-devtools</artifactId>
    <scope>runtime</scope>
    <optional>true</optional>
</dependency>

When you use the Spring Boot DevTools in your project and run the application in dev mode, Arconia keeps the Dev Services running while you make changes to your code instead of restarting them with the application. This allows you to see the changes in real-time without having to restart the Dev Services. Changes to the configuration of a Dev Service take effect once you stop and start the application again.

Running the Application

When using the Arconia Dev Services, you can keep running your application as you normally would. The Dev Services will automatically start when you run your application.

  • Gradle

  • Maven

  • CLI

./gradlew bootRun
./mvnw spring-boot:run
arconia dev
Unlike the lower-level Testcontainers support in Spring Boot, Arconia doesn’t require special tasks to run your application when using Dev Services (./gradlew bootTestRun or ./mvnw spring-boot:test-run) nor requires you to define a separate @SpringBootApplication class for configuring Testcontainers.

Your integration tests based on @SpringBootTest will automatically use the Dev Services without any additional configuration.

Test slices (e.g. @DataJdbcTest) load only a subset of the auto-configurations, so they don’t pick up Dev Services automatically. You can import the Dev Service explicitly. For example, for the PostgreSQL Dev Service:

@DataJdbcTest
@AutoConfigureTestDatabase(replace = Replace.NONE)
@Import(PostgresqlDevServicesAutoConfiguration.class)
class CustomerRepositoryTests {
    ...
}

By default, when running the application in dev mode, multiple applications running simultaneously use the same OpenLit Dev Service: the application connects to a running OpenLit Dev Service started by another application if available, or else starts its own that other applications can discover in turn. To always start a container for the application alone, set the arconia.dev.services.openlit.reuse-strategy property to none. Learn more about Reusing Dev Services.

Accessing OpenLit

The application logs will show you the URL where you can access the OpenLit UI.

...i.a.d.s.startup  : Dev Service 'openlit' is ready in container <container-id> (ghcr.io/openlit/openlit, reuse-strategy: framework)
...i.a.d.s.startup  : Dev Service 'openlit' links: OpenLit UI: http://localhost:<port>

The service is pre-configured with a demo account which is automatically authenticated when accessing OpenLit the first time. The credentials are: user@openlit.io (username) and openlituser (password).

OpenLit restricts a few operations for the demo account, such as changing the database configuration and deleting API keys or prompts. If you need them, disable the automatic sign-in by setting the DEMO_ACCOUNT_EMAIL environment variable to an empty value and register a new user from the OpenLit login page.

arconia:
  dev:
    services:
      openlit:
        environment:
          DEMO_ACCOUNT_EMAIL: ""

By default, logs, metrics, and traces are exported via OTLP using the HTTP/Protobuf format.

Configuring the Dev Service

You can configure the Dev Service via configuration properties.

Property Default Description

arconia.dev.services.openlit.enabled

true

Whether the dev service is enabled.

arconia.dev.services.openlit.image-name

ghcr.io/openlit/openlit

Full name of the container image used for OpenLit.

arconia.dev.services.openlit.clickhouse-image-name

clickhouse/clickhouse-server

Full name of the container image used for the internal ClickHouse instance.

arconia.dev.services.openlit.environment

{}

Environment variables to set in the service.

arconia.dev.services.openlit.network-aliases

[]

Additional hostnames the dev service container is reachable by on the shared network, next to the name of the dev service. Only applicable when the shared network is enabled.

arconia.dev.services.openlit.port

0

Fixed port for exposing the OpenLit UI port to the host. When it’s 0 (default), a random available port is assigned dynamically.

arconia.dev.services.openlit.resources

[]

Resources from the classpath or host filesystem to copy into the container. They can be files or directories that will be copied to the specified destination path inside the container at startup and are immutable (read-only).

arconia.dev.services.openlit.reuse-strategy

framework

Strategy for reusing a running container for the dev service instead of starting a new one. With framework, the dev service is discoverable by other applications, and the application connects to an existing dev service if available. With testcontainers, the container is kept running across application restarts, relying on the Testcontainers reusable containers feature, which must be enabled in the ~/.testcontainers.properties file; such containers are not stopped automatically and must be cleaned up manually. Only applicable in dev mode.

arconia.dev.services.openlit.startup-timeout

120s

Maximum waiting time for the service to start, counted from the container start.

arconia.dev.services.openlit.volumes

[]

Files or directories to mount from the host filesystem into the container. They are mounted at the specified destination path inside the container at startup and are mutable (read-write). Changes in either the host or the container will be immediately reflected in the other.

arconia.dev.services.openlit.otlp-grpc-port

0

Fixed port for exposing the OTLP gRPC port to the host. When it’s 0 (default), a random available port is assigned dynamically.

arconia.dev.services.openlit.otlp-http-port

0

Fixed port for exposing the OTLP HTTP port to the host. When it’s 0 (default), a random available port is assigned dynamically.

You can enable/disable the Dev Service selectively for a specific application mode (development, test), relying on one of the profiles which are automatically configured by Arconia (see Profiles).

You can enable/disable the Dev Service for a specific test class by using the @TestPropertySource annotation or equivalent Spring testing utilities.