0
# File Descriptor Monitoring
1

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

4
## Core Imports
5

6
```java
7
import com.codahale.metrics.jvm.FileDescriptorRatioGauge;
8
import com.codahale.metrics.MetricRegistry;
9
import java.lang.management.OperatingSystemMXBean;
10
```
11

12
## Capabilities
13

14
### FileDescriptorRatioGauge
15

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

18
```java { .api }
19
/**
20
 * A gauge for the ratio of used to total file descriptors.
21
 */
22
public class FileDescriptorRatioGauge extends RatioGauge {
23
    /**
24
     * Creates a new gauge using the platform OperatingSystemMXBean.
25
     */
26
    public FileDescriptorRatioGauge();
27
    
28
    /**
29
     * Creates a new gauge using a custom OperatingSystemMXBean.
30
     * @param os an OperatingSystemMXBean
31
     */
32
    public FileDescriptorRatioGauge(OperatingSystemMXBean os);
33
    
34
    /**
35
     * Returns the ratio of used to available file descriptors.
36
     * @return Ratio object containing numerator and denominator
37
     */
38
    protected Ratio getRatio();
39
}
40
```
41

42
**Metrics Provided:**
43

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

47
**Usage Examples:**
48

49
```java
50
import com.codahale.metrics.MetricRegistry;
51
import com.codahale.metrics.jvm.FileDescriptorRatioGauge;
52
import java.lang.management.ManagementFactory;
53

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

59
// Check file descriptor usage
60
double fdRatio = fdGauge.getValue();
61
if (!Double.isNaN(fdRatio)) {
62
    System.out.println("File descriptor usage: " + (fdRatio * 100) + "%");
63
    
64
    if (fdRatio > 0.8) {
65
        System.out.println("WARNING: High file descriptor usage!");
66
    }
67
} else {
68
    System.out.println("File descriptor monitoring not available on this platform");
69
}
70

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

76
// Access underlying file descriptor counts (if on Unix system)
77
if (customOsBean instanceof com.sun.management.UnixOperatingSystemMXBean) {
78
    com.sun.management.UnixOperatingSystemMXBean unixOs = 
79
        (com.sun.management.UnixOperatingSystemMXBean) customOsBean;
80
    
81
    long openFds = unixOs.getOpenFileDescriptorCount();
82
    long maxFds = unixOs.getMaxFileDescriptorCount();
83
    
84
    System.out.println("Open file descriptors: " + openFds);
85
    System.out.println("Max file descriptors: " + maxFds);
86
    System.out.println("Available file descriptors: " + (maxFds - openFds));
87
}
88
```
89

90
**Monitoring Patterns:**
91

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

97
**Platform Compatibility:**
98

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

103
**Common Causes of High Usage:**
104

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

111
**Monitoring Integration:**
112

113
```java
114
// Alert-based monitoring
115
public class FileDescriptorAlert {
116
    private final FileDescriptorRatioGauge gauge;
117
    private final double warningThreshold = 0.8;
118
    private final double criticalThreshold = 0.95;
119
    
120
    public FileDescriptorAlert(FileDescriptorRatioGauge gauge) {
121
        this.gauge = gauge;
122
    }
123
    
124
    public AlertLevel checkStatus() {
125
        double ratio = gauge.getValue();
126
        
127
        if (Double.isNaN(ratio)) {
128
            return AlertLevel.UNKNOWN;
129
        } else if (ratio >= criticalThreshold) {
130
            return AlertLevel.CRITICAL;
131
        } else if (ratio >= warningThreshold) {
132
            return AlertLevel.WARNING;
133
        } else {
134
            return AlertLevel.OK;
135
        }
136
    }
137
    
138
    enum AlertLevel {
139
        OK, WARNING, CRITICAL, UNKNOWN
140
    }
141
}
142

143
// Health check integration
144
public class FileDescriptorHealthCheck extends HealthCheck {
145
    private final FileDescriptorRatioGauge gauge;
146
    
147
    public FileDescriptorHealthCheck(FileDescriptorRatioGauge gauge) {
148
        this.gauge = gauge;
149
    }
150
    
151
    @Override
152
    protected Result check() {
153
        double ratio = gauge.getValue();
154
        
155
        if (Double.isNaN(ratio)) {
156
            return Result.healthy("File descriptor monitoring not available");
157
        }
158
        
159
        if (ratio > 0.95) {
160
            return Result.unhealthy("Critical file descriptor usage: %.1f%%", ratio * 100);
161
        } else if (ratio > 0.8) {
162
            return Result.unhealthy("High file descriptor usage: %.1f%%", ratio * 100);
163
        } else {
164
            return Result.healthy("File descriptor usage: %.1f%%", ratio * 100);
165
        }
166
    }
167
}
168
```