plugin_name: python.d.plugin
modules:
  - meta:
      plugin_name: python.d.plugin
      module_name: zscores
      monitored_instance:
        name: python.d zscores
        link: https://en.wikipedia.org/wiki/Standard_score
        categories:
          - data-collection.other
        icon_filename: ""
      related_resources:
        integrations:
          list: []
      info_provided_to_referring_integrations:
        description: ""
      keywords:
        - zscore
        - z-score
        - standard score
        - standard deviation
        - anomaly detection
        - statistical anomaly detection
      most_popular: false
    overview:
      data_collection:
        metrics_description: |
          By using smoothed, rolling [Z-Scores](https://en.wikipedia.org/wiki/Standard_score) for selected metrics or charts you can narrow down your focus and shorten root cause analysis.
        method_description: |
          This collector uses the [Netdata rest api](https://github.com/netdata/netdata/blob/master/web/api/README.md) to get the `mean` and `stddev`
          for each dimension on specified charts over a time range (defined by `train_secs` and `offset_secs`).
          
          For each dimension it will calculate a Z-Score as `z = (x - mean) / stddev` (clipped at `z_clip`). Scores are then smoothed over
          time (`z_smooth_n`) and, if `mode: 'per_chart'`, aggregated across dimensions to a smoothed, rolling chart level Z-Score at each time step.
      supported_platforms:
        include: []
        exclude: []
      multi_instance: true
      additional_permissions:
        description: ""
      default_behavior:
        auto_detection:
          description: ""
        limits:
          description: ""
        performance_impact:
          description: ""
    setup:
      prerequisites:
        list:
          - title: Python Requirements
            description: |
              This collector will only work with Python 3 and requires the below packages be installed.
              
              ```bash
              # become netdata user
              sudo su -s /bin/bash netdata
              # install required packages
              pip3 install numpy pandas requests netdata-pandas==0.0.38
              ```
      configuration:
        file:
          name: python.d/zscores.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: charts_regex
              description: what charts to pull data for - A regex like `system\..*|` or `system\..*|apps.cpu|apps.mem` etc.
              default_value: "system\\..*"
              required: true
            - name: train_secs
              description: length of time (in seconds) to base calculations off for mean and stddev.
              default_value: 14400
              required: true
            - name: offset_secs
              description: offset (in seconds) preceding latest data to ignore when calculating mean and stddev.
              default_value: 300
              required: true
            - name: train_every_n
              description: recalculate the mean and stddev every n steps of the collector.
              default_value: 900
              required: true
            - name: z_smooth_n
              description: smooth the z score (to reduce sensitivity to spikes) by averaging it over last n values.
              default_value: 15
              required: true
            - name: z_clip
              description: cap absolute value of zscore (before smoothing) for better stability.
              default_value: 10
              required: true
            - name: z_abs
              description: "set z_abs: 'true' to make all zscores be absolute values only."
              default_value: "true"
              required: true
            - name: burn_in
              description: burn in period in which to initially calculate mean and stddev on every step.
              default_value: 2
              required: true
            - name: mode
              description: mode can be to get a zscore 'per_dim' or 'per_chart'.
              default_value: per_chart
              required: true
            - name: per_chart_agg
              description: per_chart_agg is how you aggregate from dimension to chart when mode='per_chart'.
              default_value: mean
              required: true
            - name: update_every
              description: Sets the default data collection frequency.
              default_value: 5
              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
        examples:
          folding:
            enabled: true
            title: "Config"
          list:
            - name: Default
              description: Default configuration.
              folding:
                enabled: false
              config: |
                local:
                  name: 'local'
                  host: '127.0.0.1:19999'
                  charts_regex: 'system\..*'
                  charts_to_exclude: 'system.uptime'
                  train_secs: 14400
                  offset_secs: 300
                  train_every_n: 900
                  z_smooth_n: 15
                  z_clip: 10
                  z_abs: 'true'
                  burn_in: 2
                  mode: 'per_chart'
                  per_chart_agg: 'mean'
    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: zscores.z
              description: Z Score
              unit: "z"
              chart_type: line
              dimensions:
                - name: a dimension per chart or dimension
            - name: zscores.3stddev
              description: Z Score >3
              unit: "count"
              chart_type: stacked
              dimensions:
                - name: a dimension per chart or dimension