github.com/mrgossett/heapster@v0.18.2/docs/model.md (about) 1 # Heapster Metric Model 2 3 The Heapster Model is a structured representation of metrics for Kubernetes clusters, which is exposed through a set of REST API endpoints. 4 It allows the extraction of up to 1 hour of historical data for any Container, Pod, Node or Namespace in the cluster, as well as the cluster itself. 5 The model can also export the Average, Max and 95th Percentile for each one of these entities, over a duration of 1 minute, 1 hour or 24 hours. 6 7 8 NOTICE: this document represents the state of the model at the next Heapster release, and is not representative of the current state of the master branch 9 TODO(afein): remove NOTICE prior to next release 10 11 ## Usage 12 13 The Heapster Model can be enabled by initializing Heapster with the `-use_model=true` flag. The resolution of the model can be configured through 14 the `-model_resolution` flag, which will cause the model to store historical data at the specified resolution. If the `model_resolution` flag is not specified, the default 15 resolution of 1 minute will be used. 16 17 ## API documentation 18 19 A detailed documentation of each API endpoint is listed below. 20 21 All endpoints ending in `/metrics/{metric-name}` can accept the optional `start` and `end` query parameters 22 that represent the start and end time of the requested timeseries. The result 23 will be a list of (Timestamp, Value) pairs in the time range (start, end]. 24 `start` and `end` are strings formatted according to RFC3339. If `start` is not 25 defined, it is assumed as the zero Unix epoch time. If `end` is not defined, 26 then all data later than `start` will be returned. 27 28 ### Cluster-level Metrics and Stats 29 `/api/v1/model/`: The root path of the model API, displays all browsable subpaths. 30 31 `/api/v1/model/metrics/`: Returns a list of available cluster-level metrics. 32 33 `/api/v1/model/metrics/{metric-name}?start=X&end=Y`: Returns a set of (Timestamp, Value) 34 pairs for the requested cluster-level metric, between the time range specified by `start` and `end`. 35 36 `/api/v1/model/stats/`: Exposes the average, max and 95th percentile over the 37 past minute, hour and day for each cluster metric. 38 39 ### Node-level Metrics and Stats 40 `/api/v1/model/nodes`: Returns a list of all available nodes, along 41 with their latest CPU and Memory Usage values. 42 43 `/api/v1/model/nodes/{node-name}`: Returns all browsable subpaths for a 44 specific node. 45 46 `/api/v1/model/nodes/{node-name}/pods`: Returns a list of all available pods 47 under a given node, along with their latest CPU and Memory Usage values 48 49 `/api/v1/model/nodes/{node-name}/metrics/`: Returns a list of available 50 node-level metrics 51 52 `/api/v1/model/metrics/nodes/{node-name}/{metric-name}?start=X&end=Y`: Returns a set of (Timestamp, Value) 53 pairs for the requested node-level metric, within the time range specified by `start` and `end`. 54 55 `/api/v1/model/nodes/{node-name}/stats/`: Exposes the average, max and 95th 56 percentile over the past minute, hour and day for each node metric 57 58 59 ### Namespace-level Metrics and Stats 60 `/api/v1/model/namespaces`: Returns a list of all available namespaces, along 61 with their latest CPU and Memory Usage values. 62 63 `/api/v1/model/namespaces/{namespace-name}`: Returns all browsable subpaths for 64 a specific namespace. 65 66 `/api/v1/model/namespaces/{namespace-name}/metrics/`: Returns a list of available namespace-level metrics 67 68 `/api/v1/model/namespaces/{namespace-name}/metrics/{metric-name}?start=X&end=Y`: Returns a set of (Timestamp, Value) 69 pairs for the requested namespace-level metric, within the time range specified by `start` and `end`. 70 71 `/api/v1/model/namespaces/{namespace-name}/stats/`: Exposes the average, max and 95th percentile over the 72 past minute, hour and day for each namespace metric. 73 74 75 ### Pod-level Metrics and Stats 76 `/api/v1/model/namespaces/{namespace-name}/pods`: Returns a list of all available pods under a given namespace, along 77 with their latest CPU and Memory Usage values. 78 79 `/api/v1/model/namespaces/{namespace-name}/pods/{pod-name}`: Returns all browsable subpaths for 80 a specific Pod. 81 82 `/api/v1/model/namespaces/{namespace-name}/pods/{pod-name}/metrics/`: Returns a list of available pod-level metrics 83 84 `/api/v1/model/namespaces/{namespace-name}/pods/{pod-name}/metrics/{metric-name}?start=X&end=Y`: Returns a set of (Timestamp, Value) 85 pairs for the requested pod-level metric, within the time range specified by `start` and `end`. 86 87 `/api/v1/model/namespaces/{namespace-name}/pods/{pod-name}/stats/`: Exposes the average, max and 95th percentile over the 88 past minute, hour and day for each pod-level metric. 89 90 91 ### Container-level Metrics and Stats 92 Container metrics and stats are accessible for both containers that belong to 93 pods, as well as for free containers running in each node. 94 95 `/api/v1/model/namespaces/{namespace-name}/pods/{pod-name}/containers`: Returns a list of all available containers under a given pod, along 96 with their latest CPU and Memory Usage values. 97 98 `/api/v1/model/namespaces/{namespace-name}/pods/{pod-name}/containers/{container-name}`: Returns all browsable subpaths for 99 a specific container. 100 101 `/api/v1/model/namespaces/{namespace-name}/pods/{pod-name}/containers/{container-name}/metrics/`: Returns a list of available container-level metrics 102 103 `/api/v1/model/namespaces/{namespace-name}/pods/{pod-name}/containers/{container-name}/metrics/{metric-name}?start=X&end=Y`: Returns a set of (Timestamp, Value) 104 pairs for the requested container-level metric, within the time range specified by `start` and `end`. 105 106 `/api/v1/model/namespaces/{namespace-name}/pods/{pod-name}/containers/{container-name}/stats/`: Exposes the average, max and 95th percentile over the 107 past minute, hour and day for each container metric. 108 109 `/api/v1/model/nodes/{node-name}/freecontainers`: Returns a list of all available free containers under a given node, along 110 with their latest CPU and Memory Usage values. 111 112 `/api/v1/model/nodes/{node-name}/freecontainers/{container-name}`: Returns all browsable subpaths for 113 a specific free container. 114 115 `/api/v1/model/nodes/{node-name}/freecontainers/{container-name}/metrics/`: Returns a list of available container-level metrics 116 117 `/api/v1/model/nodes/{node-name}/freecontainers/{container-name}/metrics/{metric-name}?start=X&end=Y`: Returns a set of (Timestamp, Value) 118 pairs for the requested container-level metric, within the time range specified by `start` and `end`. 119 120 `/api/v1/model/nodes/{node-name}/freecontainers/{container-name}/stats/`: Exposes the average, max and 95th percentile over the 121 past minute, hour and day for each container metric. 122