diff options
Diffstat (limited to 'web/api/netdata-swagger.json')
| -rw-r--r-- | web/api/netdata-swagger.json | 283 |
1 files changed, 272 insertions, 11 deletions
diff --git a/web/api/netdata-swagger.json b/web/api/netdata-swagger.json index f09c8fe31..ed2555f83 100644 --- a/web/api/netdata-swagger.json +++ b/web/api/netdata-swagger.json @@ -9,7 +9,7 @@ "/info": { "get": { "summary": "Get netdata basic information", - "description": "The info endpoint returns basic information about netdata. It provides:\n* netdata version\n* netdata unique id\n* list of hosts mirrored (includes itself)\n* Operating System, Virtualization and Container technology information\n* List of active collector plugins and modules\n* number of alarms in the host\n * number of alarms in normal state\n * number of alarms in warning state\n * number of alarms in critical state\n", + "description": "The info endpoint returns basic information about netdata. It provides:\n* netdata version\n* netdata unique id\n* list of hosts mirrored (includes itself)\n* Operating System, Virtualization, K8s nodes and Container technology information\n* List of active collector plugins and modules\n* number of alarms in the host\n * number of alarms in normal state\n * number of alarms in warning state\n * number of alarms in critical state\n", "responses": { "200": { "description": "netdata basic information.", @@ -130,8 +130,8 @@ { "name": "chart", "in": "query", - "description": "The id of the chart as returned by the /charts call.", - "required": true, + "description": "The id of the chart as returned by the /charts call. Note chart or context must be specified", + "required": false, "allowEmptyValue": false, "schema": { "type": "string", @@ -140,6 +140,17 @@ } }, { + "name": "context", + "in": "query", + "description": "The context of the chart as returned by the /charts call. Note chart or context must be specified", + "required": false, + "allowEmptyValue": false, + "schema": { + "type": "string", + "format": "as returned by /charts" + } + }, + { "name": "dimension", "in": "query", "description": "Zero, one or more dimension ids or names, as returned by the /chart call, separated with comma or pipe. Netdata simple patterns are supported.", @@ -156,7 +167,7 @@ { "name": "after", "in": "query", - "description": "This parameter can either be an absolute timestamp specifying the starting point of the data to be returned, or a relative number of seconds (negative, relative to parameter: before). Netdata will assume it is a relative number if it is less that 3 years (in seconds). Netdata will adapt this parameter to the boundaries of the round robin database. The default is the beginning of the round robin database (i.e. by default netdata will attempt to return data for the entire database).", + "description": "This parameter can either be an absolute timestamp specifying the starting point of the data to be returned, or a relative number of seconds (negative, relative to parameter: before). Netdata will assume it is a relative number if it is less that 3 years (in seconds). If not specified the default is -600 seconds. Netdata will adapt this parameter to the boundaries of the round robin database unless the allow_past option is specified.", "required": true, "allowEmptyValue": false, "schema": { @@ -273,7 +284,8 @@ "unaligned", "match-ids", "match-names", - "showcustomvars" + "showcustomvars", + "allow_past" ] }, "default": [ @@ -328,7 +340,7 @@ "description": "Bad request - the body will include a message stating what is wrong." }, "404": { - "description": "No chart with the given id is found." + "description": "Chart or context is not found. The supplied chart or context will be reported." }, "500": { "description": "Internal server error. This usually means the server is out of memory." @@ -338,7 +350,7 @@ }, "/badge.svg": { "get": { - "summary": "Generate a SVG image for a chart (or dimension)", + "summary": "Generate a badge in form of SVG image for a chart (or dimension)", "description": "Successful responses are SVG images.", "parameters": [ { @@ -471,18 +483,38 @@ { "name": "label_color", "in": "query", - "description": "A color to be used for the background of the label.", + "description": "A color to be used for the background of the label side(left side) of the badge. One of predefined colors or specific color in hex `RGB` or `RRGGBB` format (without preceding `#` character). If value wrong or not given default color will be used.", "required": false, "allowEmptyValue": true, "schema": { - "type": "string", - "format": "any text" + "oneOf": [ + { + "type": "string", + "enum": [ + "green", + "brightgreen", + "yellow", + "yellowgreen", + "orange", + "red", + "blue", + "grey", + "gray", + "lightgrey", + "lightgray" + ] + }, + { + "type": "string", + "format": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" + } + ] } }, { "name": "value_color", "in": "query", - "description": "A color to be used for the background of the label. You can set multiple using a pipe with a condition each, like this: colorvalue|color:null The following operators are supported: >, <, >=, <=, =, :null (to check if no value exists).", + "description": "A color to be used for the background of the value *(right)* part of badge. You can set multiple using a pipe with a condition each, like this: `color<value|color:null` The following operators are supported: >, <, >=, <=, =, :null (to check if no value exists). Each color can be specified in same manner as for `label_color` parameter. Currently only integers are suported as values.", "required": false, "allowEmptyValue": true, "schema": { @@ -491,6 +523,68 @@ } }, { + "name": "text_color_lbl", + "in": "query", + "description": "Font color for label *(left)* part of the badge. One of predefined colors or as HTML hexadecimal color without preceeding `#` character. Formats allowed `RGB` or `RRGGBB`. If no or wrong value given default color will be used.", + "required": false, + "allowEmptyValue": true, + "schema": { + "oneOf": [ + { + "type": "string", + "enum": [ + "green", + "brightgreen", + "yellow", + "yellowgreen", + "orange", + "red", + "blue", + "grey", + "gray", + "lightgrey", + "lightgray" + ] + }, + { + "type": "string", + "format": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" + } + ] + } + }, + { + "name": "text_color_val", + "in": "query", + "description": "Font color for value *(right)* part of the badge. One of predefined colors or as HTML hexadecimal color without preceeding `#` character. Formats allowed `RGB` or `RRGGBB`. If no or wrong value given default color will be used.", + "required": false, + "allowEmptyValue": true, + "schema": { + "oneOf": [ + { + "type": "string", + "enum": [ + "green", + "brightgreen", + "yellow", + "yellowgreen", + "orange", + "red", + "blue", + "grey", + "gray", + "lightgrey", + "lightgray" + ] + }, + { + "type": "string", + "format": "^([0-9a-fA-F]{3}|[0-9a-fA-F]{6})$" + } + ] + } + }, + { "name": "multiply", "in": "query", "description": "Multiply the value with this number for rendering it at the image (integer value required).", @@ -522,6 +616,28 @@ "type": "number", "format": "integer" } + }, + { + "name": "fixed_width_lbl", + "in": "query", + "description": "This parameter overrides auto-sizing of badge and creates it with fixed width. This parameter determines the size of the label's left side *(label/name)*. You must set this parameter together with `fixed_width_val` otherwise it will be ignored. You should set the label/value widths wide enough to provide space for all the possible values/contents of the badge you're requesting. In case the text cannot fit the space given it will be clipped. The `scale` parameter still applies on the values you give to `fixed_width_lbl` and `fixed_width_val`.", + "required": false, + "allowEmptyValue": false, + "schema": { + "type": "number", + "format": "integer" + } + }, + { + "name": "fixed_width_val", + "in": "query", + "description": "This parameter overrides auto-sizing of badge and creates it with fixed width. This parameter determines the size of the label's right side *(value)*. You must set this parameter together with `fixed_width_lbl` otherwise it will be ignored. You should set the label/value widths wide enough to provide space for all the possible values/contents of the badge you're requesting. In case the text cannot fit the space given it will be clipped. The `scale` parameter still applies on the values you give to `fixed_width_lbl` and `fixed_width_val`.", + "required": false, + "allowEmptyValue": false, + "schema": { + "type": "number", + "format": "integer" + } } ], "responses": { @@ -562,6 +678,20 @@ } }, { + "name": "variables", + "in": "query", + "description": "When enabled, netdata will expose various system configuration metrics.", + "required": false, + "schema": { + "type": "string", + "enum": [ + "yes", + "no" + ], + "default": "no" + } + }, + { "name": "help", "in": "query", "description": "Enable or disable HELP lines in prometheus output.", @@ -705,6 +835,16 @@ "schema": { "type": "boolean" } + }, + { + "name": "active", + "in": "query", + "description": "If passed, the raised alarms in state WARNING or CRITICAL are returned.", + "required": false, + "allowEmptyValue": true, + "schema": { + "type": "boolean" + } } ], "responses": { @@ -721,6 +861,46 @@ } } }, + "/alarms_values": { + "get": { + "summary": "Get a list of active or raised alarms on the server", + "description": "The alarms_values endpoint returns the list of all raised or enabled alarms on the netdata server. Called without any parameters, the raised alarms in state WARNING or CRITICAL are returned. By passing \"?all\", all the enabled alarms are returned. This option output differs from `/alarms` in the number of variables delivered. This endpoint gives to user `id`, `value` and alarm `status`.", + "parameters": [ + { + "name": "all", + "in": "query", + "description": "If passed, all enabled alarms are returned.", + "required": false, + "allowEmptyValue": true, + "schema": { + "type": "boolean" + } + }, + { + "name": "active", + "in": "query", + "description": "If passed, the raised alarms in state WARNING or CRITICAL are returned.", + "required": false, + "allowEmptyValue": true, + "schema": { + "type": "boolean" + } + } + ], + "responses": { + "200": { + "description": "An object containing general info and a linked list of alarms.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/alarms_values" + } + } + } + } + } + } + }, "/alarm_log": { "get": { "summary": "Retrieves the entries of the alarm log", @@ -923,6 +1103,35 @@ "host2.example.com" ] }, + "mirrored_hosts_status": { + "type": "array", + "description": "List of details of hosts mirrored to this served (including self). Indexes correspond to indexes in \"mirrored_hosts\".", + "items": { + "type": "object", + "description": "Host data", + "properties": { + "guid": { + "type": "string", + "format": "uuid", + "nullable": false, + "description": "Host unique GUID from `netdata.public.unique.id`.", + "example": "245e4bff-3b34-47c1-a6e5-5c535a9abfb2" + }, + "reachable": { + "type": "boolean", + "nullable": false, + "description": "Current state of streaming. Always true for localhost/self." + }, + "claim_id": { + "type": "string", + "format": "uuid", + "nullable": true, + "description": "Cloud GUID/identifier in case the host is claimed. If child status unknown or unclaimed this field is set to `null`", + "example": "c3b2a66a-3052-498c-ac52-7fe9e8cccb0c" + } + } + } + }, "os_name": { "type": "string", "description": "Operating System Name.", @@ -963,6 +1172,11 @@ "description": "Kernel Version.", "example": "4.19.32-1-MANJARO" }, + "is_k8s_node": { + "type": "boolean", + "description": "Netdata is running on a K8s node.", + "example": false + }, "architecture": { "type": "string", "description": "Kernel architecture.", @@ -988,6 +1202,17 @@ "description": "Container technology detection method.", "example": "dockerenv" }, + "labels": { + "type": "object", + "description": "List of host labels.", + "properties": { + "app": { + "type": "string", + "description": "Host label.", + "example": "netdata" + } + } + }, "collectors": { "type": "array", "items": { @@ -1798,6 +2023,42 @@ "nullable": true } } + }, + "alarms_values": { + "type": "object", + "properties": { + "hostname": { + "type": "string" + }, + "alarms": { + "type": "object", + "description": "HashMap with keys being alarm names", + "additionalProperties": { + "type": "object", + "properties": { + "id": { + "type": "integer" + }, + "value": { + "type": "integer" + }, + "status": { + "type": "string", + "enum": [ + "REMOVED", + "UNDEFINED", + "UNINITIALIZED", + "CLEAR", + "RAISED", + "WARNING", + "CRITICAL", + "UNKNOWN" + ] + } + } + } + } + } } } } |