swagger: '2.0' info: description: Vitals API version: 0.35.0 title: Vitals API basePath: / tags: - name: health description: Stats about the health of a Kong cluster - name: traffic description: Stats about traffic routed through Kong schemes: - http paths: /vitals: get: tags: - vitals summary: Get information about stats collected description: '' operationId: getVitalsInfo produces: - application/json responses: '200': description: successful operation schema: $ref: '#/definitions/VitalsInfo' /vitals/cluster: get: tags: - health summary: Get health stats for this Kong cluster description: '' operationId: getClusterStats produces: - application/json parameters: - name: interval in: query description: Granularity of the time series (minutes or seconds) required: true type: string - name: start_ts in: query description: 'Requested start of the time series, in Unix epoch format (seconds)' required: true type: string responses: '200': description: successful operation schema: $ref: '#/definitions/ClusterVitalsTimeSeriesWithMetadata' '400': description: Invalid query params /vitals/cluster/status_codes: get: deprecated: true tags: - traffic summary: Get the status code classes returned across the cluster description: This operation is deprecated. Use /status_code_classes. operationId: getClusterStatusCodeStats produces: - application/json parameters: - name: interval in: query description: Granularity of the time series (minutes or seconds) required: true type: string - name: start_ts in: query description: 'Requested start of the time series, in Unix epoch format (seconds)' required: true type: string responses: '200': description: successful operation schema: $ref: '#/definitions/ClusterVitalsStatusCodesWithMetadata' '400': description: Invalid query params /vitals/nodes: get: tags: - health summary: Get health stats for all nodes description: '' operationId: getAllNodeStats produces: - application/json parameters: - name: interval in: query description: Granularity of the time series (minutes or seconds) required: true type: string - name: start_ts in: query description: 'Requested start of the time series, in Unix epoch format (seconds)' required: true type: string responses: '200': description: successful operation schema: $ref: '#/definitions/NodeVitalsTimeSeriesWithMetadata' '400': description: Invalid query params '/vitals/nodes/{node_id}': get: tags: - health summary: Get stats for a specific node by UUID description: '' operationId: getNodeStatsByID produces: - application/json parameters: - name: node_id type: string in: path description: Node to retrieve stats for required: true - name: interval in: query description: Granularity of the time series (minutes or seconds) required: true type: string - name: start_ts in: query description: 'Requested start of the time series, in Unix epoch format (seconds)' required: true type: string responses: '200': description: successful operation schema: $ref: '#/definitions/NodeVitalsTimeSeriesWithMetadata' '400': description: Invalid query params '404': description: Unable to find requested node '/vitals/consumers/{consumer_id}/cluster': get: tags: - traffic deprecated: true summary: Get count of requests for the given consumer across entire cluster description: This operation is deprecated. Use /vitals/status_codes/by_consumer_and_route operationId: getConsumerClusterStats produces: - application/json parameters: - name: consumer_id type: string in: path description: Consumer to retrieve stats for required: true - name: interval type: string in: query description: Granularity of the time series (minutes or seconds) required: true - name: start_ts in: query description: 'Requested start of the time series, in Unix epoch format (seconds)' required: true type: string responses: '200': description: successful operation schema: $ref: '#/definitions/ClusterConsumersTimeSeriesWithMetadata' '400': description: Invalid query params '404': description: Unable to find requested consumer /{workspace_name}/vitals/status_code_classes: get: tags: - traffic summary: Get status code classes for a cluster or workspace. description: '' operationId: getStatusCodeClassesByWorkspace produces: - application/json parameters: - name: workspace_name type: string in: path description: >- Optional parameter. If provided, returns status code classes for the workspace; otherwise, returns them for the cluster required: true - name: interval type: string in: query description: Granularity of the time series (minutes or seconds) required: true - name: start_ts in: query description: 'Requested start of the time series, in Unix epoch format (seconds)' required: true type: string responses: '200': description: successful operation schema: $ref: '#/definitions/StatusCodesByEntityMetadata' '400': description: Invalid query params '404': description: Unable to find requested consumer /{workspace_name}/vitals/status_codes/by_service: get: tags: - traffic summary: Get a time series of status codes returned by a given service description: '' operationId: getStatusCodesByService produces: - application/json parameters: - name: service_id type: string in: query description: Service to retrieve status codes for required: true - name: interval type: string in: query description: Granularity of the time series (minutes or seconds) required: true - name: start_ts in: query description: 'Requested start of the time series, in Unix epoch format (seconds)' required: true type: string - name: workspace_name type: string in: path description: >- This parameter is optional. When present, it limits the result to a specific workspace. required: true responses: '200': description: successful operation schema: $ref: '#/definitions/StatusCodesByEntityTimeSeriesWithMetadata' '400': description: Invalid query params '404': description: Unable to find requested service /{workspace_name}/vitals/status_codes/by_route: get: tags: - traffic summary: Get cluster-wide count of status for a given route description: '' operationId: getStatusCodesByRoute produces: - application/json parameters: - name: route_id type: string in: query description: Route to retrieve status codes for required: true - name: interval type: string in: query description: Granularity of the time series (minutes or seconds) required: true - name: start_ts in: query description: 'Requested start of the time series, in Unix epoch format (seconds)' required: true type: string - name: workspace_name type: string in: path description: >- This parameter is optional. When present, it limits the result to a specific workspace. required: true responses: '200': description: successful operation schema: $ref: '#/definitions/StatusCodesByEntityTimeSeriesWithMetadata' '400': description: Invalid query params '404': description: Unable to find requested route '/{workspace_name}/vitals/status_codes/by_consumer_and_route': get: tags: - traffic summary: >- Get status codes for all the routes called by the given consumer in the given timeframe description: '' operationId: getStatusCodesByConsumerAndRoute produces: - application/json parameters: - name: consumer_id type: string in: query description: Consumer to retrieve status codes for required: true - name: interval type: string in: query description: Granularity of the time series (minutes or seconds) required: true - name: start_ts in: query description: 'Requested start of the time series, in Unix epoch format (seconds)' required: true type: string - name: workspace_name type: string in: path description: >- This parameter is optional. When present, it limits the result to a specific workspace. required: true responses: '200': description: successful operation schema: $ref: '#/definitions/StatusCodesByEntityTimeSeriesWithMetadata' '400': description: Invalid query params '404': description: Unable to find requested consumer definitions: ClusterVitalsMetadata: properties: level: type: string example: cluster enum: - cluster - node workspace_id: type: string description: UUID of workspace this time series is for interval: type: string example: seconds enum: - seconds - minutes interval_width: type: number example: 60 earliest_ts: type: integer example: 1514508300 latest_ts: type: integer example: 1514508480 stat_labels: type: array items: type: string example: - cache_datastore_hits_total - cache_datastore_misses_total - latency_proxy_request_min_ms - latency_proxy_request_max_ms - latency_upstream_min_ms - latency_upstream_max_ms - requests_proxy_total - latency_proxy_request_avg_ms - latency_upstream_avg_ms StatusCodesByEntityMetadata: properties: entity_type: type: string example: service|route entity_id: type: string example: level: type: string example: cluster enum: - cluster workspace_id: type: string description: UUID of the workspace this time series is for interval: type: string example: seconds enum: - seconds - minutes interval_width: type: number example: 60 earliest_ts: type: integer example: 1514508300 latest_ts: type: integer example: 1514508480 stat_labels: type: array items: type: string example: - status_codes_service|route_total StatusCodesByEntityTimeSeriesWithMetadata: type: object properties: meta: $ref: '#/definitions/StatusCodesByEntityMetadata' stats: $ref: '#/definitions/StatusCodesByEntityStats' ClusterVitalsStatusCodesMetadata: properties: level: type: string example: cluster enum: - cluster interval: type: string example: seconds enum: - seconds - minutes interval_width: type: number example: 60 earliest_ts: type: integer example: 1514508300 latest_ts: type: integer example: 1514508480 stat_labels: type: array items: type: string example: - status_code_classes_total ClusterVitalsStats: properties: cluster: type: object properties: : type: array items: type: integer description: >- List of stat values collected at "timestamp_n", in same order as "meta.stat_labels" example: - 999 - 130 - 0 - 35 - 142 - 528 - 1146 - 110 - 156 StatusCodesByEntityStats: properties: cluster: type: object description: Vitals status codes data available at the cluster level properties: : type: object properties: : type: integer description: >- The total count of a particular status code for the time period example: 1824 ClusterVitalsStatusCodesStats: properties: cluster: type: object description: Vitals status codes data available at the cluster level properties: : type: object properties: : type: integer description: >- The total count of a particular status code class for the time period example: 1824 ClusterVitalsTimeSeriesWithMetadata: type: object properties: meta: $ref: '#/definitions/ClusterVitalsMetadata' stats: $ref: '#/definitions/ClusterVitalsStats' ClusterVitalsStatusCodesWithMetadata: type: object properties: meta: $ref: '#/definitions/ClusterVitalsStatusCodesMetadata' stats: $ref: '#/definitions/ClusterVitalsStatusCodesStats' ClusterConsumersMetadata: properties: level: type: string example: cluster enum: - cluster - node interval: type: string example: seconds enum: - seconds - minutes interval_width: type: number example: 60 earliest_ts: type: integer example: 1514508300 latest_ts: type: integer example: 1514508480 stat_labels: type: array items: type: string example: - requests_consumer_total ClusterConsumersStats: properties: cluster: type: object properties: : type: integer description: >- List of stat values collected at "timestamp_n", in same order as "meta.stat_labels" example: 47 ClusterConsumersTimeSeriesWithMetadata: type: object properties: meta: $ref: '#/definitions/ClusterConsumersMetadata' stats: $ref: '#/definitions/ClusterConsumersStats' NodeVitalsMetadata: properties: level: type: string example: node enum: - cluster - node workspace_id: type: string description: UUID of the workspace this time series is for interval: type: string example: seconds enum: - seconds - minutes interval_width: type: number example: 60 earliest_ts: type: integer example: 1514508300 latest_ts: type: integer example: 1514508480 stat_labels: type: array items: type: string example: - cache_datastore_hits_total - cache_datastore_misses_total - latency_proxy_request_min_ms - latency_proxy_request_max_ms - latency_upstream_min_ms - latency_upstream_max_ms - requests_proxy_total - latency_proxy_request_avg_ms - latency_upstream_avg_ms nodes: type: object description: >- table of node ids that contributed to this time series. This element is not included on cluster-level requests. properties: : type: object description: The id of a node included in this time series. properties: hostname: type: string description: The name of the host where this node runs NodeVitalsStats: properties: : type: object description: >- The node this time series is for, or "cluster" if it's a cluster-level time series. properties: : type: array items: type: integer description: >- List of stat values collected at "timestamp_n", in same order as "meta.stat_labels" example: - 999 - 130 - 0 - 35 - 142 - 528 - 1146 - 110 - 156 NodeVitalsTimeSeriesWithMetadata: type: object properties: meta: $ref: '#/definitions/NodeVitalsMetadata' stats: $ref: '#/definitions/NodeVitalsStats' VitalsInfo: type: object example: stats: cache_datastore_hits_total: levels: cluster: intervals: minutes: retention_period_seconds: 90000 seconds: retention_period_seconds: 3600 nodes: intervals: minutes: retention_period_seconds: 90000 seconds: retention_period_seconds: 3600 properties: stats: type: object properties: : type: object properties: levels: type: object description: >- Vitals data is tracked and aggregated at different levels (per cluster, per node) properties: cluster: type: object description: Vitals data available at the cluster level properties: intervals: type: object description: >- Vitals data is available at different intervals (seconds, minutes) properties: minutes: type: object properties: retention_period_seconds: type: integer description: >- Configured retention period (in seconds) for the minutes interval seconds: type: object properties: retention_period_seconds: type: integer description: >- Configured retention period (in seconds) for the seconds interval nodes: type: object description: Vitals data available at the node level properties: intervals: type: object description: >- Vitals data is available at different intervals (seconds, minutes) properties: minutes: type: object properties: retention_period_seconds: type: integer description: >- Configured retention period (in seconds) for the minutes interval seconds: type: object properties: retention_period_seconds: type: integer description: >- Configured retention period (in seconds) for the seconds interval