0
# Metrics Query API
1

2
REST-based metrics querying system providing HTTP endpoints for searching tags, querying time series data, and executing batch queries across the CDAP metrics storage system.
3

4
## Capabilities
5

6
### MetricsQueryService
7

8
Main HTTP service for metrics querying with service discovery registration, providing the foundation for metrics REST API endpoints.
9

10
```java { .api }
11
/**
12
 * HTTP service for metrics querying with service discovery registration
13
 * Manages lifecycle of metrics query endpoints and integrates with CDAP service discovery
14
 */
15
public class MetricsQueryService extends AbstractIdleService {
16
    /**
17
     * Starts the metrics query HTTP service
18
     * @throws Exception if service startup fails
19
     */
20
    protected void startUp() throws Exception;
21
    
22
    /**
23
     * Stops the metrics query HTTP service
24
     * @throws Exception if service shutdown fails  
25
     */
26
    protected void shutDown() throws Exception;
27
}
28
```
29

30
### MetricsHandler
31

32
REST endpoint handler providing HTTP endpoints for metrics search and query operations.
33

34
```java { .api }
35
/**
36
 * REST endpoint handler for metrics operations
37
 * Provides HTTP endpoints for searching tags/metrics and querying metrics data
38
 */
39
public class MetricsHandler extends AbstractHttpHandler {
40
    // REST endpoints handled by this class:
41
    // POST /v3/metrics/search - Search for tags or metrics
42
    // POST /v3/metrics/query - Query metrics data (batch and single queries)
43
    // GET /v3/metrics/processor/status - Get metrics processor status
44
}
45
```
46

47
**REST Endpoints:**
48

49
- `POST /v3/metrics/search` - Search for available tags or metrics
50
- `POST /v3/metrics/query` - Execute metrics queries (supports both single and batch queries)
51
- `GET /v3/metrics/processor/status` - Get current metrics processor status
52

53
### Exception Handling
54

55
```java { .api }
56
/**
57
 * Exception thrown when metrics REST API path parsing fails
58
 * Indicates malformed or invalid request paths in metrics endpoints
59
 */
60
public class MetricsPathException extends Exception {
61
    /**
62
     * Create exception with error message
63
     * @param message Description of the path parsing error
64
     */
65
    public MetricsPathException(String message);
66
    
67
    /**
68
     * Create exception with error message and cause
69
     * @param message Description of the path parsing error
70
     * @param cause Underlying exception that caused this error
71
     */
72
    public MetricsPathException(String message, Throwable cause);
73
}
74
```
75

76
## Usage
77

78
The metrics query API is primarily accessed through HTTP requests to the MetricsQueryService. The service provides REST endpoints for:
79

80
1. **Tag and Metric Discovery**: Use `POST /v3/metrics/search` to discover available tags and metrics
81
2. **Data Querying**: Use `POST /v3/metrics/query` to execute time series and aggregate queries
82
3. **Status Monitoring**: Use `GET /v3/metrics/processor/status` to check metrics processing status
83

84
**Example HTTP Usage:**
85

86
```bash
87
# Search for available metrics
88
curl -X POST "http://localhost:11015/v3/metrics/search" \
89
  -H "Content-Type: application/json" \
90
  -d '{"tags": ["namespace", "app"]}'
91

92
# Query metrics data
93
curl -X POST "http://localhost:11015/v3/metrics/query" \
94
  -H "Content-Type: application/json" \
95
  -d '{
96
    "tags": {"namespace": "myNamespace", "app": "myApp"}, 
97
    "metrics": ["system.cpu.usage"],
98
    "timeRange": {"start": "now-1h", "end": "now"}
99
  }'
100
```
101

102
## Constants
103

104
```java { .api }
105
// Common query constants from internal MetricsQueryHelper
106
public static final String NAMESPACE_STRING = "namespace";
107
public static final String APP_STRING = "app";
108
```