Back to Guides
このページを編集

Observability Dev Services with Grafana OTel LGTM

この Dev Service は、 Grafana OTel-LGTM を提供します。これは、テレメトリーデータを受信して Prometheus (メトリクス)、Tempo (トレース)、および Loki (ログ) に転送する OpenTelemetry Collector を含む all-in-one Docker イメージです。 このデータは、 Grafana で視覚化できます。LGTM という略語は次の意味です。

  • L → Loki (ログ)

  • G → Grafana (メトリクスの可視化)

  • T → Tempo (トレース)

  • M → Mimir (Prometheus の長期保存)

プロジェクトの設定

If you are using quarkus-opentelemetry or quarkus-micrometer-opentelemetry this Observability extension is already bundled and the container will start automatically in dev mode.

If the mentioned extensions are not present, you can manually add the Quarkus Grafana OTel LGTM sink (where data goes) extension to your build file:

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-observability-devservices-lgtm</artifactId>
    <scope>provided</scope>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-observability-devservices-lgtm")

Micrometer

Micrometer Quarkus エクステンション は、Quarkus とそのエクステンションに実装された自動計装からのメトリクスを提供します。

Micrometer メトリクスを出力する方法は複数あります。次にいくつか例を示します。

Micrometer Prometheus レジストリーの使用

これは、Micrometer からメトリクスを出力する最も一般的な方法であり、Quarkus のデフォルトの方法です。Micrometer Prometheus レジストリーは、 /q/metrics エンドポイントでデータを公開し、Grafana LGTM Dev Service 内のスクレイパーがデータを取得します (サービスからデータを プル します)。

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-registry-prometheus</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-micrometer-registry-prometheus")

Micrometer OTLP レジストリーの使用

Quarkiverse Micrometer OTLP レジストリー は、OpenTelemetry OTLP プロトコルを使用してデータを Grafana LGTM Dev Service に出力します。これにより、データがサービスから プッシュ されます。

pom.xml
<dependency>
    <groupId>io.quarkiverse.micrometer.registry</groupId>
    <artifactId>quarkus-micrometer-registry-otlp</artifactId>
</dependency>
build.gradle
implementation("io.quarkiverse.micrometer.registry:quarkus-micrometer-registry-otlp")

Micrometer の Quarkiverse OTLP レジストリーを使用してメトリクスを Grafana OTel LGTM にプッシュする場合、Docker コンテナーの外部から見える OTel コレクターエンドポイントに quarkus.micrometer.export.otlp.url プロパティーが自動的に設定されます。

OpenTelemetry

OpenTelemetry を使用すると、メトリクス、トレース、ログを作成し、Grafana LGTM Dev Service に送信できます。

デフォルトでは、 OpenTelemetry エクステンション は トレース を生成します。 メトリクス と ログ は個別に有効にする必要があります。

quarkus-opentelemetry エクステンションは、次のようにビルドファイルに追加できます。

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-opentelemetry</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-opentelemetry")

quarkus.otel.exporter.otlp.endpoint プロパティーは、Docker コンテナーの外部から見える OTel コレクターエンドポイントに自動的に設定されます。

quarkus.otel.exporter.otlp.protocol は http/protobuf に設定されています。

Micrometer から OpenTelemetry へのブリッジ

このエクステンションは、Micrometer メトリクスと OpenTelemetry メトリクス、トレース、およびログを提供します。データはすべて OpenTelemetry エクステンションによって管理され、送信されます。

すべてのシグナルがデフォルトで有効になります。

エクステンションは次のようにビルドファイルに追加できます。

pom.xml
<dependency>
    <groupId>io.quarkus</groupId>
    <artifactId>quarkus-micrometer-opentelemetry</artifactId>
</dependency>
build.gradle
implementation("io.quarkus:quarkus-micrometer-opentelemetry")

Grafana

Grafana UI へのアクセス

アプリケーションを開発モードで起動します。

CLI
quarkus dev
Maven
./mvnw quarkus:dev
Gradle
./gradlew --console=plain quarkusDev

次のようなログエントリーが表示されます。

[io.qu.ob.de.ObservabilityDevServiceProcessor] (build-35) Dev Service Lgtm started, config: {grafana.endpoint=http://localhost:42797, prometheus.endpoint=http://localhost:39090, tempo-mcp.endpoint=http://localhost:43200, quarkus.otel.exporter.otlp.endpoint=http://localhost:34711, otel-collector.url=localhost:34711, quarkus.micrometer.export.otlp.url=http://localhost:34711/v1/metrics, quarkus.otel.exporter.otlp.protocol=http/protobuf}

Grafana はエフェメラルポートでアクセス可能であるため、どのポートが使用されているかを確認するにはログを確認する必要があります。この例では、Grafana エンドポイントは grafana.endpoint=http://localhost:42797 です。

もう 1 つの方法は、Dev UI (http://localhost:8080/q/dev-ui/extensions) を使用することです。Grafana URL リンクが使用可能になり、選択すると、実行中の Grafana インスタンスに直接新しいブラウザータブが開きます。

Dev UI LGTM

探索

Explore セクションでは、すべてのデータソースのデータをクエリーできます。

トレースを表示するには、 tempo データソースを選択し、データをクエリーします。

Dev UI LGTM

ログの場合は、 loki データソースを選択し、データをクエリーします。

Dev UI LGTM

ダッシュボード

Dev Service にはダッシュボードのセットが含まれています。

Dev UI LGTM

各ダッシュボードは、特定のアプリケーション設定に合わせて調整されています。使用可能なダッシュボードは次のとおりです。

  • Quarkus Micrometer OpenTelemetry: Micrometer および OpenTelemetry エクステンションで使用されます。

  • Quarkus Micrometer OTLP registry: Micrometer OTLP レジストリーエクステンションで使用されます。

  • Quarkus Micrometer Prometheus registry: Micrometer Prometheus レジストリーエクステンションで使用されます。

  • Quarkus OpenTelemetry Logging: OpenTelemetry エクステンションからのログを表示します。

ダッシュボードの一部のパネルでは、値がスライディングタイムウィンドウにわたって計算される場合、正確なデータが表示されるまでに数分かかることがあります。

カスタムダッシュボード

ユーザーは独自のGrafanaダッシュボードと独自の構成を追加できます。grafana-dashboard-[your name].json ファイルをアプリケーションの META-INF/grafana ディレクトリーに配置すると、LGTM Dev Services が自動的にそれを検出し、このダッシュボード構成を全体のGrafanaダッシュボード YAML 構成に含めます。

例えば、/META-INF/grafana/grafana-dashboard-my-simple-prometheus-dashboard.json 構成ファイルは、My Simple Prometheus Dashboard という名前のダッシュボードを作成します。

追加設定

このエクステンションは、Grafana OTel LGTM イメージにバンドルされている OTel Collector にデータを送信するために、 quarkus-opentelemetry および quarkus-micrometer-registry-otlp エクステンションを設定します。

Dev Services に関する面倒な作業 (既存の実行中のコンテナーの検索や再利用など) を避ける場合は、Dev Services を無効にして、Dev Resource の使用のみを有効にすることができます。

quarkus.observability.enabled=false
quarkus.observability.dev-resources=true

デフォルトでは、Quarkus は Testcontainers に Grafana と OTel のランダムなポートを公開させますが、ポートを自分で設定することで、ユーザー側で固定ポートを使用するように強制できます。ただし、その場合はポート競合に注意してください。

quarkus.observability.lgtm.grafana-port=3001
quarkus.observability.lgtm.otel-grpc-port=5317
quarkus.observability.lgtm.otel-http-port=5318

内部コンテナーポートは同じままです。例: Grafana は 3000、OTel gRPC は 4317、OTel HTTP は 4318 など。

Disabling observability Dev Services

Observability Dev Services are enabled by default in dev mode. To disable them entirely (both in dev and test mode), preventing the Grafana LGTM container from starting automatically, set:

quarkus.observability.enabled=false

This also disables the Dev UI card, the shared container discovery, compose support and the OpenTelemetry override properties.

Automatic detection of explicit OTLP endpoint configuration

LGTM Dev Services will not start if an OTLP exporter endpoint is already explicitly configured. This prevents the Dev Service from overriding a custom collector (e.g. a Jaeger or Zipkin instance) that has been intentionally set by the user.

The following properties are checked, depending on which extensions are present:

エクステンション Property checked

quarkus-opentelemetry

quarkus.otel.exporter.otlp.endpoint

quarkus-opentelemetry

quarkus.otel.exporter.otlp.traces.endpoint

quarkus-opentelemetry

quarkus.otel.exporter.otlp.metrics.endpoint

quarkus-opentelemetry

quarkus.otel.exporter.otlp.logs.endpoint

quarkus-micrometer-registry-otlp

quarkus.micrometer.export.otlp.url

If any of those properties is explicitly set, the following log entry will appear and LGTM will not start:

Not starting LGTM Dev Services: 'quarkus.otel.exporter.otlp.traces.endpoint' is explicitly configured.

If you need a custom endpoint in production but still want LGTM to start in dev mode, scope the property to the production profile so that it is invisible to the dev mode config:

%prod.quarkus.otel.exporter.otlp.traces.endpoint=http://my-collector:4318

Enabling observability Dev Services in tests

By default, observability Dev Services do not start in test mode. To enable the Grafana LGTM container during tests, set:

quarkus.observability.enabled-in-tests=true

This property has no effect in dev mode, where Dev Services are controlled solely by quarkus.observability.enabled.

For the least 'auto-magical' usage in the tests, you can explicitly list LGTM Dev Resource in the test as a @QuarkusTestResource resource:

@QuarkusTest
@QuarkusTestResource(value = LgtmResource.class, restrictToAnnotatedClass = true)
@TestProfile(QuarkusTestResourceTestProfile.class)
public class LgtmLifecycleTest extends LgtmTestBase {
}

Dev Resources mode

As an alternative to full Dev Services, you can enable a simplified Dev Resources mode. In this mode, containers are started lazily at runtime via a MicroProfile ConfigSource instead of during the build phase. This means there is no shared container discovery, no compose support, no Dev UI card and no OpenTelemetry override properties injected.

quarkus.observability.enabled=false
quarkus.observability.dev-resources=true

quarkus.observability.enabled must be set to false when using Dev Resources mode. The two modes are mutually exclusive.

MCP integration for AI tools

The LGTM Dev Service supports the Model Context Protocol (MCP), allowing AI coding tools like Claude Code and Cursor to query telemetry data directly from the running container.

Two MCP pathways are available:

Component MCP Server Transport Capability

Grafana

uvx mcp-grafana (runs on host)

stdio

Dashboards, PromQL, LogQL

Tempo

Built-in HTTP endpoint

HTTP

Traces via TraceQL

Tempo MCP

The Tempo MCP server is automatically enabled and exposes an HTTP endpoint at port 3200 (/api/mcp).

You can fix the Tempo MCP port if needed:

quarkus.observability.lgtm.tempo-mcp-port=3200

The mapped endpoint is available as the tempo-mcp.endpoint config property:

@ConfigProperty(name = "tempo-mcp.endpoint")
String tempoMcpEndpoint; // e.g. http://localhost:45678

To add the Tempo MCP server to Claude Code, use the endpoint from the Dev Service startup log:

claude mcp add --transport http tempo <tempo-mcp.endpoint>/api/mcp

Grafana MCP

The Grafana MCP server runs as a client-side process on the host using uvx mcp-grafana and connects to the Grafana instance inside the container. It provides access to dashboards, PromQL queries (metrics), and LogQL queries (logs).

The mapped Grafana endpoint is available as the grafana.endpoint config property:

@ConfigProperty(name = "grafana.endpoint")
String grafanaEndpoint; // e.g. http://localhost:42797

After the container starts, a Grafana service account token is automatically created inside the container at /tmp/grafana-sa-token. You can retrieve it and the full MCP configuration:

# Find the container name
docker ps --filter "label=quarkus-dev-service=lgtm" --format '{{.Names}}'

# Retrieve the service account token
TOKEN=$(docker exec <container-name> cat /tmp/grafana-sa-token)

# Retrieve the full MCP configuration JSON
docker exec <container-name> cat /etc/lgtm/mcp.json

To add the Grafana MCP server to Claude Code (requires uvx), use the grafana.endpoint URL from the Dev Service startup log:

claude mcp add grafana \
  -e GRAFANA_URL=<grafana.endpoint> \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN="$TOKEN" \
  -- uvx mcp-grafana

The Grafana MCP server also proxies the Tempo MCP server, so adding both is optional. Tempo’s standalone endpoint is useful when you only need trace queries without the full Grafana integration.

Exposed backend endpoints

In addition to the Grafana, Tempo MCP, and OTel Collector endpoints, the Dev Service also exposes the Prometheus HTTP API directly. This is useful for querying metrics programmatically without going through Grafana:

@ConfigProperty(name = "prometheus.endpoint")
String prometheusEndpoint; // e.g. http://localhost:39090

The full list of exposed endpoints:

Config property 説明

grafana.endpoint

Grafana UI and API

prometheus.endpoint

Prometheus HTTP API (e.g. /api/v1/query)

tempo-mcp.endpoint

Tempo query-frontend (search API and MCP)

otel-collector.url

OpenTelemetry Collector (gRPC or HTTP, depending on otlp-protocol)

Container component logging

You can enable container log output for individual LGTM components by setting the logging property. This maps to the ENABLE_LOGS_* environment variables in the container.

quarkus.observability.lgtm.logging=TEMPO,OTELCOL

Available components: GRAFANA, LOKI, PROMETHEUS, TEMPO, PYROSCOPE, OTELCOL, OBI, ALL.

Shutdown timeout

The container forwards SIGTERM and SIGINT to every backend and waits for a graceful shutdown. By default the timeout is 5 seconds. You can override it:

quarkus.observability.lgtm.shutdown-timeout=15

OBI (eBPF auto-instrumentation)

OBI (OpenTelemetry eBPF Instrumentation) automatically generates traces and RED metrics for HTTP/gRPC services without code changes. It requires Linux kernel 5.8+ with BTF support.

When enabled, the container is started with --pid=host and --privileged flags.

quarkus.observability.lgtm.enable-obi=true
quarkus.observability.lgtm.obi-target=java

Additional OBI targeting options:

プロパティー 説明

quarkus.observability.lgtm.obi-target

Language (java, python, node, dotnet, ruby) or any regex matching an executable name

quarkus.observability.lgtm.obi-open-port

Override which ports OBI monitors (e.g. 8080,9090)

quarkus.observability.lgtm.obi-auto-target-exe

Executable name pattern for targeting

Customize backend configuration

Extra CLI arguments

Each backend supports extra CLI arguments appended at startup. The value is split on whitespace into separate arguments.

quarkus.observability.lgtm.prometheus-extra-args=--storage.tsdb.retention.time=90d
quarkus.observability.lgtm.loki-extra-args=-store.retention=90d
quarkus.observability.lgtm.tempo-extra-args=--additional-flag=value
quarkus.observability.lgtm.pyroscope-extra-args=--some-flag
quarkus.observability.lgtm.otelcol-extra-args=--some-flag

Tempo always includes --query-frontend.mcp-server.enabled=true by default. Any value set via tempo-extra-args is appended after this flag.

Custom configuration files

For deeper customization, you can mount full configuration files from the classpath into the container. Place your custom YAML file in src/main/resources/ and reference it:

quarkus.observability.lgtm.prometheus-config=my-prometheus.yaml
quarkus.observability.lgtm.loki-config=my-loki-config.yaml
quarkus.observability.lgtm.tempo-config=my-tempo-config.yaml
quarkus.observability.lgtm.pyroscope-config=my-pyroscope-config.yaml
quarkus.observability.lgtm.otelcol-config=my-otelcol-config.yaml
プロパティー Container path

prometheus-config

/otel-lgtm/prometheus.yaml

loki-config

/otel-lgtm/loki-config.yaml

tempo-config

/otel-lgtm/tempo-config.yaml

pyroscope-config

/otel-lgtm/pyroscope-config.yaml

otelcol-config

/otel-lgtm/otelcol-config.yaml

When a custom prometheus-config is provided, it replaces the Prometheus configuration that Quarkus generates (including scraping configuration). The other backends have no generated configuration, so the custom file simply replaces the container defaults.

Pre-install Grafana plugins

You can pre-install Grafana plugins by setting a comma-separated list:

quarkus.observability.lgtm.grafana-plugins-preinstall=grafana-clock-panel,grafana-simple-json-datasource

See the Grafana documentation for details on available plugins.

Custom Grafana home dashboard

To set a custom dashboard as the Grafana home dashboard, point to a dashboard JSON file path inside the container. This is useful in combination with [Custom dashboards] which are copied to /otel-lgtm/:

quarkus.observability.lgtm.grafana-home-dashboard-path=/otel-lgtm/grafana-dashboard-my-home.json

Forward telemetry to external vendors

The built-in OpenTelemetry Collector can forward telemetry data to external backends via OTLP/HTTP, enabling easy comparison between the local LGTM stack and a vendor backend.

quarkus.observability.lgtm.vendor-otlp-endpoint=https://otlp-gateway.example.com
quarkus.observability.lgtm.vendor-otlp-headers=Authorization=Basic xxx

Per-signal endpoints take precedence over the global endpoint:

quarkus.observability.lgtm.vendor-otlp-logs-endpoint=https://logs.example.com
quarkus.observability.lgtm.vendor-otlp-metrics-endpoint=https://metrics.example.com
quarkus.observability.lgtm.vendor-otlp-traces-endpoint=https://traces.example.com

完全な Grafana OTel LGTM スタックのテスト - 例

既存の Quarkus MicroMeter OTLP レジストリーの使用

pom.xml
<dependency>
    <groupId>io.quarkiverse.micrometer.registry</groupId>
    <artifactId>quarkus-micrometer-registry-otlp</artifactId>
</dependency>
build.gradle
implementation("io.quarkiverse.micrometer.registry:quarkus-micrometer-registry-otlp")

Meter レジストリーをコードに注入するだけで、メトリクスが Grafana LGTM の OTLP HTTP エンドポイントに定期的にプッシュされるようになります。

@Path("/api")
public class SimpleEndpoint {
    private static final Logger log = Logger.getLogger(SimpleEndpoint.class);

    @Inject
    MeterRegistry registry;

    @PostConstruct
    public void start() {
        Gauge.builder("xvalue", arr, a -> arr[0])
                .baseUnit("X")
                .description("Some random x")
                .tag("my_key", "x")
                .register(registry);
    }

    // ...
}

Where you can then check Prometheus for existing metrics data, using the exposed prometheus.endpoint:

public class LgtmTestBase {

    @ConfigProperty(name = "grafana.endpoint")
    String endpoint; // NOTE -- injected Grafana endpoint!

    @ConfigProperty(name = "prometheus.endpoint")
    String prometheusEndpoint; // NOTE -- injected Prometheus endpoint!

    @Test
    public void testTracing() {
        String response = RestAssured.get("/api/poke?f=100").body().asString();
        System.out.println(response);
        GrafanaClient client = new GrafanaClient(endpoint, prometheusEndpoint, null, "admin", "admin");
        Awaitility.await().atMost(61, TimeUnit.SECONDS).until(
                client::user,
                u -> "admin".equals(u.login));
        Awaitility.await().atMost(61, TimeUnit.SECONDS).until(
                () -> client.query("xvalue_X"),
                result -> !result.data.result.isEmpty());
    }

}

Quarkus is open. All dependencies of this project are available under the Apache Software License 2.0 or compatible license. CC by 3.0

This website was built with Roq on Quarkus, is hosted on GitHub Pages and is completely open source. If you want to make it better, fork the website and show us what you’ve got.

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
Copyright © Quarkus. All rights reserved. For details on our trademarks, please visit our Trademark Policy and Trademark List. Trademarks of third parties are owned by their respective holders and their mention here does not suggest any endorsement or association.