Home

LoomDoctor Wiki

Welcome to the official documentation for LoomDoctor, a production telemetry and diagnostics framework designed for Java 21+ Project Loom Virtual Threads.

The Problem LoomDoctor Solves

Project Loom introduces lightweight virtual threads (java.lang.Thread.ofVirtual()) capable of scaling concurrent operations to millions of tasks. However, two silent killers threaten production stability:

1. Carrier Thread Pinning: When virtual threads execute blocking operations inside synchronized blocks, synchronized methods, or native JNI methods, the underlying OS carrier thread is pinned and unable to context-switch to other ready virtual threads.
2. Resource Pool Starvation: Because thousands of virtual threads can run simultaneously, fixed-size downstream resources (such as HikariCP database connection pools, HTTP client pools, or semaphore queues) experience catastrophic contention if unthrottled.

LoomDoctor monitors, captures, and diagnoses these runtime hazards in real time, exposing health metrics directly through Spring Boot Actuator or programmatic APIs.

Key Capabilities

• Circular Buffer Pinning Detector: Captures stack traces, pinned carrier thread names, durations, and pinpointed class/method locations with zero memory leak risk.
• Pool Starvation Monitor: Tracks active vs. queued virtual threads waiting on connection pools, calculating wait-to-capacity ratios and flagging critical congestion before thread pools crash.
• Spring Boot Actuator Endpoint: Exposes /actuator/loom-doctor with structured JSON diagnostic reports, health status badges (HEALTHY, DEGRADED, CRITICAL), and actionable remediation advice.
• Lightweight Core: Pure Java 21+ with zero heavy external dependencies. Compatible with any standalone application or microservice framework.

Module Structure

• loomdoctor-core: Core telemetry models, pinning detector buffer, pool starvation analyzer, and diagnostic reporting facade.
• loomdoctor-spring-boot-starter: Spring Boot 3 auto-configuration and native Actuator web endpoint /actuator/loom-doctor.

Quick Navigation

• Getting Started: Installation via Maven / Gradle and basic setup.
• Complete API Reference: Comprehensive documentation of all classes, methods, parameters, and code examples.
• Architecture & Telemetry: Deep dive into virtual thread pinning mechanics and pool starvation algorithms.
• Configuration Reference: Reference guide for application.yml properties and JVM flags.