github.com/google/cadvisor@v0.49.1/docs/api.md (about)

     1  # cAdvisor Remote REST API
     2  
     3  cAdvisor exposes its raw and processed stats via a versioned remote REST API:
     4  
     5  `http://<hostname>:<port>/api/<version>/<request>`
     6  
     7  The current version of the API is `v1.3`.
     8  
     9  There is a beta release of the `v2.0` API [available](api_v2.md).
    10  
    11  ## Version 1.3
    12  
    13  This version exposes the same endpoints as `v1.2` with one additional read-only endpoint.
    14  
    15  ### Events
    16  
    17  The resource name for Docker container information is as follows:
    18  
    19  `/api/v1.3/events/<absolute container name>`
    20  
    21  Querying the endpoint receives a list of events which are a serialized `Event` JSON objects (found in [info/v1/container.go](../info/v1/container.go)).
    22  
    23  The endpoint accepts a certain number of query parameters:
    24  
    25  | Parameter         | Description                                                                    | Default           |
    26  |-------------------|--------------------------------------------------------------------------------|-------------------|
    27  | `start_time`      | Start time of events to query (for stream=false)                               | Beginning of time |
    28  | `end_time`        | End time of events to query (for stream=false)                                 | Now               |
    29  | `stream`          | Whether to stream new events as they occur. If false returns historical events | false             |
    30  | `subcontainers`   | Whether to also return events for all subcontainers                            | false             |
    31  | `max_events`      | The max number of events to return (for stream=false)                          | 10                |
    32  | `all_events`      | Whether to include all supported event types                                   | false             |
    33  | `oom_events`      | Whether to include OOM events                                                  | false             |
    34  | `oom_kill_events` | Whether to include OOM kill events                                             | false             |
    35  | `creation_events` | Whether to include container creation events                                   | false             |
    36  | `deletion_events` | Whether to include container deletion events                                   | false             |
    37  
    38  ## Version 1.2
    39  
    40  This version exposes the same endpoints as `v1.1` with one additional read-only endpoint.
    41  
    42  ### Docker Container Information
    43  
    44  The resource name for Docker container information is as follows:
    45  
    46  `/api/v1.2/docker/<Docker container name or blank for all Docker containers>`
    47  
    48  The Docker name can be either the UUID or the short name of the container. It returns the information of the specified container(s). The information is returned as a list of serialized `ContainerInfo` JSON objects (found in [info/v1/container.go](../info/v1/container.go)).
    49  
    50  ## Version 1.1
    51  
    52  This version exposes the same endpoints as `v1.0` with one additional read-only endpoint.
    53  
    54  ### Subcontainer Information
    55  
    56  The resource name for subcontainer information is as follows:
    57  
    58  `/api/v1.1/subcontainers/<absolute container name>`
    59  
    60  Where the absolute container name follows the lmctfy naming convention (described bellow). It returns the information of the specified container and all subcontainers (recursively). The information is returned as a list of serialized `ContainerInfo` JSON objects (found in [info/v1/container.go](../info/v1/container.go)).
    61  
    62  ## Version 1.0
    63  
    64  This version exposes two main endpoints, one for container information and the other for machine information. Both endpoints are read-only in v1.0.
    65  
    66  ### Container Information
    67  
    68  The resource name for container information is as follows:
    69  
    70  `/api/v1.0/containers/<absolute container name>`
    71  
    72  Where the absolute container name follows the lmctfy naming convention. For example:
    73  
    74  | Container Name       | Resource Name                             |
    75  |----------------------|-------------------------------------------|
    76  | /                    | /api/v1.0/containers/                     |
    77  | /foo                 | /api/v1.0/containers/foo                  |
    78  | /docker/2c4dee605d22 | /api/v1.0/containers/docker/2c4dee605d22  |
    79  
    80  Note that the root container (`/`) contains usage for the entire machine. All Docker containers are listed under `/docker`.
    81  
    82  The container information is returned as a JSON object containing:
    83  
    84  - Absolute container name
    85  - List of subcontainers
    86  - ContainerSpec which describes the resource isolation enabled in the container
    87  - Detailed resource usage statistics of the container for the last `N` seconds (`N` is globally configurable in cAdvisor)
    88  - Histogram of resource usage from the creation of the container
    89  
    90  The actual object is the marshalled JSON of the `ContainerInfo` struct found in [info/v1/container.go](../info/v1/container.go)
    91  
    92  ### Machine Information
    93  
    94  The resource name for machine information is as follows:
    95  
    96  `/api/vX.Y/machine`
    97  
    98  This resource is read-only. The machine information is returned as a JSON object containing:
    99  
   100  - Number of schedulable logical CPU cores
   101  - Memory capacity (in bytes)
   102  - Maximum supported CPU frequency (in kHz)
   103  - Available filesystems: major, minor numbers and capacity (in bytes)
   104  - Network devices: mac addresses, MTU, and speed (if available)
   105  - Machine topology: Nodes, cores, threads, per-node memory, and caches
   106  
   107  The actual object is the marshalled JSON of the `MachineInfo` struct found in [info/v1/machine.go](../info/v1/machine.go)