Skip to content

Latest commit

 

History

History
107 lines (66 loc) · 5.22 KB

api.md

File metadata and controls

107 lines (66 loc) · 5.22 KB
Raw

cAdvisor Remote REST API

cAdvisor exposes its raw and processed stats via a versioned remote REST API:

https://<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.

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).

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).

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).

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

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