vitalsSpec.yaml

swagger: '2.0'
info:
  description: Vitals API
  version: 2.4.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 (days, 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: false
          type: string
        - name: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: false
          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 (days, 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: false
          type: string
        - name: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: false
          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 (days, 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: false
          type: string
        - name: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: false
          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 (days, 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: false
          type: string
        - name: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: false
          type: string
      responses:
        '200':
          description: successful operation
          schema:
            $ref: '#/definitions/NodeVitalsTimeSeriesWithMetadata'
        '400':
          description: Invalid query params
        '404':
          description: Unable to find requested node
  '/{workspace_name}/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: workspace_name
          type: string
          in: path
          description: Workspace containing the requested consumer.
          required: true
        - 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 (days, minutes or seconds)
          required: true
        - name: start_ts
          in: query
          description: Requested start of the time series, in Unix epoch format (seconds)
          required: false
          type: string
        - name: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: false
          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 (days, minutes or seconds)
          required: true
        - name: start_ts
          in: query
          description: Requested start of the time series, in Unix epoch format (seconds)
          required: false
          type: string
        - name: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: false
          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 (days, 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: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: true
          type: string
        - name: workspace_name
          type: string
          in: path
          description: Workspace containing the requested service.
          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 (days, 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: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: true
          type: string
        - name: workspace_name
          type: string
          in: path
          description: Workspace containing the requested route.
          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:
    get:
      tags:
        - traffic
      summary: Get cluster-wide count of status for a given consumer
      description: ''
      operationId: getStatusCodesByRoute
      produces:
        - application/json
      parameters:
        - name: consumer_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 (days, 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: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: true
          type: string
        - name: workspace_name
          type: string
          in: path
          description: Workspace containing the requested consumer.
          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 (days, minutes or seconds)
          required: true
        - name: start_ts
          in: query
          description: Requested start of the time series, in Unix epoch format (seconds)
          required: false
          type: string
        - name: end_ts
          in: query
          description: Requested end of the time series, in Unix epoch format (seconds)
          required: false
          type: string
        - name: workspace_name
          type: string
          in: path
          description: Workspace containing the requested consumer and route.
          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
          - days
      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: <entity_id>
      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
          - days
      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
          - days
      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:
          <timestamp_n>:
            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:
          <timestamp_n>:
            type: object
            properties:
              <status_code>:
                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:
          <timestamp_n>:
            type: object
            properties:
              <status_code_class>:
                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
          - days
      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:
          <timestamp_n>:
            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
          - days
      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:
          <node_id>:
            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:
      <node_id>:
        type: object
        description: >-
          The node this time series is for, or "cluster" if it's a cluster-level
          time series.
        properties:
          <timestamp_n>:
            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:
                days:
                  retention_period_seconds: 63072000
                minutes:
                  retention_period_seconds: 90000
                seconds:
                  retention_period_seconds: 3600
            nodes:
              intervals:
                days:
                  retention_period_seconds: 63072000
                minutes:
                  retention_period_seconds: 90000
                seconds:
                  retention_period_seconds: 3600
    properties:
      stats:
        type: object
        properties:
          <stat_label>:
            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, days)
                        properties:
                          days:
                            type: object
                            properties:
                              retention_period_seconds:
                                type: integer
                                description: >-
                                  Configured retention period (in seconds) for
                                  the days interval
                          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, days)
                        properties:
                          days:
                            type: object
                            properties:
                              retention_period_seconds:
                                type: integer
                                description: >-
                                  Configured retention period (in seconds) for
                                  the days interval
                          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