Monitor Document Template Reference

This topic is for developers who want to monitor their apps using App Metrics.

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

For uploading a monitor document, see cURL Your Monitor Document to App Metrics below.

For more information about the schema and API, see Monitor Document API Specification below. This also contains an example monitor document, named MonitorDocumentExample.

cURL Your Monitor Document to App Metrics

After you have your monitor document prepared, you can push it to App Metrics using cURL. The flow is the same as the indicator document flow but curling to the /monitor-documents endpoint.

Linux/Mac:

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

Where MONITOR-DOCUMENT is the name of your monitor document YAML file.

Windows:

Copy your OAuth token to the clipboard by running:
```
cf oauth-token
```
Paste your OAuth token into the following command:
```
curl -vvv https://metrics.sys.DOMAIN/monitor-documents -H "Authorization: [AUTH-TOKEN]" --data-binary "@[MONITOR-DOCUMENT.yml]"
```
Where:
- AUTH-TOKEN is the OAuth token you copied in the previous step.
- MONITOR-DOCUMENT is the name of your monitor document YAML file.

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

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

Monitor Document API Spec

In short, there is a /monitors-documents path that supports POST and an /monitor-documents/{org,space,app} that supports GET a monitor document for a specific org,space,app. There is currently no DELETE supported for a single monitors document. However, a monitors document is deleted when a new indicator file is uploaded for that app.

For more details about the monitor 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 Monitor Documents
  version: '1.0'
paths:
  /monitor-documents:
    post:
      description: POST document
      requestBody:
        description: YAML file containing the Monitor Document
        required: true
        content:
          text/yaml;charset=utf-8:
            schema:
              $ref: '#/components/schemas/MonitorDocument'
            examples:
              errorCountExample:
                $ref: '#/components/examples/MonitorDocumentExample'
      responses:
        '200':
          description: OK
        '400':
          description: Invalid monitor document format
        '401':
          description: Invalid Authorization header
        '404':
          description: Product name not found
  '/monitor-documents/{productName}':
    parameters:
      - name: productName
        in: path
        required: true
        description: product name associated with the indicator document to delete
        schema:
          type: string
    get:
      description: GET monitor document
      responses:
        '200':
          description: fetched document successfully
        '400':
          description: No product name supplied
        '401':
          description: Invalid Authorization header
        '404':
          description: Product name not found
components:
  schemas:
    MonitorDocument:
      type: object
      required:
        - product
        - monitors
      properties:
        product:
          type: string
          description: 'org,space,app name for the application to be monitored'
        monitors:
          type: array
          items:
            $ref: '#/components/schemas/Monitor'
        webhook_url:
          type: string
          description: URL of webhook to receive JSON payload when alerts are triggered
    Monitor:
      type: object
      required:
        - name
        - indicator
      properties:
        name:
          type: string
        indicator:
          type: string
          description: |
            Name of the indicator this monitor corresponds to. It could be the name of a custom indicator or one of the
            following default indicators: {RequestCount, HttpLatency, ErrorCount, CPU, MemoryPercentage, DiskPercentage}
        warning:
          description: Threshold at which warning notifications should go off
          $ref: '#/components/schemas/MonitorThreshold'
        critical:
          description: Threshold at which critical notifications should go off
          $ref: '#/components/schemas/MonitorThreshold'
    MonitorThreshold:
      type: object
      required:
        - operator
        - threshold
        - duration
        - only_every
      properties:
        operator:
          type: string
          enum:
            - lt
            - lte
            - gt
            - gte
            - eq
            - neq
        threshold:
          type: number
        duration:
          type: string
          description: How long the value has to be past the threshold before firing an alert.
        only_every:
          type: string
          description: 'Minimum duration between alerts. Alerts will fire only every [this duration].'
  examples:
    MonitorDocumentExample:
      description: |
        A monitor on the ErrorCount indicator for the system,catalyst,appmetrics application that sends alerts to
        https://my-slack-webhook.com.

        A warning alert gets sent when the ErrorCount is greater than 1 for a duration of at least one minute, and will
        only get sent a maximum of once every hour.

        A critical alert will get sent when the ErrorCount is greater than 2 for a duration of at least one minute,
        and will only get sent a maximum of every fifteen minutes.
      value: |
        ---
        product: system,catalyst,appmetrics

        webhook_url: https://my-slack-webhook.com

        monitors:
          - name: 500 Errors For Application
            indicator: ErrorCount
            warning:
               operator: gte
               threshold: 1.0
               duration: 1m
               only_every: 1h
            critical:
               operator: gte
               threshold: 2.0
               duration: 1m
               only_every: 15m