plugin_name: python.d.plugin
modules:
  - meta:
      plugin_name: python.d.plugin
      module_name: alarms
      monitored_instance:
        name: Netdata Agent alarms
        link: https://github.com/netdata/netdata/blob/master/collectors/python.d.plugin/alarms/README.md
        categories:
          - data-collection.other
        icon_filename: ""
      related_resources:
        integrations:
          list: []
      info_provided_to_referring_integrations:
        description: ""
      keywords:
        - alarms
        - netdata
      most_popular: false
    overview:
      data_collection:
        metrics_description: |
          This collector creates an 'Alarms' menu with one line plot of `alarms.status`.
        method_description: |
          Alarm status is read from the Netdata agent rest api [`/api/v1/alarms?all`](https://learn.netdata.cloud/api#/alerts/alerts1).
      supported_platforms:
        include: []
        exclude: []
      multi_instance: true
      additional_permissions:
        description: ""
      default_behavior:
        auto_detection:
          description: |
            It discovers instances of Netdata running on localhost, and gathers metrics from `http://127.0.0.1:19999/api/v1/alarms?all`. `CLEAR` status is mapped to `0`, `WARNING` to `1` and `CRITICAL` to `2`. Also, by default all alarms produced will be monitored.
        limits:
          description: ""
        performance_impact:
          description: ""
    setup:
      prerequisites:
        list: []
      configuration:
        file:
          name: python.d/alarms.conf
          description: ""
        options:
          description: |
            There are 2 sections:
            
            * Global variables
            * One or more JOBS that can define multiple different instances to monitor.
            
            The following options can be defined globally: priority, penalty, autodetection_retry, update_every, but can also be defined per JOB to override the global values.
            
            Additionally, the following collapsed table contains all the options that can be configured inside a JOB definition.
            
            Every configuration JOB starts with a `job_name` value which will appear in the dashboard, unless a `name` parameter is specified.
          folding:
            title: Config options
            enabled: true
          list:
            - name: url
              description: Netdata agent alarms endpoint to collect from. Can be local or remote so long as reachable by agent.
              default_value: http://127.0.0.1:19999/api/v1/alarms?all
              required: true
            - name: status_map
              description: Mapping of alarm status to integer number that will be the metric value collected.
              default_value: '{"CLEAR": 0, "WARNING": 1, "CRITICAL": 2}'
              required: true
            - name: collect_alarm_values
              description: set to true to include a chart with calculated alarm values over time.
              default_value: false
              required: true
            - name: alarm_status_chart_type
              description: define the type of chart for plotting status over time e.g. 'line' or 'stacked'.
              default_value: "line"
              required: true
            - name: alarm_contains_words
              description: >
                A "," separated list of words you want to filter alarm names for. For example 'cpu,load' would filter for only alarms with "cpu" or "load" in alarm name. Default includes all.
              default_value: ""
              required: true
            - name: alarm_excludes_words
              description: >
                A "," separated list of words you want to exclude based on alarm name. For example 'cpu,load' would exclude all alarms with "cpu" or "load" in alarm name. Default excludes None.
              default_value: ""
              required: true
            - name: update_every
              description: Sets the default data collection frequency.
              default_value: 10
              required: false
            - name: priority
              description: Controls the order of charts at the netdata dashboard.
              default_value: 60000
              required: false
            - name: autodetection_retry
              description: Sets the job re-check interval in seconds.
              default_value: 0
              required: false
            - name: penalty
              description: Indicates whether to apply penalty to update_every in case of failures.
              default_value: yes
              required: false
            - name: name
              description: Job name. This value will overwrite the `job_name` value. JOBS with the same name are mutually exclusive. Only one of them will be allowed running at any time. This allows autodetection to try several alternatives and pick the one that works.
              default_value: ""
              required: false
        examples:
          folding:
            enabled: true
            title: Config
          list:
            - name: Basic
              folding:
                enabled: false
              description: A basic example configuration.
              config: |
                jobs:
                  url: 'http://127.0.0.1:19999/api/v1/alarms?all'
            - name: Advanced
              folding:
                enabled: true
              description: |
                An advanced example configuration with multiple jobs collecting different subsets of alarms for plotting on different charts.
                "ML" job will collect status and values for all alarms with "ml_" in the name. Default job will collect status for all other alarms.
              config: |
                ML:
                  update_every: 5
                  url: 'http://127.0.0.1:19999/api/v1/alarms?all'
                  status_map:
                    CLEAR: 0
                    WARNING: 1
                    CRITICAL: 2
                  collect_alarm_values: true
                  alarm_status_chart_type: 'stacked'
                  alarm_contains_words: 'ml_'
                
                Default:
                  update_every: 5
                  url: 'http://127.0.0.1:19999/api/v1/alarms?all'
                  status_map:
                    CLEAR: 0
                    WARNING: 1
                    CRITICAL: 2
                  collect_alarm_values: false
                  alarm_status_chart_type: 'stacked'
                  alarm_excludes_words: 'ml_'
    troubleshooting:
      problems:
        list: []
    alerts: []
    metrics:
      folding:
        title: Metrics
        enabled: false
      description: ""
      availability: []
      scopes:
        - name: global
          description: |
            These metrics refer to the entire monitored application.
          labels: []
          metrics:
            - name: alarms.status
              description: Alarms ({status mapping})
              unit: "status"
              chart_type: line
              dimensions:
                - name: a dimension per alarm representing the latest status of the alarm.
            - name: alarms.values
              description: Alarm Values
              unit: "value"
              chart_type: line
              dimensions:
                - name: a dimension per alarm representing the latest collected value of the alarm.