Configuration Reference

Configuration Reference

This page documents all configuration properties, system environment variables, and JVM options for LoomDoctor.

---

1. Spring Boot Configuration Properties

All properties are prefixed with loomdoctor.

Property	Type	Default	Description
loomdoctor.enabled	boolean	true	Enables or disables LoomDoctor auto-configuration and Actuator integration.
loomdoctor.pinning-threshold-ms	long	50	Minimum duration in milliseconds for an incident to be categorized as actionable pinning.
loomdoctor.queue-starvation-ratio	double	2.0	Ratio of queuedThreads / activeConnections that triggers a pool starvation alert.

Complete application.yml Example

loomdoctor:
  enabled: true
  pinning-threshold-ms: 25
  queue-starvation-ratio: 1.5

management:
  endpoints:
    web:
      exposure:
        include: "health,info,loom-doctor"
  endpoint:
    loom-doctor:
      enabled: true

---

2. JVM Command-Line Flags

To allow the JVM to track and emit native virtual thread pinning diagnostics:

-Djdk.tracePinnedThreads

• Flag: -Djdk.tracePinnedThreads=short
  • Prints a concise, single-line stack trace identifying the pinned method whenever pinning occurs.
• Flag: -Djdk.tracePinnedThreads=full
  • Prints complete native and Java stack traces, including carrier thread worker names and monitor addresses.

Example

java -Djdk.tracePinnedThreads=short -jar my-service.jar

---

3. Java Flight Recorder (JFR) Events

Project Loom emits built-in JFR events compatible with JDK 21+:

• jdk.VirtualThreadPinned: Triggered when a virtual thread blocks while pinned.
• jdk.VirtualThreadSubmitFailed: Triggered if a virtual thread cannot be queued onto a carrier.

These events can be consumed programmatically by registering a jdk.jfr.consumer.RecordingStream and feeding them directly into LoomDoctor.getPinningDetector().recordPinning(...).