Indicator Document Template Reference

Page last updated:

This topic contains detailed information about the schema and API for indicator documents.

This topic is for developers who want to customize their dashboards for monitoring their apps using App Metrics.

For uploading an indicator document, see cURLing Your Indicator Document to App Metrics below.

For more information on the schema and API, see Indicator Document API Specification below. This also contains an example indicator document, named IndicatorDocumentExample.

For more information about the full schema of indicator documents, see the Indicator Protocol Document Reference.

Note: At this time, only the below subset of the name, promql, documentation, and presentation fields are supported for app indicators.

cURLing Your Indicator Document to App Metrics

After you have created your indicator document, you can push it to App Metrics with cURL.

Linux/Mac:

curl -vvv https://metrics.sys.DOMAIN/indicator-documents -H "Authorization: $(cf oauth-token)" --data-binary "@[YourDoc.yml]"

Windows:

  1. Copy your cf oath token to the clipboard: cf oauth-token
  2. Paste your oauth token into the following command:
curl -vvv https://metrics.sys.DOMAIN/indicator-documents -H "Authorization: [YOUR-TOKEN]" --data-binary "@[YourDoc.yml]"

Note: You can only push indicators for apps that run in a space that you have access to.

After you have your indicator document created, you can also automate the deployment of app indicator documents within your deployment pipeline.

Indicator Document API Specification

In short, there is a /indicator-documents path that supports POST and an /indicator-documents/{org,space,app} that supports deleting an indicator document for a specific org,space,app.

Deleting or uploading an indicator document clears all associated monitors and recorded alerts associated with that app.

For more details about the indicator document API, consult the following Open API specification. To use demos and examples, you can test it out in the Swagger Editor.

openapi: 3.0.2
info:
  title: App Metrics API for Indicator Documents
  version: '1.0'
paths:
  /indicator-documents:
    post:
      description: POST document
      requestBody:
        description: YAML file containing the Indicator Document
        required: true
        content:
          text/yaml;charset=utf-8:
            schema:
              $ref: '#/components/schemas/IndicatorDocument'
            examples:
              errorCountExample:
                $ref: '#/components/examples/IndicatorDocumentExample'
      responses:
        '200':
          description: OK
        '400':
          description: Invalid indicator document format
        '401':
          description: Invalid Authorization header
        '404':
          description: Product name not found
  '/indicator-documents/{productName}':
    parameters:
      - name: productName
        in: path
        required: true
        description: product name associated with the indicator document to delete
        schema:
          type: string
    delete:
      description: DELETE document
      responses:
        '204':
          description: OK
        '401':
          description: Invalid Authorization header
        '404':
          description: Product name not found
components:
  schemas:
    IndicatorDocument:
      type: object
      required:
        - apiVersion
        - kind
        - spec
      properties:
        apiVersion:
          type: string
          enum:
            - indicatorprotocol.io/v1
        kind:
          type: string
          enum:
            - IndicatorDocument
        spec:
          type: object
          required:
            - product
          properties:
            product:
              type: object
              required:
                - name
                - version
              properties:
                name:
                  type: string
                  minLength: 1
                version:
                  type: string
                  minLength: 1
            indicators:
              type: array
              items:
                type: object
                required:
                  - name
                  - promql
                properties:
                  name:
                    type: string
                    pattern: '[a-zA-Z_:][a-zA-Z0-9_:]*'
                  promql:
                    type: string
                    minLength: 1
                  presentation:
                    type: object
                    properties:
                      chartType:
                        type: string
                        enum:
                          - step
                          - quota
                      units:
                        type: string
                        enum:
                          - none
                          - bytes
                          - counts
                          - percentage
                        description: |
                          The units are responsible for automatic formatting of chart data. bytes will automatically be
                          converted to kB, MB, GB, or TB as appropriate. counts will be converted to K or M as appropriate.
                          percentage will be formatted as a percentage. none will round to 2 decimals.
                  documentation:
                    type: object
                    properties:
                      title:
                        type: string
                        description: Title that the chart will display
                      description:
                        type: string
                        description: What is the chart trying to display?
                      recommendedMeasurement:
                        type: string
                        description: 'Explanation of time frame, PromQL query in general'
                      recommendedResponse:
                        type: string
                        description: Troubleshooting information
                      thresholdNote:
                        type: string
                        description: Explanations for why the thresholds exist
  examples:
    IndicatorDocumentExample:
      description: |
        An indicator document specifying one custom indicator called CustomErrorCount500 for the
        application `org,space,app`.

        It will graph the 1 minute average errors as reported by the custom metric `customMetricName500`. The
        `$sourceId` will be interpolated to the source_id of the app at rendering time.

        The title of the graph will display as "Custom Metric 500 Errors".
      value: |
        ---
        apiVersion: indicatorprotocol.io/v1
        kind: IndicatorDocument

        spec:
          product:
            name: org,space,app-name
            version: 0.0.1

          indicators:
            - name: CustomErrorCount500
              promql: "sum(rate(customMetricName500{source_id='$sourceId'}[1m]))"
              documentation:
                title: "Custom Metric 500 Errors"
              presentation:
                units: "counts"