Langfuse Dev Service

A service providing Langfuse, an open-source LLM engineering platform for tracing, evaluating, and debugging AI applications, for development and testing purposes. It consists of:

Langfuse for exploring the traces of AI applications, with the worker processing the ingested data.
PostgreSQL, ClickHouse, and Redis as the Langfuse backends.
Floci as the S3-compatible storage for the ingested events and media.

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

Arconia OpenTelemetry.

For Spring AI applications, use it together with the Langfuse Semantic Conventions.

Langfuse accepts traces only, via OTLP with the HTTP/Protobuf protocol. While the Dev Service is active, logs and metrics are not exported.

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-langfuse"
}

<dependency>
    <groupId>io.arconia</groupId>
    <artifactId>arconia-dev-services-langfuse</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.

In test mode, the Dev Service is skipped by default, since most tests have no use for a telemetry backend. For the tests that verify the telemetry the application exports, set arconia.dev.services.langfuse.skip-in-tests to false, preferably in a configuration shared by those tests, such as an application-test.yml file, so that they share one application context and one set of containers (see Dev Services in Test Mode).

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

Starting Langfuse takes longer than most Dev Services, since it runs six containers and applies its database migrations at startup.

Accessing Langfuse

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

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

Sign in with the user created when Langfuse starts: arconia@example.com (email) and password (password). The traces of the application are in the Arconia project.

The application sends its traces to Langfuse authenticated with the API keys of the project, pk-lf-arconia (public key) and sk-lf-arconia (secret key). Use the public-key and secret-key properties to change them.

The Langfuse server closes plaintext HTTP connections that request an upgrade to HTTP/2. The OTLP exporters of Arconia OpenTelemetry send the traces over HTTP/1.1, so no configuration is needed on your side. If you replace the Arconia sender, use one that doesn’t request the upgrade, such as the one based on OkHttp. Learn more about HTTP.

Customizing Langfuse

The organization, project, and user created when Langfuse starts are configured via the Langfuse environment variables, which you can override with the environment property. For example, to sign in with a different user:

arconia:
  dev:
    services:
      langfuse:
        environment:
          LANGFUSE_INIT_USER_EMAIL: me@example.com
          LANGFUSE_INIT_USER_PASSWORD: my-password

Langfuse processes the ingested traces after a delay, which the Dev Service shortens from 15 seconds to 1 second, so that the traces are visible right away. Set the LANGFUSE_INGESTION_QUEUE_DELAY_MS environment variable to change it.

Configuring the Dev Service

You can configure the Dev Service via configuration properties.

Property Default Description

Property	Default	Description
`arconia.dev.services.langfuse.enabled`	`true`	Whether the dev service is enabled.
`arconia.dev.services.langfuse.image-name`	`langfuse/langfuse`	Full name of the container image used in the dev service.
`arconia.dev.services.langfuse.worker-image-name`	`langfuse/langfuse-worker`	Full name of the container image used for the Langfuse worker.
`arconia.dev.services.langfuse.postgres-image-name`	`postgres`	Full name of the container image used for the internal PostgreSQL instance.
`arconia.dev.services.langfuse.clickhouse-image-name`	`clickhouse/clickhouse-server`	Full name of the container image used for the internal ClickHouse instance.
`arconia.dev.services.langfuse.redis-image-name`	`redis`	Full name of the container image used for the internal Redis instance.
`arconia.dev.services.langfuse.floci-image-name`	`floci/floci`	Full name of the container image used for the internal Floci instance, providing the S3-compatible storage.
`arconia.dev.services.langfuse.public-key`	`pk-lf-arconia`	Public key of the API keys of the Langfuse project, used to authenticate the telemetry data sent to Langfuse.
`arconia.dev.services.langfuse.secret-key`	`sk-lf-arconia`	Secret key of the API keys of the Langfuse project, used to authenticate the telemetry data sent to Langfuse.
`arconia.dev.services.langfuse.environment`	`{}`	Environment variables to set in the service.
`arconia.dev.services.langfuse.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.langfuse.port`	`0`	Fixed port for exposing the Langfuse UI and API to the host. When it’s 0 (default), a random available port is assigned dynamically.
`arconia.dev.services.langfuse.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.langfuse.reuse-strategy`	`framework`	Strategy for reusing a running container for the dev service across applications or restarts. Only applicable in dev mode. See Reusing Dev Services.
`arconia.dev.services.langfuse.startup-timeout`	`300s`	Maximum waiting time for the service to start, counted from the container start.
`arconia.dev.services.langfuse.skip-in-tests`	`true`	Whether the dev service is skipped in test mode, where the application rarely needs a telemetry backend. Set it to false for tests that verify the telemetry the application exports.
`arconia.dev.services.langfuse.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.langfuse.enabled

true

Whether the dev service is enabled.

arconia.dev.services.langfuse.image-name

langfuse/langfuse

Full name of the container image used in the dev service.

arconia.dev.services.langfuse.worker-image-name

langfuse/langfuse-worker

Full name of the container image used for the Langfuse worker.

arconia.dev.services.langfuse.postgres-image-name

postgres

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

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

clickhouse/clickhouse-server

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

arconia.dev.services.langfuse.redis-image-name

redis

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

arconia.dev.services.langfuse.floci-image-name

floci/floci

Full name of the container image used for the internal Floci instance, providing the S3-compatible storage.

arconia.dev.services.langfuse.public-key

pk-lf-arconia

Public key of the API keys of the Langfuse project, used to authenticate the telemetry data sent to Langfuse.

arconia.dev.services.langfuse.secret-key

sk-lf-arconia

Secret key of the API keys of the Langfuse project, used to authenticate the telemetry data sent to Langfuse.

arconia.dev.services.langfuse.environment

{}

Environment variables to set in the service.

arconia.dev.services.langfuse.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.langfuse.port

0

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

arconia.dev.services.langfuse.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.langfuse.reuse-strategy

framework

Strategy for reusing a running container for the dev service across applications or restarts. Only applicable in dev mode. See Reusing Dev Services.

arconia.dev.services.langfuse.startup-timeout

300s

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

arconia.dev.services.langfuse.skip-in-tests

true

Whether the dev service is skipped in test mode, where the application rarely needs a telemetry backend. Set it to false for tests that verify the telemetry the application exports.

arconia.dev.services.langfuse.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.

Disabling the Dev Service

Set the arconia.dev.services.langfuse.enabled property to false to disable the Dev Service. To disable it in one mode only, use the profile Arconia activates for that mode (see Profiles), for example in an application-test.yml file to disable it in tests:

arconia:
  dev:
    services:
      langfuse:
        enabled: false

To disable it for a single test class, set the property with @SpringBootTest(properties = …) or @TestPropertySource. To disable all the Dev Services at once, set arconia.dev.services.enabled to false.