0
# Metrics Collection API
1

2
Interfaces and implementations for collecting and emitting metrics data, supporting counter, gauge, and distribution metrics with aggregation capabilities and integration with CDAP's metrics processing pipeline.
3

4
## Capabilities
5

6
### MetricsEmitter Interface
7

8
Core interface for metric emission, defining the contract for classes that emit MetricValue objects.
9

10
```java { .api }
11
/**
12
 * Interface for classes that emit MetricValue objects
13
 * Defines the contract for metric emission at specific timestamps
14
 */
15
public interface MetricsEmitter {
16
    /**
17
     * Emit a MetricValue for the current or specified timestamp
18
     * @return MetricValue containing the current metric data
19
     */
20
    MetricValue emit();
21
}
22
```
23

24
### AggregatedMetricsEmitter
25

26
Concrete implementation that aggregates metric values during collection and emits aggregated values, supporting multiple metric types with thread-safe operations.
27

28
```java { .api }
29
/**
30
 * Aggregates metric values during collection and emits aggregated values
31
 * Thread-safe implementation supporting counter, gauge, and distribution metrics
32
 */
33
public final class AggregatedMetricsEmitter implements MetricsEmitter {
34
    /**
35
     * Create emitter for a specific metric
36
     * @param name Name of the metric to emit
37
     */
38
    public AggregatedMetricsEmitter(String name);
39
    
40
    /**
41
     * Increment counter metric by the specified value
42
     * Thread-safe operation that adds to the current counter value
43
     * @param incrementValue Amount to increment the counter (must be positive)
44
     */
45
    public void increment(long incrementValue);
46
    
47
    /**
48
     * Set gauge metric to the specified value
49
     * Thread-safe operation that sets the current gauge value
50
     * @param value New gauge value (can be any long value)
51
     */
52
    public void gauge(long value);
53
    
54
    /**
55
     * Add event to distribution metric
56
     * Thread-safe operation that records an event for distribution calculation
57
     * @param value Event value to add to the distribution
58
     */
59
    public void event(long value);
60
    
61
    /**
62
     * Emit current aggregated metric value
63
     * Returns the current aggregated state and optionally resets internal counters
64
     * @return MetricValue containing aggregated metric data
65
     */
66
    public MetricValue emit();
67
}
68
```
69

70
**Usage Examples:**
71

72
```java
73
import io.cdap.cdap.metrics.collect.AggregatedMetricsEmitter;
74
import io.cdap.cdap.api.metrics.MetricValue;
75

76
// Counter metric example
77
AggregatedMetricsEmitter counterEmitter = new AggregatedMetricsEmitter("requests.count");
78
counterEmitter.increment(1);        // Increment by 1
79
counterEmitter.increment(5);        // Increment by 5  
80
MetricValue counterValue = counterEmitter.emit();  // Get aggregated count (6)
81

82
// Gauge metric example  
83
AggregatedMetricsEmitter gaugeEmitter = new AggregatedMetricsEmitter("memory.usage");
84
gaugeEmitter.gauge(1024);          // Set current memory usage
85
gaugeEmitter.gauge(2048);          // Update memory usage (overwrites previous)
86
MetricValue gaugeValue = gaugeEmitter.emit();      // Get current gauge value (2048)
87

88
// Distribution metric example
89
AggregatedMetricsEmitter distEmitter = new AggregatedMetricsEmitter("response.time");
90
distEmitter.event(100);            // Record response time of 100ms
91
distEmitter.event(250);            // Record response time of 250ms  
92
distEmitter.event(150);            // Record response time of 150ms
93
MetricValue distValue = distEmitter.emit();        // Get distribution statistics
94
```
95

96
### Distribution
97

98
Data model for distribution metrics that handles histogram-type metrics with statistical aggregation including count, sum, min, max, and percentiles.
99

100
```java { .api }
101
/**
102
 * Handles distribution/histogram type metrics with statistical aggregation
103
 * Maintains statistical information about a series of events
104
 */
105
public class Distribution {
106
    /**
107
     * Create empty distribution
108
     */
109
    public Distribution();
110
    
111
    /**
112
     * Add a value to the distribution
113
     * @param value Numeric value to add to the distribution
114
     */
115
    public void add(long value);
116
    
117
    /**
118
     * Get the count of values in the distribution
119
     * @return Number of values added to this distribution
120
     */
121
    public long getCount();
122
    
123
    /**
124
     * Get the sum of all values in the distribution
125
     * @return Sum of all values added to this distribution
126
     */
127
    public long getSum();
128
    
129
    /**
130
     * Get the minimum value in the distribution
131
     * @return Minimum value, or Long.MAX_VALUE if no values added
132
     */
133
    public long getMin();
134
    
135
    /**
136
     * Get the maximum value in the distribution  
137
     * @return Maximum value, or Long.MIN_VALUE if no values added
138
     */
139
    public long getMax();
140
    
141
    /**
142
     * Calculate the mean/average of values in the distribution
143
     * @return Mean value, or 0.0 if no values added
144
     */
145
    public double getMean();
146
    
147
    /**
148
     * Get percentile value from the distribution
149
     * @param percentile Percentile to calculate (0.0 to 1.0)
150
     * @return Value at the specified percentile
151
     */
152
    public long getPercentile(double percentile);
153
    
154
    /**
155
     * Reset distribution to empty state
156
     * Clears all accumulated values and statistics
157
     */
158
    public void reset();
159
}
160
```
161

162
**Usage Examples:**
163

164
```java
165
import io.cdap.cdap.metrics.collect.Distribution;
166

167
// Create and populate distribution
168
Distribution responseTimeDistribution = new Distribution();
169

170
// Add response times (in milliseconds)  
171
responseTimeDistribution.add(100);
172
responseTimeDistribution.add(150);
173
responseTimeDistribution.add(200);
174
responseTimeDistribution.add(75);
175
responseTimeDistribution.add(300);
176

177
// Get statistics
178
System.out.println("Count: " + responseTimeDistribution.getCount());         // 5
179
System.out.println("Sum: " + responseTimeDistribution.getSum());             // 825
180
System.out.println("Min: " + responseTimeDistribution.getMin());             // 75
181
System.out.println("Max: " + responseTimeDistribution.getMax());             // 300
182
System.out.println("Mean: " + responseTimeDistribution.getMean());           // 165.0
183
System.out.println("95th percentile: " + responseTimeDistribution.getPercentile(0.95)); // ~300
184

185
// Reset for next measurement period
186
responseTimeDistribution.reset();
187
```
188

189
### Service Integration
190

191
Classes for integrating metrics collection with CDAP's service lifecycle and messaging systems.
192

193
```java { .api }
194
/**
195
 * Service manager for metrics collection services lifecycle management
196
 */
197
public class MetricsServiceManager extends AbstractIdleService {
198
    /**
199
     * Start metrics collection services
200
     * @throws Exception if startup fails
201
     */
202
    protected void startUp() throws Exception;
203
    
204
    /**
205
     * Stop metrics collection services  
206
     * @throws Exception if shutdown fails
207
     */
208
    protected void shutDown() throws Exception;
209
}
210

211
/**
212
 * Message envelope for administrative operations on metrics
213
 * Used for system maintenance and metrics deletion operations
214
 */
215
public final class MetricsAdminMessage {
216
    /**
217
     * Get the message type
218
     * @return Type of administrative operation
219
     */
220
    public Type getType();
221
    
222
    /**
223
     * Get the message payload with specified type
224
     * @param gson Gson instance for deserialization
225
     * @param type Target type for payload deserialization  
226
     * @return Deserialized payload object
227
     */
228
    public <T> T getPayload(Gson gson, Type type);
229
    
230
    /**
231
     * Types of administrative messages
232
     */
233
    public enum Type {
234
        /** Message indicating metric deletion operation */
235
        DELETE
236
    }
237
}
238

239
/**
240
 * Enumeration of metrics entity types for categorization
241
 */
242
public enum MetricsEntityType {
243
    /** Context entity type */
244
    CONTEXT("c"),
245
    /** Run entity type */  
246
    RUN("r"),
247
    /** Metric entity type */
248
    METRIC("m"),  
249
    /** Tag entity type */
250
    TAG("t");
251
    
252
    /**
253
     * Get the single-character identifier for this entity type
254
     * @return Single character identifier
255
     */
256
    public String getId();
257
}
258
```