108 lines
5.2 KiB
Markdown
108 lines
5.2 KiB
Markdown
# cAdvisor Remote REST API
|
|
|
|
cAdvisor exposes its raw and processed stats via a versioned remote REST API:
|
|
|
|
`http://<hostname>:<port>/api/<version>/<request>`
|
|
|
|
The current version of the API is `v1.3`.
|
|
|
|
There is a beta release of the `v2.0` API [available](api_v2.md).
|
|
|
|
## Version 1.3
|
|
|
|
This version exposes the same endpoints as `v1.2` with one additional read-only endpoint.
|
|
|
|
### Events
|
|
|
|
The resource name for Docker container information is as follows:
|
|
|
|
`/api/v1.3/events/<absolute container name>`
|
|
|
|
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)).
|
|
|
|
The endpoint accepts a certain number of query parameters:
|
|
|
|
| Parameter | Description | Default |
|
|
|-------------------|--------------------------------------------------------------------------------|-------------------|
|
|
| `start_time` | Start time of events to query (for stream=false) | Beginning of time |
|
|
| `end_time` | End time of events to query (for stream=false) | Now |
|
|
| `stream` | Whether to stream new events as they occur. If false returns historical events | false |
|
|
| `subcontainers` | Whether to also return events for all subcontainers | false |
|
|
| `max_events` | The max number of events to return (for stream=false) | 10 |
|
|
| `all_events` | Whether to include all supported event types | false |
|
|
| `oom_events` | Whether to include OOM events | false |
|
|
| `oom_kill_events` | Whether to include OOM kill events | false |
|
|
| `creation_events` | Whether to include container creation events | false |
|
|
| `deletion_events` | Whether to include container deletion events | false |
|
|
|
|
## Version 1.2
|
|
|
|
This version exposes the same endpoints as `v1.1` with one additional read-only endpoint.
|
|
|
|
### Docker Container Information
|
|
|
|
The resource name for Docker container information is as follows:
|
|
|
|
`/api/v1.2/docker/<Docker container name or blank for all Docker containers>`
|
|
|
|
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)).
|
|
|
|
## Version 1.1
|
|
|
|
This version exposes the same endpoints as `v1.0` with one additional read-only endpoint.
|
|
|
|
### Subcontainer Information
|
|
|
|
The resource name for subcontainer information is as follows:
|
|
|
|
`/api/v1.1/subcontainers/<absolute container name>`
|
|
|
|
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)).
|
|
|
|
## Version 1.0
|
|
|
|
This version exposes two main endpoints, one for container information and the other for machine information. Both endpoints are read-only in v1.0.
|
|
|
|
### Container Information
|
|
|
|
The resource name for container information is as follows:
|
|
|
|
`/api/v1.0/containers/<absolute container name>`
|
|
|
|
Where the absolute container name follows the lmctfy naming convention. For example:
|
|
|
|
| Container Name | Resource Name |
|
|
|----------------------|-------------------------------------------|
|
|
| / | /api/v1.0/containers/ |
|
|
| /foo | /api/v1.0/containers/foo |
|
|
| /docker/2c4dee605d22 | /api/v1.0/containers/docker/2c4dee605d22 |
|
|
|
|
Note that the root container (`/`) contains usage for the entire machine. All Docker containers are listed under `/docker`.
|
|
|
|
The container information is returned as a JSON object containing:
|
|
|
|
- Absolute container name
|
|
- List of subcontainers
|
|
- ContainerSpec which describes the resource isolation enabled in the container
|
|
- Detailed resource usage statistics of the container for the last `N` seconds (`N` is globally configurable in cAdvisor)
|
|
- Histogram of resource usage from the creation of the container
|
|
|
|
The actual object is the marshalled JSON of the `ContainerInfo` struct found in [info/v1/container.go](../info/v1/container.go)
|
|
|
|
### Machine Information
|
|
|
|
The resource name for machine information is as follows:
|
|
|
|
`/api/vX.Y/machine`
|
|
|
|
This resource is read-only. The machine information is returned as a JSON object containing:
|
|
|
|
- Number of schedulable logical CPU cores
|
|
- Memory capacity (in bytes)
|
|
- Maximum supported CPU frequency (in kHz)
|
|
- Available filesystems: major, minor numbers and capacity (in bytes)
|
|
- Network devices: mac addresses, MTU, and speed (if available)
|
|
- Machine topology: Nodes, cores, threads, per-node memory, and caches
|
|
|
|
The actual object is the marshalled JSON of the `MachineInfo` struct found in [info/v1/machine.go](../info/v1/machine.go)
|