Getting Started

Prerequisites

  • JDK 21+

  • Maven 3.9+ (or use the included mvnw wrapper)

  • Docker (for LGTM stack via Dev Services)

  • uvx — used to run the mcp-grafana MCP server (pip install uv or brew install uv)

  • API key for at least one LLM provider (OpenAI or Grok)

Quick Start

The fastest way to get started is running the AI module in dev mode. Quarkus Dev Services automatically starts an LGTM stack — no manual setup needed:

git clone https://github.com/quarkiverse/quarkus-ai-rca.git
cd quarkus-ai-rca

export OPENAI_API_KEY=sk-...   # or GROK_API_KEY for Grok

./dev-ai.sh 8081,8082

The app.ports argument is optional — it tells the AI module which of your application ports to connect to via Dev MCP for source examination and dashboard generation. This requires the target applications to be running in Quarkus dev mode (which exposes the Dev MCP endpoint). Without it, the core analysis (traces, logs, metrics) works the same — the Examine Source option is simply disabled in the UI.

LLM Provider Selection

The AI module uses Maven profiles to select the LLM provider:

./mvn.ai.sh quarkus:dev              # OpenAI (default)
./mvn.ai.sh quarkus:dev -Pgrok       # Grok/xAI
./mvn.ai.sh quarkus:dev -Pgemini     # Gemini
./mvn.ai.sh quarkus:dev -Pwatsonx    # WatsonX

Environment Variables

Set the API key for your chosen provider:

export OPENAI_API_KEY=sk-...
export GROK_API_KEY=xai-...
export GEMINI_API_KEY=...
export WATSONX_API_KEY=...

Analyze

Once the AI module and your applications are running and generating telemetry, open the Web UI at http://localhost:8080 or call the API directly:

curl http://localhost:8080/analyze/5   # analyze last 5 traces

Production Mode (Uber-jar)

For connecting to an existing LGTM instance without dev mode, use the pre-built uber-jar:

# Build locally
./mvn.ai.sh package -DskipTests

# Run with existing LGTM
./run-ai.sh http://localhost:3000 http://localhost:3200 8081,8082

The uber-jar is also published to Maven Central:

io.quarkiverse.ai.rca:quarkus-ai-rca-core:<version>:jar:runner

Dashboard Generation

When you enable Create Dashboard in the web UI, the AI module generates a Grafana dashboard with panels tailored to the issues it found (JVM memory, CPU usage, HTTP latency, error rates, etc.).

In dev mode (with app.ports configured), the AI module writes the dashboard JSON directly into your application’s src/main/resources/META-INF/dashboards/ directory via Dev MCP. Just restart your application — Quarkus automatically provisions the dashboard into your Grafana instance. No manual import needed.

In production mode (uber-jar without app.ports), the dashboard JSON is still generated and displayed in the UI’s Dashboard section, where you can copy it and import it into Grafana manually.

Manual LGTM (without DevServices)

To connect to an externally started LGTM stack instead of using Dev Services:

docker run -p 3000:3000 -p 4317:4317 -p 4318:4318 -p 3200:3200 grafana/otel-lgtm:0.24.0

Then run the AI module with the lgtm profile:

./mvn.ai.sh quarkus:dev -Dquarkus.profile=lgtm,openai

Trying It with Example Apps

The project includes companion modules (proxy, app, ext) that simulate distributed microservices with configurable chaos failure modes. These are useful for trying out the AI analysis without instrumenting your own applications:

# Terminal 1: Start proxy (launches shared LGTM DevServices)
./mvn.proxy.sh quarkus:dev

# Terminal 2: Start app (wait for proxy to fully start)
./mvn.app.sh quarkus:dev

# Terminal 3: Start AI module
./dev-ai.sh 8081,8082

Generate traces by poking the proxy: curl http://localhost:8081/poke?value=500

See Integration Testing for the full catalog of chaos scenarios these apps support.

Scripts Reference

Script Purpose

./dev-ai.sh [ports]

Start AI module in dev mode with Dev Services (LGTM auto-starts)

./run-ai.sh <grafana-url> <tempo-url> [ports]

Run AI module uber-jar against existing LGTM

./mvn.ai.sh <goals>

Build/run the AI module with Maven

./run-lgtm.sh [ports]

Start LGTM and the AI module together