From dc29afd4c8c7fe16d0c321e3bcbf10f1596a5bae Mon Sep 17 00:00:00 2001
From: hsiegeln <37154749+hsiegeln@users.noreply.github.com>
Date: Sun, 12 Apr 2026 18:29:01 +0200
Subject: [PATCH] docs: add Prometheus metrics reference to CLAUDE.md

Lists all business metrics (gauges, counters, timers) with their
tags and source classes, plus agent container label mapping table.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 CLAUDE.md | 41 ++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 40 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index c39469dd..6a25c07a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -296,6 +296,45 @@ In SaaS mode, each tenant's server and its deployed apps are isolated at the Doc
 
 - `client_max_body_size 200m` is required in the nginx config to allow JAR uploads up to 200 MB. Without this, large JAR uploads return 413.
 
+### Prometheus Metrics
+
+Server exposes `/api/v1/prometheus` (unauthenticated, Prometheus text format). Spring Boot Actuator provides JVM, GC, thread pool, and `http.server.requests` metrics automatically. Business metrics via `ServerMetrics` component:
+
+**Gauges (auto-polled):**
+
+| Metric | Tags | Source |
+|--------|------|--------|
+| `cameleer.agents.connected` | `state` (live, stale, dead, shutdown) | `AgentRegistryService.findByState()` |
+| `cameleer.agents.sse.active` | — | `SseConnectionManager.getConnectionCount()` |
+| `cameleer.ingestion.buffer.size` | `type` (execution, processor, log, metrics) | `WriteBuffer.size()` |
+| `cameleer.ingestion.accumulator.pending` | — | `ChunkAccumulator.getPendingCount()` |
+
+**Counters:**
+
+| Metric | Tags | Instrumented in |
+|--------|------|-----------------|
+| `cameleer.ingestion.drops` | `reason` (buffer_full, no_agent, no_identity) | `LogIngestionController` |
+| `cameleer.agents.transitions` | `transition` (went_stale, went_dead, recovered) | `AgentLifecycleMonitor` |
+| `cameleer.deployments.outcome` | `status` (running, failed, degraded) | `DeploymentExecutor` |
+| `cameleer.auth.failures` | `reason` (invalid_token, revoked, oidc_rejected) | `JwtAuthenticationFilter` |
+
+**Timers:**
+
+| Metric | Tags | Instrumented in |
+|--------|------|-----------------|
+| `cameleer.ingestion.flush.duration` | `type` (execution, processor, log) | `ExecutionFlushScheduler` |
+| `cameleer.deployments.duration` | — | `DeploymentExecutor` |
+
+**Agent container Prometheus labels** (set by `PrometheusLabelBuilder` at deploy time):
+
+| Runtime Type | `prometheus.path` | `prometheus.port` |
+|---|---|---|
+| `spring-boot` | `/actuator/prometheus` | `8081` |
+| `quarkus` / `native` | `/q/metrics` | `9000` |
+| `plain-java` | `/metrics` | `9464` |
+
+All containers also get `prometheus.scrape=true`. These labels enable Prometheus `docker_sd_configs` auto-discovery.
+
 ## Disabled Skills
 
 - Do NOT use any `gsd:*` skills in this project. This includes all `/gsd:` prefixed commands.
@@ -303,7 +342,7 @@ In SaaS mode, each tenant's server and its deployed apps are isolated at the Doc
 <!-- gitnexus:start -->
 # GitNexus — Code Intelligence
 
-This project is indexed by GitNexus as **cameleer3-server** (5987 symbols, 15177 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+This project is indexed by GitNexus as **cameleer3-server** (6012 symbols, 15283 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
 
 > If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.