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:
- Copy your cf oath token to the clipboard:
cf oauth-token - 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"
