Observability and Logging

Module 8 · ~8 min read

A RAG pipeline has many failure modes: slow LLMs, cache misses, low-confidence retrieval, guardrail blocks, PII redactions. Good logging makes each of these visible at a glance. Power RAG logs structured INFO messages at every pipeline outcome and WARN messages at every safety event.

Key Log Points in the Pipeline

RagService.java — pipeline log statements View source ↗

// Successful full RAG query
log.info("RAG query completed in {}ms — provider={} model={} confidence={} sources={} lang={}",
    durationMs, resolvedProvider, resolvedId, confidence, sources.size(), lang);

// Cache hit — pipeline short-circuited
log.info("RAG cache HIT in {}ms — lang={}", durationMs, lang);

// Input blocked by guardrail
log.warn("Input blocked by guardrail: category={}", inputCheck.category());

// Output PII detected
log.warn("Output PII detected: category={}", outputCheck.category());

// No relevant documents found
log.info("No relevant docs (confidence={}), using general knowledge", confidence);

What Each Log Line Tells You

Log message	Operational insight
`RAG query completed in Xms`	End-to-end latency. >5s may indicate LLM timeout or slow retrieval
`confidence=0.XX`	Retrieval quality. Low values (<0.2) repeatedly may indicate indexing gaps
`sources=N`	How many chunks were used. 0 = general knowledge fallback
`RAG cache HIT`	Cache is working. High hit rate = cost and latency savings
`Input blocked by guardrail`	Safety system triggered. Monitor for false positives
`Output PII detected`	PII found in LLM response. Investigate document content

Log Level Configuration

application.yml — logging levels View source ↗

logging:
  level:
    com.powerrag: INFO
    org.springframework.ai: INFO      # change to DEBUG for LLM call details
    org.springframework.security: WARN # change to DEBUG for auth tracing
    org.flywaydb: INFO

Set org.springframework.ai to DEBUG to see the full prompt and response for every LLM call — extremely useful during development. Never leave DEBUG enabled in production (it logs the full prompt content including any sensitive user queries).

JaCoCo Coverage Thresholds

The Maven build enforces minimum coverage thresholds. The build fails if coverage drops below these levels, preventing new code from being merged without tests.

pom.xml — JaCoCo coverage rules View source ↗

<rule>
  <element>BUNDLE</element>
  <limits>
    <limit><counter>LINE</counter><value>COVEREDRATIO</value><minimum>0.80</minimum></limit>
    <limit><counter>BRANCH</counter><value>COVEREDRATIO</value><minimum>0.75</minimum></limit>
  </limits>
</rule>

Spring Boot Actuator Endpoints

Spring Boot Actuator provides built-in operational endpoints. Power RAG exposes:

Endpoint	Purpose	Access
`/actuator/health`	Application health status — checks DB, Redis, Qdrant connectivity	Public (for load balancer health checks)
`/actuator/metrics`	JVM metrics, HTTP request counts, latency histograms	Authenticated / internal only
`/actuator/prometheus`	Prometheus-format metrics scrape endpoint	Authenticated / internal only

For production monitoring, connect /actuator/prometheus to a Prometheus + Grafana stack. Key metrics to dashboard: http_server_requests_seconds (latency by endpoint), custom rag.query.duration timer, and rag.cache.hit.rate gauge.

Congratulations!

You have completed the Spring AI & RAG Development course. You now understand every component of the Power RAG pipeline — from document ingestion to LLM response, from semantic caching to safety guardrails.

The full source code is available at github.com/lcheeyon/power-rag.

← Previous Next →