api.yaml

openapi: 3.0.1

paths:
  /aggregated_canary_analyses/v1:
    post:
      summary: Start an aggregated canary analysis execution stage
      description: >
        This endpoint triggers a canary analysis stage that will run for {requestBody.lifetime} seconds.
        The stage will conduct {requestBody.lifetime} / {requestBody.interval} canary judgements.
        The canary judgments will source the data at a data point per {requestBody.step} second resolution.
      tags:
        - aggregated canary analysis
      requestBody:
        required: true
        content:
          application/json; charset=UTF-8:
            schema:
              $ref: '#/components/schemas/CanaryAnalysisExecutionRequest'
      responses:
        '200':
          description: Canary analysis stage job started
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/CanaryAnalysisExecutionResponse'
        '400':
          description: Bad Request
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: "#/components/schemas/BackstopperError"
        '500':
          description: Server Error
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: "#/components/schemas/BackstopperError"
  /aggregated_canary_analyses/v1/{id}:
    get:
      summary: Get a canary analysis stage
      description: Fetches an started or complete canary analysis stage
      tags:
        - aggregated canary analysis
      parameters:
      - description: 'id of the canary analysis stage'
        in: path
        name: id
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: '#/components/schemas/CanaryAnalysisExecutionStatusResponse'
        '404':
          description: Not Found
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: "#/components/schemas/BackstopperError"
        '500':
          description: Server Error
          content:
            application/json; charset=UTF-8:
              schema:
                $ref: "#/components/schemas/BackstopperError"
components:
  schemas:
    CanaryAnalysisExecutionRequest:
      type: object
      description: The canary analysis stage request
      properties:
        application:
          type: string
          description: The subject under test.
          example: RefereeApi
        metricsAccountName:
          type: string
          description: The metrics account to use
          example: sfx-arch
        storageAccountName:
          type: string
          description: The storage account to use
          example: s3
        canaryConfig:
          type: object
          description: The kayenta canary config
          $ref: "#/components/schemas/KayentaCanaryConfig"
        scopes:
          type: array
          description: List of scopes
          items:
            $ref: "#/components/schemas/CanaryAnalysisExecutionRequestScope"
        scoreThresholds:
          type: object
          description: The thresholds
          properties:
            pass:
              type: number
              description: The score that the final canary judgement must meet or exceed.
              example: 90
            marginal:
              type: number
              description: The score that all canary judgements must meet or exceed for the stage to continue.
              example: 50
        lifetimeDurationMins:
          type: number
          description: >
            The number of minutes to run the canary analysis stage stage for.
          example: 30
        beginCanaryAnalysisAfterMins:
          type: number
          description: >
            The number of minutes to to wait before running the canary analysis stage.
            This might be needed if your app doesn't isn't immediately sending data to its metric source
          example: 5
        lookbackMins:
          type: number
          description: TODO
          example: 0
        canaryAnalysisIntervalMins:
          type: number
          description: >
            The interval in minutes that the canary analysis stage should conduct judgements on.
            If you have a 1 hour canary and select an interval of 10 minutes, there will be 6 judgement results.
            This would allow the canary to fail fast at time delay + interval
          example: 10
    KayentaCanaryConfig:
      type: object
      description: >
        User defined config / config overrides.
        If supplied this object will be recursively left merged with the baseConfig
        See: https://github.com/spinnaker/kayenta/blob/master/json-formats.md for examples
      # TODO reference the Kayenta config here, the Kayenta config would be significant task to document in open api 3.0
      additionalProperties:
        type: object
      example:
        name: node-golden-signals-example
        description: Golden Signals for the Nike SignalFx Node Metrics Lib with Express middleware.
        judge:
          judgeConfigurations: {}
          name: NetflixACAJudge-v1.0
        metrics:
        - name: 95th Percentile Request Latency for /hello
          query:
            metricName: requests.p95
            queryPairs:
            - key: uri
              value: "/hello"
            - key: statusCode
              value: 2*
            aggregationMethod: mean
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: increase
              critical: false
          groups:
          - Latency
          scopeName: default
        - name: 95th Percentile Request Latency for /foo
          query:
            metricName: requests.p95
            queryPairs:
            - key: uri
              value: "/foo"
            - key: statusCode
              value: 2*
            aggregationMethod: mean
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: increase
              nanStrategy: replace
              critical: false
          groups:
          - Latency
          scopeName: default
        - name: Successful request count
          query:
            metricName: requests.count
            queryPairs:
            - key: statusCode
              value: 2*
            aggregationMethod: sum
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: decrease
              nanStrategy: remove
              critical: false
          groups:
          - Traffic
          scopeName: default
        - name: Successful request count for /hello
          query:
            metricName: requests.count
            queryPairs:
            - key: uri
              value: "/hello"
            - key: statusCode
              value: 2*
            aggregationMethod: sum
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: decrease
              nanStrategy: replace
              critical: false
          groups:
          - Traffic
          scopeName: default
        - name: Successful request count for /foo
          query:
            metricName: requests.count
            queryPairs:
            - key: uri
              value: "/foo"
            - key: statusCode
              value: 2*
            aggregationMethod: sum
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: decrease
              nanStrategy: replace
              critical: false
          groups:
          - Traffic
          scopeName: default
        - name: Server Error count for /hello
          query:
            metricName: requests.count
            queryPairs:
            - key: uri
              value: "/hello"
            - key: statusCode
              value: 5*
            aggregationMethod: sum
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: increase
              nanStrategy: replace
              critical: false
          groups:
          - Errors
          - Traffic
          scopeName: default
        - name: Request Error count for /hello
          query:
            metricName: requests.count
            queryPairs:
            - key: uri
              value: "/hello"
            - key: statusCode
              value: 4*
            aggregationMethod: sum
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: increase
              nanStrategy: replace
              critical: false
          groups:
          - Errors
          - Traffic
          scopeName: default
        - name: Server Error count for /foo
          query:
            metricName: requests.count
            queryPairs:
            - key: uri
              value: "/foo"
            - key: statusCode
              value: 5*
            aggregationMethod: sum
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: increase
              nanStrategy: replace
              critical: false
          groups:
          - Errors
          - Traffic
          scopeName: default
        - name: Request Error count for /foo
          query:
            metricName: requests.count
            queryPairs:
            - key: uri
              value: "/foo"
            - key: statusCode
              value: 4*
            aggregationMethod: sum
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: increase
              nanStrategy: replace
              critical: false
          groups:
          - Errors
          scopeName: default
        - name: Available System Memory
          query:
            metricName: node.os.freemem
            aggregationMethod: mean
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: decrease
              nanStrategy: remove
              critical: false
              effectSize:
                allowedIncrease: 1.1
                criticalIncrease: 25
          groups:
          - Saturation
          scopeName: default
        - name: OS 1m Load Average
          query:
            metricName: node.os.loadavg.1m
            aggregationMethod: mean
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: increase
              nanStrategy: remove
              critical: false
              effectSize:
                allowedIncrease: 1.5
                criticalIncrease: 25
          groups:
          - Saturation
          scopeName: default
        - name: Node Heap Used
          query:
            metricName: node.process.memory-usage.heap-used
            aggregationMethod: mean
            serviceType: signalfx
            type: signalfx
          analysisConfigurations:
            canary:
              direction: increase
              nanStrategy: remove
              critical: false
              effectSize:
                allowedIncrease: 1.1
                criticalIncrease: 25
          groups:
          - Saturation
          scopeName: default
        classifier:
          groupWeights:
            Latency: 20
            Traffic: 20
            Errors: 50
            Saturation: 10
    CanaryAnalysisExecutionRequestScope:
      type: object
      description: The object that tells kayenta how to identify and look up data in the metric source
      properties:
        scopeName:
          type: string
          description: name of the scope
          example: default
        controlScope:
          type: string
          description: the control scope
          example: refereeapi-control-v001
        controlLocation:
          type: string
          description: the control location
          example: us-west-2
        experimentScope:
          type: string
          description: the experiment scope
          example: refereeapi-v002
        experimentLocation:
          type: string
          description: the control location
          example: us-west-2
        extendedScopeParams:
          type: object
          additionalProperties:
            type: string
          example:
            _scope_key: asg_name
    CanaryAnalysisExecutionResponse:
      properties:
        canaryAnalysisExecutionId:
          type: string
          description: The id of the canary analysis execution
          example: adsfa-asdf-23-sdf
    CanaryAnalysisExecutionStatusResponse:
      type: object
      description: The result of an indivisual canary analysis judgement
      properties:
        application:
          type: string
          description: The name of the application under test
        pipelineId:
          type: string
          description: The the id of the orca execution pipeline, can be used for canceling the pipeline.
        pipelineName:
          type: string
          description: The name of the pipeline, that is being ran
        pipelineConfigId:
          type: string
          description: The pipeline config id
        stageStatus:
          type: array
          description: The status of the stages in the canary analysis execution pipeline
          items:
            type: object
            description: The metadata for a stage
            properties:
              type:
                type: string
                description: The stage type
              name:
                type: string
                description: The stage name
              status:
                type: string
                description: The orca stage execution status
        isComplete:
          type: boolean
          description: Indicates that the pipeline has finished its work (successfully or not).
        execptions:
          type: array
          descriptions: A list of propagated exceptions
          items:
            type: object
        canaryAnalysisExecutionResult:
          type: object
          description: The CAE requests
          $ref: "#/components/schemas/CanaryAnalysisExecutionResult"
        canaryAnalysisExecutionRequest:
          type: object
          description: The CAE requests
          $ref: "#/components/schemas/CanaryAnalysisExecutionRequest"
        buildTimeMillis:
          type: number
          description: build time epoch millis, when the pipeline was first created.
        buildTimeIso:
          type: string
          description: ISO 8061 build time, when the pipeline was first created.
        startTimeMillis:
          type: number
          description: start time epoch millis, refers to the time the pipeline started running.
        startTimeIso:
          type: string
          description: ISO 8061 start time, refers to the time the pipeline started running.
        endTimeMillis:
          type: number
          description: end time epoch millis, refers to the time the pipeline ended, either successfully or unsuccessfully.
        endTimeIso:
          type: string
          description: ISO 8061 end time, refers to the time the pipeline ended, either successfully or unsuccessfully.
    CanaryAnalysisExecutionResult:
      type: object
      description: The actual results of the Canary Analysis Execution Pipeline, Object present when isComplete is true
      properties:
        didPassThresholds:
          type: boolean
          description: true, if the job ran successfully and the all canary judgements passed their defined thresholds.
        canaryScoreMessage:
          type: string
          description: message for when didPassThresholds is false
        canaryScores:
          type: array
          description: The array of scores in chronological order.
          items:
            type: number
        canaryExecutionResults:
          type: object
          description: The result for an indivisual canary judgement interval
          $ref: "#/components/schemas/CanaryExecutionResult"
        buildTimeIso:
          type: string
          description: ISO 8061 build time, when the pipeline was first created.
        startTimeIso:
          type: string
          description: ISO 8061 start time, refers to the time the pipeline started running.
        endTimeIso:
          type: string
          description: ISO 8061 end time, refers to the time the pipeline ended, either successfully or unsuccessfully.
    CanaryExecutionResult:
      type: object
      description: The result for an indivisual canary judgement interval
      properties:
        executionId:
          type: string
          description: The kayenta execution id for the canary judgement execution
        executionStatus:
          type: string
          description: The orca stage execution status
        exception:
          type: object
          description: The propigated exception from Kayenta if present
        result:
          type: object
          description: The canary judgement result wrapper from Kayenta
          $ref: "#/components/schemas/KayentaCanaryJudgementExecutionResult"
        warnings:
          type: array
          description: List of warnings from kayenta
          items:
            type: string
        metricSetPairListId:
          type: string
          description: The kayenta metric set pair id
        buildTimeMillis:
          type: number
          description: build time epoch millis, when the canary judgement execution was first created.
        buildTimeIso:
          type: string
          description: ISO 8061 build time, when the canary judgement execution was first created.
        startTimeMillis:
          type: number
          description: start time epoch millis, refers to the time the canary judgement execution started running.
        startTimeIso:
          type: string
          description: ISO 8061 start time, refers to the time the canary judgement execution started running.
        endTimeMillis:
          type: number
          description: end time epoch millis, refers to the time the canary judgement execution ended, either successfully or unsuccessfully.
        endTimeIso:
          type: string
          description: ISO 8061 end time, refers to the time the canary judgement execution ended, either successfully or unsuccessfully.
        storageAccountName:
          type: string
          description: if set the storage account used
        configurationAccountName:
          type: string
          description: if set the configuration account used
    KayentaCanaryJudgementExecutionResult:
      type: object
      description: The execution result wrapper from Kayenta
      properties:
        canaryDuration:
          type: string
          description: ISO-8601 representation of the duration
        judgeResults:
          type: object
          description: The canary judgement result from Kayenta
          $ref: "#/components/schemas/CanaryJudgementResult"
    CanaryJudgementResult:
      type: object
      description: The judgement result from Kayenta
      properties:
        judgeName:
          type: string
          description: The judge that was used
        results:
          type: array
          description: the results
          items:
            type: object
            description: the canary analysis result
            properties:
              name:
                type: string
              tags:
                type: object
                description: map of tags
                additionalProperties:
                  type: string
              id:
                type: string
                descripton: the id of the result
            classification:
              type: string
              enum:
              - Pass
              - Fail
              - Marginal
              - Nodata
              - NodataFailMetric
              - Error
            classificationReason:
              type: string
              desciption: The reason for the the classification
            groups:
              type: array
              description: the metrics groups
              items:
                type: string
            experimentMetadata:
              type: object
              description: map of experiment metadata
              additionalProperties:
                type: object
            controlMetadata:
              type: object
              description: map of control metadata
              additionalProperties:
                type: object
            resultMetadata:
              type: object
              description: map of result metadata
              additionalProperties:
                type: object
            critical:
              type: boolean
              description: did fail critically
        groupScores:
          type: array
          description: the groups scores
          items:
            type: object
            properties:
              name:
                type: string
                description: The group name
              score:
                type: number
                description: The score for the group
            classification:
              type: string
              description: the classifiaction for the group
            classificationReason:
              type: string
              desciption: The reason for the the classification
        score:
          type: object
          description: The score object
          properties:
            score:
              type: number
              description: the score between 0 and 100
            classification:
              type: string
              enum:
                - Pass
                - Fail
                - Marginal
                - Nodata
                - NodataFailMetric
                - Error
            classificationReason:
              type: string
              desciption: The reason for the the classification
    BackstopperError:
      type: object
      description: BackstopperError object describing the error that occured
      properties:
        errorId:
          type: string
          description: a unique guid that can be used to find server logs
        errors:
          type: array
          description: List of errors objects, that caused the main error
          items:
            type: object
            properties:
              code:
                description: the error number
                type: number
                example: 43
              message:
                description: Human readable error message
                type: string
                example: unable to find the request canary analysis execution
              metadata:
                description: key value map of metadata
                type: object
                additionalProperties:
                  type: string
                example:
                  "id": "abc-abesd-asdfsadf"
      example:
        errorId: "abc-abesd-asdfsadf"
        errors:
        - code: 43
          message: failed to find canary execution