From 1ffc949c1e17bf0fe17727bdcb1a4ab84d2b4a07 Mon Sep 17 00:00:00 2001 From: pouchrobot Date: Wed, 22 Aug 2018 03:06:43 +0000 Subject: [PATCH] docs: auto generate pouch cli docs via code Signed-off-by: pouchrobot --- docs/api/HTTP_API.md | 214 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 212 insertions(+), 2 deletions(-) diff --git a/docs/api/HTTP_API.md b/docs/api/HTTP_API.md index 564b2afd4..50227907c 100644 --- a/docs/api/HTTP_API.md +++ b/docs/api/HTTP_API.md @@ -588,8 +588,8 @@ POST /containers/{id}/resize |Type|Name|Description|Schema| |---|---|---|---| |**Path**|**id**
*required*|ID or name of the container|string| -|**Query**|**height**
*optional*|height of the tty|string| -|**Query**|**width**
*optional*|width of the tty|string| +|**Query**|**h**
*optional*|height of the tty|string| +|**Query**|**w**
*optional*|width of the tty|string| #### Responses @@ -598,6 +598,8 @@ POST /containers/{id}/resize |---|---|---| |**200**|no error|No Content| |**400**|bad parameter|[Error](#error)| +|**404**|An unexpected 404 error occurred.|[Error](#error)| +|**500**|An unexpected server error occurred.|[Error](#error)| #### Tags @@ -667,6 +669,53 @@ POST /containers/{id}/start * Container + +### Get container stats based on resource usage +``` +GET /containers/{id}/stats +``` + + +#### Description +This endpoint returns a live stream of a container’s resource usage +statistics. + +The `precpu_stats` is the CPU statistic of the *previous* read, and is +used to calculate the CPU usage percentage. It is not an exact copy +of the `cpu_stats` field. + +If either `precpu_stats.online_cpus` or `cpu_stats.online_cpus` is +nil then for compatibility with older daemons the length of the +corresponding `cpu_usage.percpu_usage` array should be used. + + +#### Parameters + +|Type|Name|Description|Schema|Default| +|---|---|---|---|---| +|**Path**|**id**
*required*|ID or name of the container|string|| +|**Query**|**stream**
*optional*|Stream the output. If false, the stats will be output once and then it will disconnect.|boolean|`"true"`| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|container stats|[ContainerStats](#containerstats)| +|**404**|An unexpected 404 error occurred.|[Error](#error)| +|**500**|An unexpected server error occurred.|[Error](#error)| + + +#### Produces + +* `application/json` + + +#### Tags + +* Container + + ### Stop a container ``` @@ -958,6 +1007,37 @@ Return low-level information about an exec instance. * Exec + +### changes the size of the tty for an exec process +``` +POST /exec/{id}/resize +``` + + +#### Parameters + +|Type|Name|Description|Schema| +|---|---|---|---| +|**Path**|**id**
*required*|ID or name of the container|string| +|**Query**|**h**
*optional*|height of the tty|string| +|**Query**|**w**
*optional*|width of the tty|string| + + +#### Responses + +|HTTP Code|Description|Schema| +|---|---|---| +|**200**|no error|No Content| +|**400**|bad parameter|[Error](#error)| +|**404**|An unexpected 404 error occurred.|[Error](#error)| +|**500**|An unexpected server error occurred.|[Error](#error)| + + +#### Tags + +* Exec + + ### Start an exec instance ``` @@ -1786,6 +1866,62 @@ The response returned by login to a registry |**Status**
*required*|The status of the authentication|string| + +### BlkioStatEntry +BlkioStatEntry is one small entity to store a piece of Blkio stats + + +|Name|Schema| +|---|---| +|**major**
*optional*|integer (uint64)| +|**minor**
*optional*|integer (uint64)| +|**op**
*optional*|string| +|**value**
*optional*|integer (uint64)| + + + +### BlkioStats +BlkioStats stores All IO service stats for data read and write. + + +|Name|Schema| +|---|---| +|**io_merged_recursive**
*optional*|< [BlkioStatEntry](#blkiostatentry) > array| +|**io_queue_recursive**
*optional*|< [BlkioStatEntry](#blkiostatentry) > array| +|**io_service_bytes_recursive**
*optional*|< [BlkioStatEntry](#blkiostatentry) > array| +|**io_service_time_recursive**
*optional*|< [BlkioStatEntry](#blkiostatentry) > array| +|**io_serviced_recursive**
*optional*|< [BlkioStatEntry](#blkiostatentry) > array| +|**io_time_recursive**
*optional*|< [BlkioStatEntry](#blkiostatentry) > array| +|**io_wait_time_recursive**
*optional*|< [BlkioStatEntry](#blkiostatentry) > array| +|**sectors_recursive**
*optional*|< [BlkioStatEntry](#blkiostatentry) > array| + + + +### CPUStats +CPUStats aggregates and wraps all CPU related info of container + + +|Name|Description|Schema| +|---|---|---| +|**cpu_usage**
*optional*||[CPUUsage](#cpuusage)| +|**online_cpus**
*optional*|onine CPUs|integer (uint32)| +|**syetem_cpu_usage**
*optional*|System CPU Usage|integer (uint64)| +|**throttling_data**
*optional*||[ThrottlingData](#throttlingdata)| + + + +### CPUUsage +CPUUsage stores All CPU stats aggregated since container inception. + + +|Name|Description|Schema| +|---|---|---| +|**percpu_usage**
*optional*|Total CPU time consumed per core (Linux).|< integer (uint64) > array| +|**total_usage**
*optional*|Total CPU time consumed.|integer (uint64)| +|**usage_in_kernelmode**
*optional*|Time spent by tasks of the cgroup in kernel mode (Linux).
Units, nanoseconds (Linux)|integer (uint64)| +|**usage_in_usermode**
*optional*|Time spent by tasks of the cgroup in user mode (Linux).
Units, nanoseconds (Linux)|integer (uint64)| + + ### Checkpoint describe a created checkpoint, include container name and checkpoint name @@ -2112,6 +2248,24 @@ options of starting container |**Status**
*optional*||[Status](#status)| + +### ContainerStats +container stats almost from cgroup resource usage. + + +|Name|Description|Schema| +|---|---|---| +|**blkio_stats**
*optional*||[BlkioStats](#blkiostats)| +|**cpu_stats**
*optional*||[CPUStats](#cpustats)| +|**id**
*optional*|container id|string| +|**memory_stats**
*optional*||[MemoryStats](#memorystats)| +|**name**
*optional*|container name|string| +|**networks**
*optional*||< string, [NetworkStats](#networkstats) > map| +|**pids_stats**
*optional*||[PidsStats](#pidsstats)| +|**precpu_stats**
*optional*||[CPUStats](#cpustats)| +|**read**
*optional*|read time of container stats.|string (date-time)| + + ### ContainerUpgradeConfig ContainerUpgradeConfig is used for API "POST /containers/upgrade". @@ -2518,6 +2672,20 @@ The logging configuration for this container |**Type**
*optional*|enum (json-file, syslog, journald, gelf, fluentd, awslogs, splunk, etwlogs, none)| + +### MemoryStats +MemoryStats aggregates all memory stats since container inception on Linux. + + +|Name|Description|Schema| +|---|---|---| +|**failcnt**
*optional*|number of times memory usage hits limits.|integer (uint64)| +|**limit**
*optional*|xxx|integer (uint64)| +|**max_usage**
*optional*|maximum usage ever recorded.|integer (uint64)| +|**stats**
*optional*|all the stats exported via memory.stat.|< string, integer (uint64) > map| +|**usage**
*optional*|current res_counter usage for memory|integer (uint64)| + + ### MountPoint A mount point inside a container @@ -2664,6 +2832,25 @@ NetworkSettings exposes the network settings in the API. |**SecondaryIPv6Addresses**
*optional*||< [IPAddress](#ipaddress) > array| + +### NetworkStats +container stats almost from cgroup resource usage. + + +|Name|Description|Schema| +|---|---|---| +|**endpoint_id**
*optional*|Endpoint ID.|string| +|**instance_id**
*optional*|Instance ID.|string| +|**rx_bytes**
*optional*|Bytes received.|integer (uint64)| +|**rx_dropped**
*optional*|Incoming packets dropped.|integer (uint64)| +|**rx_errors**
*optional*|Received errors.|integer (uint64)| +|**rx_packets**
*optional*|Packets received.|integer (uint64)| +|**tx_bytes**
*optional*|Bytes sent.|integer (uint64)| +|**tx_dropped**
*optional*|Outgoing packets dropped.|integer (uint64)| +|**tx_errors**
*optional*|Sent errors.|integer (uint64)| +|**tx_packets**
*optional*|Packets sent.|integer (uint64)| + + ### NetworkingConfig Configuration for a network used to create a container. @@ -2680,6 +2867,17 @@ Configuration for a network used to create a container. |**NvidiaVisibleDevices**
*optional*|NvidiaVisibleDevices controls which GPUs will be made accessible inside the container
**Example** : `"Possible values.\n0,1,2, GPU-fef8089b …: a comma-separated list of GPU UUID(s) or index(es).\nall: all GPUs will be accessible, this is the default value in our container images.\nnone: no GPU will be accessible, but driver capabilities will be enabled.\n"`|string| + +### PidsStats +PidsStats contains the stats of a container's pids + + +|Name|Description|Schema| +|---|---|---| +|**current**
*optional*|Current is the number of pids in the cgroup|integer (uint64)| +|**limit**
*optional*|Limit is the hard limit on the number of pids in the cgroup.
A "Limit" of 0 means that there is no limit.|integer (uint64)| + + ### PortBinding PortBinding represents a binding between a host IP address and a host port @@ -2913,6 +3111,18 @@ The status of the container. For example, "running" or "exited". |**Rate**
*optional*|Rate
**Minimum value** : `0`|integer (uint64)| + +### ThrottlingData +ThrottlingData stores CPU throttling stats of one running container. + + +|Name|Description|Schema| +|---|---|---| +|**periods**
*optional*|Number of periods with throttling active.|integer (uint64)| +|**throttled_periods**
*optional*|Number of periods when the container hits its throttling limit.|integer (uint64)| +|**throttled_time**
*optional*|Aggregate time the container was throttled for in nanoseconds.|integer (uint64)| + + ### Ulimit A list of resource limits