diff options
Diffstat (limited to 'web/api/netdata-swagger.yaml')
| -rw-r--r-- | web/api/netdata-swagger.yaml | 229 |
1 files changed, 213 insertions, 16 deletions
diff --git a/web/api/netdata-swagger.yaml b/web/api/netdata-swagger.yaml index 78644a76a..748274216 100644 --- a/web/api/netdata-swagger.yaml +++ b/web/api/netdata-swagger.yaml @@ -12,7 +12,7 @@ paths: * netdata version * netdata unique id * list of hosts mirrored (includes itself) - * Operating System, Virtualization and Container technology information + * Operating System, Virtualization, K8s nodes and Container technology information * List of active collector plugins and modules * number of alarms in the host * number of alarms in normal state @@ -101,13 +101,21 @@ paths: parameters: - 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 format: as returned by /charts default: system.cpu + - 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 @@ -125,11 +133,10 @@ paths: 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)." + 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: @@ -243,6 +250,7 @@ paths: - match-ids - match-names - showcustomvars + - allow_past default: - seconds - jsonwrap @@ -285,13 +293,13 @@ paths: "400": 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. /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: - name: chart @@ -410,23 +418,82 @@ paths: format: any text - 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 + 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: - colorvalue|color:null The following operators are - supported: >, <, >=, <=, =, :null (to check if no value exists)." + `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: type: string format: any text + - 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 @@ -453,6 +520,22 @@ paths: schema: 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: "200": description: The call was successful. The response should be an SVG image. @@ -481,6 +564,17 @@ paths: - prometheus_all_hosts - json default: shell + - 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. @@ -593,6 +687,13 @@ paths: 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. @@ -600,6 +701,37 @@ paths: application/json: schema: $ref: "#/components/schemas/alarms" + /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 @@ -757,6 +889,33 @@ components: example: - host1.example.com - 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. @@ -789,6 +948,10 @@ components: type: string 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. @@ -809,6 +972,14 @@ components: type: string 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: @@ -1412,3 +1583,29 @@ components: old_value: type: number 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 |