This topic is for developers who want to monitor events from their apps using App Metrics. Have a configurable Enable Event Alertingvariable in the Ops Manager->App Metrics tile -> Settings-> Resource Config to disable or enable Event Alerting optional feature.

It contains detailed information about the schema and API for log monitor documents.

To upload a log monitor document, see cURL Your Log Monitor Document to App Metrics below.

For more information about the schema and API, see Log Monitor Document API Specification below. It also contains an example for log monitor document, named LogMonitorDocumentExample.

cURL Your Log Monitor Document to App Metrics

After you have your log monitor document prepared, you can push it to App Metrics using cURL. The endpoint is the same as the monitor document.

Linux/Mac:

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

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

Windows:

  1. Copy your OAuth token to the clipboard by running:

    cf oauth-token
    
  2. Paste your OAuth token into the following command:

    curl -vvv https://metrics.sys.DOMAIN/monitor-documents -H "Authorization: [AUTH-TOKEN]" --data-binary "@[LOG-MONITOR-DOCUMENT.yml]"
    

    Where:

    • AUTH-TOKEN is the OAuth token you copied in the previous step.
    • LOG-MONITOR-DOCUMENT is the name of your log monitor document YAML file.

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

Log Monitor Document API Specification

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 log monitors document.

For more details about the log 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 the Log Monitor Documents
  version: '1.0'
paths:
  /monitor-documents:
    post:
      description: POST document
      requestBody:
        description: YAML file containing the Log Monitor Document
        required: true
        content:
          text/yaml;charset=utf-8:
            schema:
              $ref: '#/components/schemas/MonitorDocument'
            examples:
              errorCountExample:
                $ref: '#/components/examples/LogMonitorDocumentExample'
      responses:
        '200':
          description: OK
        '400':
          description: Invalid log 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: 'org,space,app name for the application to be monitored'
        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
        - log_monitors
      properties:
        product:
          type: string
          description: 'org,space,app name for the application to be monitored'
        log_monitors:
          type: array
          items:
            $ref: '#/components/schemas/LogMonitor'
        webhook_url:
          type: string
          description: URL of webhook to receive JSON payload when alerts are triggered
    LogMonitor:
      type: object
      required:
        - name
      properties:
        name:
          type: string
        event:
          description: Is to fire alert in case of matched event for the specific application. Allowed events types are CRASH, SSH, START, STOP, UPDATE
          $ref: '#/components/schemas/Event'
        log:
          description: Is to look at given log pattern in the app logs and fire alert in case of match
          $ref: '#/components/schemas/Log'
    Log:
      type: object
      required:
        - log_pattern
        - message_type
        - source_type
        - only_every
        - duration
      properties:
        log_pattern:
          description: The pattern to look at in the logs
        message_type:
          type: string
          description: The file descriptor the log was written to, any subset of {"OUT","ERR"}
        source_type:
          type: string
          description: The source of the log, any subset of {"API","APP","CELL","HEALTH","LGR","RTR","SSH","STG"}
        only_every:
          type: string
          description: 'Minimum duration between alerts. Alerts will fire only every [this duration].'
        duration:
          type: string
          description: How long the value has to be past the threshold before firing an alert
    Event:
      type: object
      required:
        - type
        - only_every
        - duration
      properties:
        type:
          type: string
          description: Name of event which can be one of the following types - CRASH, SSH, START, STOP, UPDATE
        only_every:
          type: string
          description: 'Minimum duration between alerts. Alerts will fire only every [this duration].'
        duration:
          type: string
          description: How long the value has to be past the threshold before firing an alert. In case of event it is required to set to Om
  examples:
    LogMonitorDocumentExample:
      description: |
        A log monitor for the system,catalyst,appmetrics application that sends alerts to
        https://my-slack-webhook.com.

        In the log monitor document's YML file specify `event` and `log` in a meantime or at least one of them.
        In case of the `event` set value of the `duration` to `0m`, and for `only_every` recommended value is "1m"
      value: |
        ---
        product: system,catalyst,appmetrics

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

        log_monitors:
          - name: Event match for CRASH
            event:
              type: CRASH
              duration: 0m
              only_every: 1m
          - name: Log match for appmetrics app
            log:
              log_pattern: Point blocked due to tagK
              message_type:
                - OUT
                - ERR
              source_type:
                - API
                - APP
                - CELL
                - HEALTH
                - LGR
                - RTR
                - SSH
                - STG
              only_every: 2m
              duration: 1m

In case of the fired alerts, the result will be posted in the appropriate slack channel as mentioned in the YAML file like the following:

[OUT] Event match for CRASH matched with log pattern
    App: system,catalyst,appmetrics
    Indicator: MONIT419582b23da0480a8308451011cf7d4a
    Source type: API
    Since: 2022-07-15T06:21:21.131883281Z
    Log pattern: App instance exited with guid
    Details: metrics.sys.DOMAIN/apps/05beac82-0a99-4735-8680-2c214bc6affc

[OUT,ERR] Log match for appmetrics app matched with log pattern
    App: system,catalyst,appmetrics
    Indicator: MONITa046a50ed2b8425eae4e2732bcdb9689
    Source type: API,APP,CELL,HEALTH,LGR,RTR,SSH,STG
    Since: 2022-07-15T06:22:16.953520572Z
    Log pattern: Point blocked due to tagK
    Details: metrics.sys.DOMAIN/apps/c7d3c907-1b14-4f37-b0ee-413a2e4d57d9
check-circle-line exclamation-circle-line close-line
Scroll to top icon