Debugging Java performance issues in Kubernetes — heap exhaustion, GC thrashing, memory leaks, OOMKills — is slow, manual, and requires deep expertise. A developer typically has to correlate pod logs, inspect Kubernetes events, figure out how to attach a profiler, collect JFR recordings, and then make sense of all of it under pressure. The result is high mean time to resolution (MTTR) and significant cognitive overhead every time something goes wrong.
Causa eliminates that toil. It is an open-source, AI-powered root-cause analysis agent for Java workloads on Kubernetes. When a Prometheus alert fires, Causa automatically aggregates context from your cluster — pod state, logs, Kubernetes events, JVM metrics via Quarkus MCP, and continuous profiling data via Jafra — and feeds that context through an AI analysis pipeline to produce prioritised, actionable remediation steps within seconds.
Key benefits:
- Drastically reduced MTTR — the time from alert firing to a root-cause explanation drops from hours of manual investigation to seconds of automated analysis.
- No profiling expertise required — Jafra automatically injects async-profiler into your Java pod and streams JFR recordings. You do not need to know how to attach a profiler or interpret raw flight recordings.
- AI-native developer workflow — Causa surfaces results through your existing AI assistant (Bob IDE, Claude Code, Cursor, Windsurf, or any MCP-capable tool). Ask your IDE "why is this app crashing?" and get a structured diagnosis back.
- Fully open source — every component from the RCA backend to the profiler agent is open source and available on github.com/causaai.
- Works locally — the default installation provisions a local Kind cluster, so you can try Causa on your laptop with no cloud account required if you use the bundled Ollama LLM option.
This guide walks you through everything you need to do from scratch to get Causa installed, configured, and analysing your first workload.
- Architecture Overview
- Prerequisites
- Install Causa
- Configure the LLM Provider
- Onboard a Java Workload
- Connect Your AI Assistant
- Verify Everything Is Working
- Run a Demo End-to-End
- Tear Down
Causa is composed of several cooperating components. Understanding how they fit together helps you follow the installation steps.
Your Java App (pod)
│
│ jafra.io/enabled=true label triggers injection
▼
jafra-controller ──→ injects async-profiler via mutating webhook
│
│ JFR chunks written to node-local hostPath
▼
jafra-agent (DaemonSet) ──gRPC──→ jafra-analyzer ──HTTP──→ Jafra MCP Server
(stores & stitches (LLM-accessible)
recordings)
Prometheus + Alertmanager
│ memory alert fires
▼
causa ←── gathers context from:
│ - Kubernetes MCP Server (pod, logs, events)
│ - Quarkus MCP Server (JVM metrics)
│ - Jafra (Experimental) MCP Server (JFR analysis)
│ runs AI analysis via LLM provider
▼
causa-mcp-server ←── Bob IDE / Claude Code / any MCP client
│ returns structured RCA
▼
Developer sees root cause + prioritised remediation steps
Component summary:
| Component | Repo | What it does |
|---|---|---|
causa |
causaai/causa | Quarkus-based AI RCA agent; receives Prometheus alerts and produces diagnoses |
causa-mcp |
causaai/causa-mcp | MCP server bridging your IDE/agent to the Causa engine |
| Jafra (Experimental) | — | Continuous profiling ecosystem for Java workloads in Kubernetes — see docs/tools/jafra.md |
jafra-controller - Experimental |
bharathappali/jafra-controller | Go mutating webhook; injects async-profiler into opted-in Java pods |
jafra-agent - Experimental |
bharathappali/jafra-agent | Rust DaemonSet; streams JFR chunks from nodes to the analyzer |
jafra-analyzer - Experimental |
bharathappali/jafra-analyzer | Quarkus service; stores recordings and serves automated JFR analysis |
installer |
causaai/installer | Shell installer; deploys the full stack in one command |
causa-demos |
causaai/causa-demos | End-to-end demos with a pre-built chaos workload |
| Tool | Purpose | Install |
|---|---|---|
docker or podman |
Container runtime for Kind | docker / podman |
kind |
Local Kubernetes cluster | kind.sigs.k8s.io |
kubectl |
Kubernetes CLI | kubernetes.io |
helm |
Installs the Prometheus stack | helm.sh |
git |
Cloning the installer | pre-installed on most systems |
curl, grep, sed, awk |
Script utilities | pre-installed on macOS and most Linux distributions |
jq |
JSON pretty-printer (used in verify steps) | jq — brew install jq / apt install jq |
envsubst |
Variable substitution in YAML templates | pre-installed on Linux; macOS: brew install gettext && brew link gettext |
Podman users: Kind requires rootful mode. Run:
podman machine init --rootful --cpus 4 --memory 4096 podman machine start
| Tool | Purpose | Install |
|---|---|---|
oc (preferred) or kubectl |
Cluster CLI | OpenShift CLI |
helm, curl, grep, sed, awk |
Script utilities | pre-installed on most systems |
python3 + PyYAML |
Alertmanager config merge | pip3 install pyyaml |
Additional OpenShift cluster requirements:
- Active login to the cluster (
oc login <api-url>) cert-managerinstalled and running in the cluster- Cluster-admin permissions
| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 4 vCPUs | 6+ vCPUs |
| RAM | 8 GB | 16 GB |
| Disk | 10 GB free | 20 GB free |
The Jafra ecosystem and Prometheus stack together add meaningful resource pressure on a laptop. 16 GB RAM is strongly recommended.
oc whoami
oc auth can-i create deployments -n defaultThe installer handles everything: provisioning a Kind cluster (if needed), deploying Prometheus, cert-manager, PostgreSQL, Jafra, and all Causa components.
# Clone the installer
git clone https://github.com/causaai/installer.git
cd installer
# Dry run — validates prerequisites without making any changes
./install.sh --dry-run
# Full install — provisions a Kind cluster named 'causa-rca' and deploys all components
./install.shWhen the installer completes, all components are running in the causa-rca namespace. All services are ClusterIP — use kubectl port-forward to reach them from your local machine (see Port-forwarding on Kind below).
| Local port | Service |
|---|---|
30000 |
Kubernetes MCP Server |
30001 |
Causa Backend |
30004 |
Quarkus MCP Server |
30005 |
Causa MCP Server |
What gets installed on Kind:
- Kind cluster + local registry
- Prometheus stack (kube-prometheus-stack) — for alerting
- cert-manager — required by the Jafra Controller webhook
- Kubernetes MCP Server
- Jafra Ecosystem - Experimental (Controller, Agent, Analyzer)
- Jafra MCP Server
- Quarkus MCP Server
- PostgreSQL with pgvector
- Causa
- Causa MCP Server
If you already know the in-cluster URL of the Java app you want to monitor, set it before running the installer so the Quarkus MCP server can start scraping metrics immediately:
export CAUSA_MCP_QUARKUS_METRICS_BASE_URL="http://my-app.my-namespace.svc.cluster.local:8080"
./install.shYou can always set or update it after installation:
kubectl set env deployment/causa-backend -n causa-rca \
CAUSA_MCP_QUARKUS_METRICS_BASE_URL="http://my-app.my-namespace.svc.cluster.local:8080"
kubectl rollout status deployment/causa-backend -n causa-rca --timeout=180sgit clone https://github.com/causaai/installer.git
cd installer
# Log in to your cluster first
oc login <api-url>
# Deploy into an existing cluster (default namespace: causa-rca)
./install.sh --target openshiftNote: Jafra (Ecosystem + MCP Server) is not supported on OpenShift. The installer skips it automatically.
What gets installed on OpenShift:
- OpenShift User Workload Monitoring (enabled) + Alertmanager webhook configured
- Kubernetes MCP Server + Route
- Quarkus MCP Server
- PostgreSQL via CloudNativePG operator
- Causa + Route
- Causa MCP Server + Route
# Kind
./install.sh -n my-namespace
# OpenShift
./install.sh --target openshift -n my-namespaceCausa uses an LLM to perform root-cause analysis. Three providers are currently implemented. Choose one and follow the steps below.
| Provider | LLM_PROVIDER value |
When to use |
|---|---|---|
| Google Vertex AI (Claude) | vertex-ai-anthropic |
You have a GCP project with Vertex AI and Claude access |
| Anthropic Direct API | anthropic |
You have an Anthropic API key (simplest, no GCP required) |
| IBM Bob | bob |
You have IBM Bob installed (IBM internal) |
Configuration is pushed to the running Causa Backend via its config API — no redeployment is required.
Option A — Vertex AI (Claude on Google Cloud)
Sub-option A: Application Default Credentials (quickest, personal dev)
gcloud auth application-default login
gcloud auth application-default set-quota-project <your-gcp-project-id>
# Credentials are written to: ~/.config/gcloud/application_default_credentials.jsonADC credentials are personal and short-lived. Use Sub-option B for shared environments.
Sub-option B: Service account key (recommended for shared / CI environments)
# Create the service account
gcloud iam service-accounts create causa-llm-sa \
--project=<your-gcp-project-id>
# Grant Vertex AI access
gcloud projects add-iam-policy-binding <your-gcp-project-id> \
--member="serviceAccount:causa-llm-sa@<your-gcp-project-id>.iam.gserviceaccount.com" \
--role="roles/aiplatform.user" \
--condition=None
# Download the key file
gcloud iam service-accounts keys create causa-gcp-key.json \
--iam-account=causa-llm-sa@<your-gcp-project-id>.iam.gserviceaccount.com
⚠️ causa-gcp-key.jsonis a sensitive credential. Never commit it to Git.
Set CAUSA_URL for your environment before running any of the curl commands below:
# Kind (http — port-forwarded local endpoint)
CAUSA_URL=http://localhost:30001
# OpenShift (https — Route TLS terminates at the ingress controller)
CAUSA_URL=https://$(oc get route causa-backend -n causa-rca -o jsonpath='{.spec.host}')# Read and base64-encode your credentials file
# base64 flags differ by OS: -w0 on Linux disables line-wrapping; macOS base64 omits line-wraps by default
CREDS_B64=$(base64 -w0 <path-to-credentials-file> 2>/dev/null || base64 <path-to-credentials-file>)
# Sub-option A: ~/.config/gcloud/application_default_credentials.json
# Sub-option B: ./causa-gcp-key.json
curl -X POST ${CAUSA_URL}/api/v1/configs \
-H 'Content-Type: application/json' \
-d "{
\"configs\": {
\"LLM_PROVIDER\": \"vertex-ai-anthropic\",
\"LLM_MODEL_NAME\": \"claude-sonnet-4-6\",
\"VERTEX_PROJECT_ID\": \"<your-gcp-project-id>\",
\"VERTEX_LOCATION\": \"us-east5\",
\"GOOGLE_APPLICATION_CREDENTIALS\": \"${CREDS_B64}\"
}
}"Valid
VERTEX_LOCATIONvalues:us-east5,us-central1,europe-west1,asia-southeast1globalis not valid for Claude on Vertex AI.
Option B — Anthropic Direct API
Get your key at https://console.anthropic.com/settings/keys.
⚠️ Never commit API keys to Git or include them in shell history.
Set CAUSA_URL as shown at the top of this section, then:
curl -X POST ${CAUSA_URL}/api/v1/configs \
-H 'Content-Type: application/json' \
-d '{
"configs": {
"LLM_PROVIDER": "anthropic",
"LLM_MODEL_NAME": "claude-sonnet-4-6",
"LLM_API_KEY": "<your-anthropic-api-key>"
}
}'Option C — IBM Bob
IBM Bob must already be installed and configured on the host where causa runs. See the Bob Shell Integration Guide for full prerequisites.
Set CAUSA_URL as shown at the top of this section, then:
curl -X POST ${CAUSA_URL}/api/v1/configs \
-H 'Content-Type: application/json' \
-d '{
"configs": {
"LLM_PROVIDER": "bob",
"LLM_API_KEY": "<your-bob-api-key>"
}
}'Vertex AI (vertex-ai-anthropic) |
Anthropic Direct (anthropic) |
IBM Bob (bob) |
|
|---|---|---|---|
| LLM access | GCP Vertex AI | Anthropic API | IBM Bob shell |
| Credentials needed | GCP credentials file + project ID | API key | Bob API key |
| GCP account required | ✅ Yes | ❌ No | ❌ No |
To have Causa monitor and diagnose a workload you need to do three things:
- Label your pod with
causa.ai/monitoring=trueso Causa knows to watch it. - Apply the PrometheusRule so Causa is notified when something goes wrong.
- Optionally, opt your pod into Jafra so async-profiler continuously captures CPU, allocation, lock, and GC data that Causa can feed into its AI analysis.
This label is required. Every alert rule shipped with Causa filters on
causa.ai/monitoring="true". Pods without this label are ignored, even if Prometheus is scraping them.
Add the label to your Deployment's pod template so it persists across restarts:
# In your Deployment spec.template.metadata.labels:
labels:
causa.ai/monitoring: "true"Or apply it imperatively to a running pod (for quick testing only — it is lost on pod restart):
kubectl label pod <pod-name> causa.ai/monitoring=true -n <namespace>Or patch the Deployment directly:
kubectl patch deployment <your-deployment> -n <your-namespace> \
--type=merge \
-p='{"spec":{"template":{"metadata":{"labels":{"causa.ai/monitoring":"true"}}}}}'
kubectl rollout status deployment/<your-deployment> -n <your-namespace>The installer applies the PrometheusRule from installer/manifests/prometheus/prometheusrule.yaml. It defines five alert rules, all scoped to pods carrying causa.ai/monitoring=true:
| Alert | Severity | Condition |
|---|---|---|
CausaAppHighMemoryUsage |
warning | Container exceeds 80 % of its memory limit |
CausaAppOOMKilled |
critical | Container was killed by the kernel OOM reaper |
CausaAppCrashLoopBackOff |
critical | Pod restarts > 2 times in 10 minutes |
CausaAppCPUThrottling |
warning | Container CPU throttling > 50 % for 2 minutes |
CausaAppFrequentRestarts |
warning | Pod restarts > 5 times in 30 minutes |
When any of these alerts fire, Alertmanager POSTs the payload to causa-backend at /api/v1/webhooks/alerts, which triggers an automatic RCA for the affected workload. A 15-minute cooldown prevents duplicate analyses.
If the rule was not applied automatically (e.g. you are onboarding a workload in a non-default namespace), apply it manually after substituting the namespace placeholder:
# Replace PLACEHOLDER_NAMESPACE with your target namespace, then apply
sed 's/PLACEHOLDER_NAMESPACE/<your-namespace>/g' \
installer/manifests/prometheus/prometheusrule.yaml | kubectl apply -f -The installer also applies a NetworkPolicy (installer/manifests/prometheus/networkpolicy.yaml) that allows Alertmanager to reach causa-backend on port 8080. Apply it the same way if your cluster uses a default-deny ingress policy:
sed 's/PLACEHOLDER_NAMESPACE/<your-namespace>/g' \
installer/manifests/prometheus/networkpolicy.yaml | kubectl apply -f -Verify the rule is registered:
# Kind
kubectl get prometheusrule -n causa-rca
# OpenShift
oc get prometheusrule -n causa-rcaJafra is deployed on Kind by the installer. To start profiling a Java pod, add two labels and one annotation to it:
Minimum required:
metadata:
labels:
jafra.io/enabled: "true"
jafra.io/mode: "continuous"
annotations:
jafra.io/containers: "<your-container-name>"The jafra-controller mutating webhook intercepts the pod creation, injects async-profiler, and configures JDK Flight Recorder. JFR chunks are collected by the jafra-agent DaemonSet and forwarded to jafra-analyzer automatically.
Imperative patch on a running deployment:
kubectl patch deployment <your-deployment> -n <your-namespace> \
--type=merge \
-p='{
"spec": {
"template": {
"metadata": {
"labels": {
"jafra.io/enabled": "true",
"jafra.io/mode": "continuous"
},
"annotations": {
"jafra.io/containers": "<your-container-name>"
}
}
}
}
}'
kubectl rollout status deployment/<your-deployment> -n <your-namespace>Advanced profiler annotations (all optional — production defaults apply if omitted):
| Annotation | Default | Description |
|---|---|---|
jafra.io/event |
ctimer |
Profiling event type (ctimer does not require extra pod privileges) |
jafra.io/interval |
20ms |
CPU sampling interval |
jafra.io/alloc |
1m |
Allocation sampling threshold |
jafra.io/lock |
10ms |
Lock contention threshold |
jafra.io/nativemem |
2m |
Native memory allocation threshold |
jafra.io/jfrsync |
default |
Enables JDK Flight Recorder alongside async-profiler |
jafra.io/chunktime |
5s |
JFR rotation interval (minimum 5s) |
jafra.io/memlimit |
128m |
async-profiler internal memory limit |
jfrsync=defaultis strongly recommended — it adds GC pauses, JIT compilation, socket I/O, and code cache events to the recording, enabling the full set of JMC diagnostic rules in jafra-analyzer.
Verify injection succeeded:
kubectl get pod -l app=<your-app> -o jsonpath='{.items[0].metadata.annotations.jafra\.io/injected}'
# Expected: trueQuery recordings from jafra-analyzer:
kubectl -n causa-rca port-forward svc/jafra-analyzer 8080:8080
curl 'http://localhost:8080/api/v1/recordings'
curl 'http://localhost:8080/api/v1/recordings?namespace=<your-namespace>&pod=<pod-name>&container=<container-name>'On Kind, causa-backend and causa-mcp are ClusterIP services — run these in a terminal before using them:
kubectl port-forward svc/causa-backend 30001:8080 -n causa-rca &
kubectl port-forward svc/causa-mcp 30005:8081 -n causa-rca &Keep the sessions running. Replace causa-rca with your namespace if you installed with -n.
Causa exposes an MCP server so that any MCP-capable AI tool can trigger and retrieve root-cause analyses directly. Register the server in your IDE once and it is available for every project.
Add the following to ~/.bob/settings/mcp.json:
{
"mcpServers": {
"causa-rca": {
"type": "http",
"url": "http://localhost:30005/mcp"
}
}
}Add to ~/.claude.json:
{
"mcpServers": {
"causa-rca": {
"type": "http",
"url": "http://localhost:30005/mcp"
}
}
}Use http://localhost:30005/mcp as the streamable-HTTP MCP endpoint. On OpenShift, replace localhost:30005 with the causa-mcp route hostname.
The causa-rca skill tells your AI assistant how to use the Causa MCP tools. It lives in the causa repository at docs/skills/SKILL.md. If you have not already cloned that repo, do so first:
git clone https://github.com/causaai/causa.gitThen copy the skill to your AI assistant's skills directory:
# Bob
mkdir -p ~/.bob/skills/causa-rca
cp causa/docs/skills/SKILL.md ~/.bob/skills/causa-rca/SKILL.md
# Claude Code
mkdir -p ~/.claude/skills/causa-rca
cp causa/docs/skills/SKILL.md ~/.claude/skills/causa-rca/SKILL.mdOnce the skill is installed, you can trigger RCA with natural language:
Why is the quarkus-perf pod crashing in the causa-rca namespace?
| Tool | Description |
|---|---|
initiate_rca |
Triggers an RCA for a named failing app; returns a diagnostic_id |
get_rca_status |
Polls progress — returns PENDING, RUNNING, COMPLETED, or FAILED |
get_rca_result |
Returns the full RCA including root cause, evidence, and fix recommendations |
Run through these checks after completing the steps above.
Check all pods are running:
kubectl get pods -n causa-rcaAll pods should be in Running state. A newly created cluster may take 2–3 minutes for all images to pull.
Check Causa is healthy:
# Kind
curl -s http://localhost:30001/q/health/ready | jq .
# OpenShift
curl -s https://$(oc get route causa-backend -n causa-rca -o jsonpath='{.spec.host}')/q/health/ready | jq .Verify MCP environment variables were stamped:
kubectl set env deployment/causa-backend -n causa-rca --list | grep CAUSA_MCPExpected output:
CAUSA_MCP_QUARKUS_ENDPOINT=http://mcp-metrics.causa-rca.svc.cluster.local:8080
CAUSA_MCP_ASYNC_PROFILER_ENDPOINT=http://jafra-mcp.causa-rca.svc.cluster.local:8083
Verify Jafra is running (Kind only):
kubectl get pods -n causa-rca -l app=jafra-controller
kubectl get pods -n causa-rca -l app=jafra-analyzer
kubectl get pods -n causa-rca -l app=jafra-agentVerify the PrometheusRule exists:
kubectl get prometheusrule -n causa-rcaWatch Causa analyse a failure (after a pod triggers an alert):
kubectl logs -n causa-rca -l app=causa-backend -fQuery RCA results directly:
# Kind
curl http://localhost:30001/api/v1/diagnostics | jq .The fastest way to see Causa in action is with the bundled Quarkus RCA demo. It deploys a quarkus-perf workload engineered for chaos testing, with a load generator that gradually fills the heap until an OOMKill occurs. Causa detects and analyses the failure autonomously.
git clone https://github.com/causaai/causa-demos.git
cd causa-demos/quarkus-rca
# Copy the example env file and fill in your credentials
cp llm.env.example llm.env
# Edit llm.env — set your LLM_PROVIDER and matching credentialsThe llm.env.example file documents every supported provider. At minimum, set one of:
# Vertex AI (Google Cloud)
LLM_PROVIDER=vertex-ai-anthropic
VERTEX_PROJECT_ID=<your-gcp-project-id>
VERTEX_LOCATION=us-east5
GOOGLE_APPLICATION_CREDENTIALS=~/.config/gcloud/application_default_credentials.json
# — OR —
# Anthropic Direct
LLM_PROVIDER=anthropic
LLM_MODEL_NAME=claude-sonnet-4-6
LLM_API_KEY=sk-ant-api03-...
⚠️ llm.envis git-ignored. Never commit it.
# Full demo — provisions Kind cluster, deploys everything, registers MCP, installs the skill
./demo.sh
# Install the causa-rca skill to Bob at the same time
./demo.sh --skill-path ~/.bob/skills
# Install the causa-rca skill to Claude Code at the same time
./demo.sh --skill-path ~/.claude/skills
# Deploy against an existing OpenShift cluster
./demo.sh --target openshift -n my-rcaThe demo script:
- Runs the Causa installer (provisions Kind + deploys the full stack)
- Deploys
quarkus-perfwith chaos scenarios (large-response,idle-timeout,memory-cache) and a load-gen job - Pushes your LLM credentials to Causa
- Writes the Causa MCP config to
~/.bob/settings/mcp.jsonand~/.claude.json - Optionally copies the
causa-rcaskill to the path you specified - Prints ready-to-paste RCA prompts
# Watch pod restarts as the heap fills and OOMKill fires
kubectl get pods -n causa-rca -w
# Watch Causa analyse the failure in real time
kubectl logs -n causa-rca -l app=causa-backend -fThe load generator fills the 512 Mi heap in approximately 3–5 minutes. Once the OOMKill fires, Prometheus triggers an alert, Alertmanager delivers it to the Causa webhook, and Causa produces a root-cause analysis automatically.
Then ask your AI assistant:
Why is the quarkus-perf app crashing?
cd installer
./install.sh --terminatepkill -f "port-forward svc/causa-backend"
pkill -f "port-forward svc/causa-mcp"cd installer
./install.sh --terminate --delete-clustercd installer
./install.sh --target openshift --terminatecd causa-demos/quarkus-rca
./demo.sh -t # removes stack, keeps cluster
./demo.sh -t --delete-cluster # removes everything- Explore the API — The Causa Backend exposes a full REST API. See causa/docs/api for the full OpenAPI specification.
- Tune LLM behaviour — Temperature, max tokens, timeout, and model name are all configurable at runtime. See the LLM Configuration Options reference.
- Add more workloads — Repeat Section 5 for any additional Java deployment. Each newly labelled workload is automatically covered by the existing alert rule and Jafra injection with no further configuration.
- Rotate LLM credentials — Re-POST to
/api/v1/configsat any time. Settings take effect immediately without restarting Causa. - Contribute — All repos live under github.com/causaai. Fork, open a feature branch, and raise a PR.