0
# CPU Time Monitoring
1

2
CPU time measurement capabilities for performance monitoring and thread-specific timing analysis.
3

4
## Core Imports
5

6
```java
7
import com.codahale.metrics.jvm.CpuTimeClock;
8
import com.codahale.metrics.Clock;
9
```
10

11
## Capabilities
12

13
### CpuTimeClock
14

15
A specialized clock implementation that returns the current thread's CPU time for precise performance measurement.
16

17
```java { .api }
18
/**
19
 * A clock implementation which returns the current thread's CPU time.
20
 */
21
public class CpuTimeClock extends Clock {
22
    /**
23
     * Returns the current thread's CPU time in nanoseconds.
24
     * @return CPU time tick for the current thread
25
     */
26
    public long getTick();
27
}
28
```
29

30
**Usage Examples:**
31

32
```java
33
import com.codahale.metrics.*;
34
import com.codahale.metrics.jvm.CpuTimeClock;
35

36
// Create CPU time clock instance
37
CpuTimeClock cpuClock = new CpuTimeClock();
38

39
// Use with Timer for CPU time measurement
40
MetricRegistry registry = new MetricRegistry();
41
Timer cpuTimer = new Timer(registry.getMetricRegistry(), cpuClock);
42
registry.register("cpu-time-timer", cpuTimer);
43

44
// Measure CPU time for operations
45
Timer.Context context = cpuTimer.time();
46
try {
47
    // Perform CPU-intensive operation
48
    performComplexCalculation();
49
} finally {
50
    context.stop(); // Records CPU time, not wall-clock time
51
}
52

53
// Direct CPU time measurement
54
long startCpuTime = cpuClock.getTick();
55
performOperation();
56
long endCpuTime = cpuClock.getTick();
57
long cpuTimeUsed = endCpuTime - startCpuTime;
58

59
System.out.println("CPU time used: " + cpuTimeUsed + " nanoseconds");
60
System.out.println("CPU time used: " + (cpuTimeUsed / 1_000_000.0) + " milliseconds");
61

62
// Compare with wall-clock time
63
Clock wallClock = Clock.defaultClock();
64
long startWall = wallClock.getTick();
65
long startCpu = cpuClock.getTick();
66

67
performOperationWithWaiting();
68

69
long endWall = wallClock.getTick();
70
long endCpu = cpuClock.getTick();
71

72
long wallTime = endWall - startWall;
73
long cpuTime = endCpu - startCpu;
74

75
System.out.println("Wall-clock time: " + (wallTime / 1_000_000.0) + " ms");
76
System.out.println("CPU time: " + (cpuTime / 1_000_000.0) + " ms");
77
System.out.println("CPU efficiency: " + ((double) cpuTime / wallTime * 100) + "%");
78
```
79

80
**Integration with Metrics Framework:**
81

82
```java
83
// Create histogram with CPU time measurement
84
Histogram cpuHistogram = new Histogram(new UniformReservoir()) {
85
    private final CpuTimeClock cpuClock = new CpuTimeClock();
86
    
87
    public void time(Runnable operation) {
88
        long start = cpuClock.getTick();
89
        try {
90
            operation.run();
91
        } finally {
92
            long duration = cpuClock.getTick() - start;
93
            update(duration);
94
        }
95
    }
96
};
97

98
// Usage
99
cpuHistogram.time(() -> {
100
    // CPU-intensive operation
101
    calculatePrimes(1000000);
102
});
103

104
// CPU time-based meter
105
Meter cpuMeter = new Meter(cpuClock);
106
registry.register("cpu-operations-rate", cpuMeter);
107

108
// Mark CPU-intensive operations
109
cpuMeter.mark(); // Records based on CPU time progression
110
```
111

112
**Performance Analysis Patterns:**
113

114
```java
115
public class CpuPerformanceAnalyzer {
116
    private final CpuTimeClock cpuClock = new CpuTimeClock();
117
    private final Clock wallClock = Clock.defaultClock();
118
    
119
    public PerformanceMetrics analyzeOperation(Runnable operation) {
120
        long startWall = wallClock.getTick();
121
        long startCpu = cpuClock.getTick();
122
        
123
        operation.run();
124
        
125
        long endWall = wallClock.getTick();
126
        long endCpu = cpuClock.getTick();
127
        
128
        return new PerformanceMetrics(
129
            endWall - startWall,    // Wall time
130
            endCpu - startCpu       // CPU time
131
        );
132
    }
133
    
134
    public static class PerformanceMetrics {
135
        private final long wallTimeNanos;
136
        private final long cpuTimeNanos;
137
        
138
        public PerformanceMetrics(long wallTimeNanos, long cpuTimeNanos) {
139
            this.wallTimeNanos = wallTimeNanos;
140
            this.cpuTimeNanos = cpuTimeNanos;
141
        }
142
        
143
        public double getCpuEfficiency() {
144
            return wallTimeNanos > 0 ? (double) cpuTimeNanos / wallTimeNanos : 0.0;
145
        }
146
        
147
        public long getWaitTimeNanos() {
148
            return wallTimeNanos - cpuTimeNanos;
149
        }
150
        
151
        public boolean isCpuBound() {
152
            return getCpuEfficiency() > 0.8; // More than 80% CPU usage
153
        }
154
        
155
        public boolean isIoBound() {
156
            return getCpuEfficiency() < 0.2; // Less than 20% CPU usage
157
        }
158
    }
159
}
160

161
// Usage
162
CpuPerformanceAnalyzer analyzer = new CpuPerformanceAnalyzer();
163
PerformanceMetrics metrics = analyzer.analyzeOperation(() -> {
164
    // Some operation to analyze
165
    processData();
166
});
167

168
System.out.println("CPU efficiency: " + (metrics.getCpuEfficiency() * 100) + "%");
169
System.out.println("Wait time: " + (metrics.getWaitTimeNanos() / 1_000_000.0) + " ms");
170
System.out.println("Operation type: " + 
171
    (metrics.isCpuBound() ? "CPU-bound" : 
172
     metrics.isIoBound() ? "I/O-bound" : "Mixed"));
173
```
174

175
**Thread-Specific Behavior:**
176

177
```java
178
// CPU time is thread-specific
179
public class ThreadCpuMonitor {
180
    public void demonstrateThreadSpecificity() {
181
        CpuTimeClock cpuClock = new CpuTimeClock();
182
        
183
        // Start background thread
184
        Thread backgroundThread = new Thread(() -> {
185
            long threadCpuStart = cpuClock.getTick();
186
            // CPU-intensive work in background
187
            burnCpu(1000);
188
            long threadCpuEnd = cpuClock.getTick();
189
            System.out.println("Background thread CPU time: " + 
190
                (threadCpuEnd - threadCpuStart) / 1_000_000.0 + " ms");
191
        });
192
        
193
        backgroundThread.start();
194
        
195
        // Main thread CPU measurement (independent of background thread)
196
        long mainCpuStart = cpuClock.getTick();
197
        Thread.sleep(500); // This uses no CPU time
198
        long mainCpuEnd = cpuClock.getTick();
199
        
200
        System.out.println("Main thread CPU time during sleep: " + 
201
            (mainCpuEnd - mainCpuStart) / 1_000_000.0 + " ms"); // Should be near 0
202
        
203
        try {
204
            backgroundThread.join();
205
        } catch (InterruptedException e) {
206
            Thread.currentThread().interrupt();
207
        }
208
    }
209
}
210
```
211

212
**Platform Considerations:**
213

214
- **CPU Time Accuracy**: Depends on JVM and operating system implementation
215
- **Thread Support**: Requires ThreadMXBean support for CPU time measurement
216
- **Resolution**: Typically nanosecond resolution, but actual precision varies by platform
217
- **Overhead**: Minimal overhead for CPU time queries, suitable for production use
218

219
**Monitoring Use Cases:**
220

221
- **Performance Profiling**: Identify CPU vs. I/O bound operations
222
- **Resource Usage Analysis**: Measure actual CPU consumption vs. wall-clock time
223
- **Efficiency Metrics**: Calculate CPU utilization ratios for optimization
224
- **Comparative Analysis**: Compare algorithm performance based on CPU time rather than elapsed time