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