Metrics Collection API

/**
 * Interface for classes that emit MetricValue objects
 * Defines the contract for metric emission at specific timestamps
 */
public interface MetricsEmitter {
    /**
     * Emit a MetricValue for the current or specified timestamp
     * @return MetricValue containing the current metric data
     */
    MetricValue emit();
}

/**
 * Aggregates metric values during collection and emits aggregated values
 * Thread-safe implementation supporting counter, gauge, and distribution metrics
 */
public final class AggregatedMetricsEmitter implements MetricsEmitter {
    /**
     * Create emitter for a specific metric
     * @param name Name of the metric to emit
     */
    public AggregatedMetricsEmitter(String name);
    
    /**
     * Increment counter metric by the specified value
     * Thread-safe operation that adds to the current counter value
     * @param incrementValue Amount to increment the counter (must be positive)
     */
    public void increment(long incrementValue);
    
    /**
     * Set gauge metric to the specified value
     * Thread-safe operation that sets the current gauge value
     * @param value New gauge value (can be any long value)
     */
    public void gauge(long value);
    
    /**
     * Add event to distribution metric
     * Thread-safe operation that records an event for distribution calculation
     * @param value Event value to add to the distribution
     */
    public void event(long value);
    
    /**
     * Emit current aggregated metric value
     * Returns the current aggregated state and optionally resets internal counters
     * @return MetricValue containing aggregated metric data
     */
    public MetricValue emit();
}

import io.cdap.cdap.metrics.collect.AggregatedMetricsEmitter;
import io.cdap.cdap.api.metrics.MetricValue;

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

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

// Distribution metric example
AggregatedMetricsEmitter distEmitter = new AggregatedMetricsEmitter("response.time");
distEmitter.event(100);            // Record response time of 100ms
distEmitter.event(250);            // Record response time of 250ms  
distEmitter.event(150);            // Record response time of 150ms
MetricValue distValue = distEmitter.emit();        // Get distribution statistics

/**
 * Handles distribution/histogram type metrics with statistical aggregation
 * Maintains statistical information about a series of events
 */
public class Distribution {
    /**
     * Create empty distribution
     */
    public Distribution();
    
    /**
     * Add a value to the distribution
     * @param value Numeric value to add to the distribution
     */
    public void add(long value);
    
    /**
     * Get the count of values in the distribution
     * @return Number of values added to this distribution
     */
    public long getCount();
    
    /**
     * Get the sum of all values in the distribution
     * @return Sum of all values added to this distribution
     */
    public long getSum();
    
    /**
     * Get the minimum value in the distribution
     * @return Minimum value, or Long.MAX_VALUE if no values added
     */
    public long getMin();
    
    /**
     * Get the maximum value in the distribution  
     * @return Maximum value, or Long.MIN_VALUE if no values added
     */
    public long getMax();
    
    /**
     * Calculate the mean/average of values in the distribution
     * @return Mean value, or 0.0 if no values added
     */
    public double getMean();
    
    /**
     * Get percentile value from the distribution
     * @param percentile Percentile to calculate (0.0 to 1.0)
     * @return Value at the specified percentile
     */
    public long getPercentile(double percentile);
    
    /**
     * Reset distribution to empty state
     * Clears all accumulated values and statistics
     */
    public void reset();
}

import io.cdap.cdap.metrics.collect.Distribution;

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

// Add response times (in milliseconds)  
responseTimeDistribution.add(100);
responseTimeDistribution.add(150);
responseTimeDistribution.add(200);
responseTimeDistribution.add(75);
responseTimeDistribution.add(300);

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

// Reset for next measurement period
responseTimeDistribution.reset();

/**
 * Service manager for metrics collection services lifecycle management
 */
public class MetricsServiceManager extends AbstractIdleService {
    /**
     * Start metrics collection services
     * @throws Exception if startup fails
     */
    protected void startUp() throws Exception;
    
    /**
     * Stop metrics collection services  
     * @throws Exception if shutdown fails
     */
    protected void shutDown() throws Exception;
}

/**
 * Message envelope for administrative operations on metrics
 * Used for system maintenance and metrics deletion operations
 */
public final class MetricsAdminMessage {
    /**
     * Get the message type
     * @return Type of administrative operation
     */
    public Type getType();
    
    /**
     * Get the message payload with specified type
     * @param gson Gson instance for deserialization
     * @param type Target type for payload deserialization  
     * @return Deserialized payload object
     */
    public <T> T getPayload(Gson gson, Type type);
    
    /**
     * Types of administrative messages
     */
    public enum Type {
        /** Message indicating metric deletion operation */
        DELETE
    }
}

/**
 * Enumeration of metrics entity types for categorization
 */
public enum MetricsEntityType {
    /** Context entity type */
    CONTEXT("c"),
    /** Run entity type */  
    RUN("r"),
    /** Metric entity type */
    METRIC("m"),  
    /** Tag entity type */
    TAG("t");
    
    /**
     * Get the single-character identifier for this entity type
     * @return Single character identifier
     */
    public String getId();
}