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 uploading an indicator and creating a custom chart from UI, see Add Your Indicator to App Metrics and Create Custom Metric Chart from the UI 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"

Add Your Indicator to App Metrics and Create Custom Metric Chart from UI

In short, there is an ability to UPLOAD, EDIT and REMOVE custom chart for the specific application from UI.

The pictures below shows how to do it.

Create Single or Multiple Custom Metric Chart

Create Custom Chart

Create Multiple Custom Charts

How to create a Single or Multiple Custom Metric Charts:

  • Click the plus icon located in the top right corner of window
  • Fill all required fields to create single or multiple custom chart, then click one of the following buttons:

    Where:

    • SAVE uploads and save the newly created custom chart into Dashboard
    • VIEW ON DASHBOARD temporarily adds the newly created custom chart into Dashboard, which then can be uploaded by clicking Upload icon located in the top right corner of chart, otherwise it will disappear after refresh of the window

Edit Custom Chart for the specific application

Edit Custom Chart

Understanding the picture:

  • Click the edit icon of the chart located in the top right corner of chart
  • Edit all necessary fields and then click the EXECUTE QUERY button to review the changes, then to save the changes and return to Dashboardclick the SAVE. To discard the changes and return to Dashboard close the window

Remove Custom Chart for the specific application

Remove Custom Chart

Understanding the picture:

  • Click the sandwich icon of the chart located in the top right corner of chart, then select Remove and confirm by clicking the OK button
check-circle-line exclamation-circle-line close-line
Scroll to top icon