tessl/maven-io-dropwizard-metrics--metrics-jvm

JVM Integration for Metrics - A set of classes which allow you to monitor critical aspects of your Java Virtual Machine using Metrics

—

Pending

Overview

Eval results

Files

File Descriptor Monitoring

Name: tessl/maven-io-dropwizard-metrics--metrics-jvm
Author: tessl

File descriptor usage ratio monitoring for Unix-based systems, providing insight into resource utilization and potential file handle leaks.

Core Imports

import com.codahale.metrics.jvm.FileDescriptorRatioGauge;
import com.codahale.metrics.MetricRegistry;
import java.lang.management.OperatingSystemMXBean;

Capabilities

FileDescriptorRatioGauge

Monitors the ratio of used to total available file descriptors on Unix systems.

/**
 * A gauge for the ratio of used to total file descriptors.
 */
public class FileDescriptorRatioGauge extends RatioGauge {
    /**
     * Creates a new gauge using the platform OperatingSystemMXBean.
     */
    public FileDescriptorRatioGauge();
    
    /**
     * Creates a new gauge using a custom OperatingSystemMXBean.
     * @param os an OperatingSystemMXBean
     */
    public FileDescriptorRatioGauge(OperatingSystemMXBean os);
    
    /**
     * Returns the ratio of used to available file descriptors.
     * @return Ratio object containing numerator and denominator
     */
    protected Ratio getRatio();
}

Metrics Provided:

Returns a ratio value between 0.0 and 1.0 representing file descriptor utilization
On non-Unix systems or when UnixOperatingSystemMXBean is not available, returns NaN

Usage Examples:

import com.codahale.metrics.MetricRegistry;
import com.codahale.metrics.jvm.FileDescriptorRatioGauge;
import java.lang.management.ManagementFactory;

// Basic usage with platform OS bean
MetricRegistry registry = new MetricRegistry();
FileDescriptorRatioGauge fdGauge = new FileDescriptorRatioGauge();
registry.register("file-descriptor-ratio", fdGauge);

// Check file descriptor usage
double fdRatio = fdGauge.getValue();
if (!Double.isNaN(fdRatio)) {
    System.out.println("File descriptor usage: " + (fdRatio * 100) + "%");
    
    if (fdRatio > 0.8) {
        System.out.println("WARNING: High file descriptor usage!");
    }
} else {
    System.out.println("File descriptor monitoring not available on this platform");
}

// Custom OperatingSystemMXBean usage
OperatingSystemMXBean customOsBean = ManagementFactory.getOperatingSystemMXBean();
FileDescriptorRatioGauge customFdGauge = new FileDescriptorRatioGauge(customOsBean);
registry.register("custom-fd-ratio", customFdGauge);

// Access underlying file descriptor counts (if on Unix system)
if (customOsBean instanceof com.sun.management.UnixOperatingSystemMXBean) {
    com.sun.management.UnixOperatingSystemMXBean unixOs = 
        (com.sun.management.UnixOperatingSystemMXBean) customOsBean;
    
    long openFds = unixOs.getOpenFileDescriptorCount();
    long maxFds = unixOs.getMaxFileDescriptorCount();
    
    System.out.println("Open file descriptors: " + openFds);
    System.out.println("Max file descriptors: " + maxFds);
    System.out.println("Available file descriptors: " + (maxFds - openFds));
}

Monitoring Patterns:

Normal Range: Typically 0.1 to 0.6 (10% to 60%) for healthy applications
Warning Level: Above 0.8 (80%) indicates potential resource pressure
Critical Level: Above 0.95 (95%) suggests imminent file descriptor exhaustion
Trending Upward: May indicate file descriptor leaks

Platform Compatibility:

Unix/Linux Systems: Full functionality with actual file descriptor counts
Windows Systems: Returns NaN (not applicable)
JVM Without Unix Support: Returns NaN when com.sun.management.UnixOperatingSystemMXBean is not available

Common Causes of High Usage:

Network Connections: Each socket consumes a file descriptor
Open Files: Database connections, log files, configuration files
Pipes and FIFOs: Inter-process communication mechanisms
Memory-Mapped Files: Each mapped file region may consume descriptors
Resource Leaks: Unclosed streams, connections, or file handles

Monitoring Integration:

// Alert-based monitoring
public class FileDescriptorAlert {
    private final FileDescriptorRatioGauge gauge;
    private final double warningThreshold = 0.8;
    private final double criticalThreshold = 0.95;
    
    public FileDescriptorAlert(FileDescriptorRatioGauge gauge) {
        this.gauge = gauge;
    }
    
    public AlertLevel checkStatus() {
        double ratio = gauge.getValue();
        
        if (Double.isNaN(ratio)) {
            return AlertLevel.UNKNOWN;
        } else if (ratio >= criticalThreshold) {
            return AlertLevel.CRITICAL;
        } else if (ratio >= warningThreshold) {
            return AlertLevel.WARNING;
        } else {
            return AlertLevel.OK;
        }
    }
    
    enum AlertLevel {
        OK, WARNING, CRITICAL, UNKNOWN
    }
}

// Health check integration
public class FileDescriptorHealthCheck extends HealthCheck {
    private final FileDescriptorRatioGauge gauge;
    
    public FileDescriptorHealthCheck(FileDescriptorRatioGauge gauge) {
        this.gauge = gauge;
    }
    
    @Override
    protected Result check() {
        double ratio = gauge.getValue();
        
        if (Double.isNaN(ratio)) {
            return Result.healthy("File descriptor monitoring not available");
        }
        
        if (ratio > 0.95) {
            return Result.unhealthy("Critical file descriptor usage: %.1f%%", ratio * 100);
        } else if (ratio > 0.8) {
            return Result.unhealthy("High file descriptor usage: %.1f%%", ratio * 100);
        } else {
            return Result.healthy("File descriptor usage: %.1f%%", ratio * 100);
        }
    }
}

Install with Tessl CLI

npx tessl i tessl/maven-io-dropwizard-metrics--metrics-jvm

docs

buffer-pool-monitoring.md

class-loading-monitoring.md

cpu-time-monitoring.md

file-descriptor-monitoring.md

gc-monitoring.md

index.md

jmx-attribute-access.md

tessl/maven-io-dropwizard-metrics--metrics-jvm