{
    "info": {
        "author": "Kyle Kneitinger",
        "author_email": "kyle@kneit.in",
        "bugtrack_url": null,
        "classifiers": [
            "License :: OSI Approved :: BSD License",
            "Topic :: Software Development :: Compilers",
            "Topic :: Utilities"
        ],
        "description": "# alertbook\nAn Ansible-inspired Prometheus rules file compiler\n\n## Installation\n\nThe recommended installation method is via `pip`:\n\n```\npip install alertbook\n```\n\nFor development use, clone this repository and install with the `-e`\n(development) flag in `pip`:\n\n```\ngit clone https://github.com/kneitinger/alertbook.git\ncd alertbook\npip install -e .\n```\n\n## Usage\n\nThis program works in analogously to how `ansible-playbook` works.  A\n*rulebook* is like an `ansible` playbook, where variables are defined and the\ndesired rules are listed, each with conditions, or `conds`, under which they\nshould be instantiated.\n\nA project layout might look something like:\n```\nalertbook_proj\n\u251c\u2500\u2500 foo_cluster.yml\n\u2514\u2500\u2500 rules\n    \u251c\u2500\u2500 DiskFailure\n    \u2514\u2500\u2500 DiskUsageHigh\n```\n\nBy default, the `alertbook` command looks for rules in the `./rules` directory,\nand outputs compiled `*.rules` files to the `./out` directory, but these values\ncan be modified with the `--rules-dir` and `--out-dir` command line arguments,\nrespectively.\n\n\n### Rules\n\n_Note: this tool is currently only compatible with the rule format of\nPrometheus versions less than 2.0_\n\nThe rules files that `alertbook` expects look no different than the recording\nand alert rules files that Prometheus already uses...in fact, files in that\nformat can be included as is into an `alertbook` rules directory.  They can\nalso be augmented with variables (in the form `${foo}` that can be assigned in\na rulebook. For example, the following rule,\n\n```\nALERT DiskUsageOver${threshold}Percent\n    IF node_filesystem_avail / node_filesystem_size < (100 - ${threshold}) / 100\n    FOR 5m\n    LABELS { severity = \"${prio}\" }\n    ANNOTATIONS {\n        description = \"{{ $labels.instance }} disk usage has over {$threshold}%.\"\n    }\n```\n\nparameterizes the disk usage percentage and alert priority with the\n`${threshold}` and `${prio}` variables, meaning that the same rule can be used\nin a variety of contexts.\n\n\n### Rulebooks\n\nA rulebook is a YAML file of the form.\n\n```\n---\nname: \"Text to appear in compiled .rules file header\"\nvars:\n  some_ident: \"in scope for all rules unless overwritten\"\nrules:\n  - file: path-relative-to-rules-dir\n    conds:\n      - some_var_in_rule_file: doop\n        another_var_in_rule_file: [8,16]\n      - some_var_in_rule_file: floop\n        another_var_in_rule_file: 53\n```\n\nThe `name` component is a purely cosmetic value that populates the header in\nthe output rules file's header.  The `vars` component allows you to define\nglobal variables for the rulebook.\n\nThe `rules` component is where all of the desired rules are listed, and their\nvariables, if any, are instantiated.  Each entry has a `file` option, which\nspecifies the path of the file relative to the default or user-specified rules\ndirectory, and optionally, a `conds` list, where any remaining variables are\nspecified.\n\n#### Conditions\nThe `conds` list can have many items (conditions), and each item may generate one or\nmore rules, depending on whether or not a variable is defined as an array.\n\nWhen a condition's variables only have single element values, `alertbook` fills\nthe rule's variables in with those values, and adds it to the output text.\nWhen one or more of the condition's variables has an array value, `alertbook`\ncreates a set of values equal to the Cartesian product of the condition's\nvariables and outputs one rule for each set.  See the **Example** section for\nfurther clarification.\n\n### Command\n\n```\n$ alertbook -h\nusage: alertbook [-h] [-r DIR] [-o DIR] book [book ...]\n\npositional arguments:\n  book\n\noptional arguments:\n  -h, --help               show this help message and exit\n  -r DIR, --rules-dir DIR  base directory of rules (default: './rules')\n  -o DIR, --out-dir DIR    directory for compiled rules (default: './out')\n```\n\n### Example\n\nLet's use the following project structure\n\n```\nalertbook_proj\n\u251c\u2500\u2500 foo_cluster.yml\n\u2514\u2500\u2500 rules\n    \u251c\u2500\u2500 DiskFailure\n    \u2514\u2500\u2500 DiskUsageHigh\n```\n\nwhere,\n```\n$ cat foo_cluster.yml \n---\nname: Prometheus Alert Rules for foo cluster\nrules:\n  - file: DiskFailure\n    conds:\n      - prio: low\n        hours: [8,16]\n      - prio: high\n        hours: 4\n  - file: DiskUsageHigh\n    conds:\n      - threshold: 85\n        prio: high\n```\n```\n$ cat rules/DiskFailure \nALERT DiskWillFillIn{%hours}Hours\n    IF predict_linear(node_filesystem_free[1h], ${hours}*3600) < 0\n    FOR 5m\n    LABELS { severity=\"${prio}\" }\n```\n```\n$ cat rules/DiskUsageHigh \nALERT DiskUsageOver${threshold}Percent\n    IF node_filesystem_avail / node_filesystem_size < (100 - ${threshold}) / 100\n    FOR 5m\n    LABELS { severity = \"${prio}\" }\n    ANNOTATIONS {\n        description = \"{{ $labels.instance }} disk usage has over {$threshold}%.\"\n    }\n```\n\nif we examine the `rules` section of the `rulebook` we can see that we're using\n2 rules.\n\nThe 2nd rule, `DiskUsageHigh`, is fairly straightforward, we are just\npopulating the values of the variables in the rule file, one for disk\npercentage, and one for alert priority.\n\nThe 1st rule however has a it more going on:\n```\n- file: DiskFailure\n    conds:\n      - prio: low\n        hours: [8,16]\n      - prio: high\n        hours: 4\n```\nIt's second condition is just like the `DiskUsageHigh` rule's form, but the\nfirst condition has an array.  Again, when `alertbook` encounters an array in\none or more of a conditions variables, it constructs the Cartesian product of\nthem and essentially generates one condition for each.  With that in mind, we\ncould interpret\n\n```\nconds:\n  - foo: [bar, baz]\n    floop: [doop,  boop]\n```\nas being equivalent to  \n```\nconds:\n  - foo: bar\n    floop: doop\n  - foo: bar\n    floop: boop\n  - foo: baz\n    floop: doop\n  - foo: baz\n    floop: boop\n```\n\nWhen we run\n\n```\nalertbook foo_cluster\n```\n\nthe following file is generated and output to `foo_cluster.rules` in the\n`./out` directory\n\n```\n##########################################\n# Prometheus Alert Rules for foo cluster #\n##########################################\n\n## DiskFailure\n\nALERT DiskWillFillIn{%hours}Hours\n    IF predict_linear(node_filesystem_free[1h], 8*3600) < 0\n    FOR 5m\n    LABELS { severity=\"low\" }\n\nALERT DiskWillFillIn{%hours}Hours\n    IF predict_linear(node_filesystem_free[1h], 16*3600) < 0\n    FOR 5m\n    LABELS { severity=\"low\" }\n\nALERT DiskWillFillIn{%hours}Hours\n    IF predict_linear(node_filesystem_free[1h], 4*3600) < 0\n    FOR 5m\n    LABELS { severity=\"high\" }\n\n\n## DiskUsageHigh\n\nALERT DiskUsageOver70Percent\n    IF node_filesystem_avail / node_filesystem_size < (100 - 70) / 100\n    FOR 5m\n    LABELS { severity = \"low\" }\n    ANNOTATIONS {\n        description = \"{{ $labels.instance }} disk usage has over {$threshold}%.\"\n    }\n\nALERT DiskUsageOver85Percent\n    IF node_filesystem_avail / node_filesystem_size < (100 - 85) / 100\n    FOR 5m\n    LABELS { severity = \"high\" }\n    ANNOTATIONS {\n        description = \"{{ $labels.instance }} disk usage has over {$threshold}%.\"\n    }\n```\n",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://packages.python.org/alertbook",
        "keywords": "prometheus",
        "license": "BSD",
        "maintainer": "",
        "maintainer_email": "",
        "name": "alertbook",
        "package_url": "https://pypi.org/project/alertbook/",
        "platform": "",
        "project_url": "https://pypi.org/project/alertbook/",
        "project_urls": {
            "Homepage": "http://packages.python.org/alertbook"
        },
        "release_url": "https://pypi.org/project/alertbook/0.0.4/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "An Ansible-inspired Prometheus alert rules compiler",
        "version": "0.0.4"
    },
    "last_serial": 3367255,
    "releases": {
        "0.0.4": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "db41a14ae8d769c4ef695bc5b6c1a4f3",
                    "sha256": "3e79e786dc558e01e61fa9f3a2a027cdc3d0c7c1be43ea85d97cd5bd2f18044a"
                },
                "downloads": -1,
                "filename": "alertbook-0.0.4.tar.gz",
                "has_sig": false,
                "md5_digest": "db41a14ae8d769c4ef695bc5b6c1a4f3",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 5657,
                "upload_time": "2017-11-27T10:16:21",
                "url": "https://files.pythonhosted.org/packages/0d/b0/b1f2d5be09b16e2d44175eede16fd4fa4b17643b1124f35b361c0f771c62/alertbook-0.0.4.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "db41a14ae8d769c4ef695bc5b6c1a4f3",
                "sha256": "3e79e786dc558e01e61fa9f3a2a027cdc3d0c7c1be43ea85d97cd5bd2f18044a"
            },
            "downloads": -1,
            "filename": "alertbook-0.0.4.tar.gz",
            "has_sig": false,
            "md5_digest": "db41a14ae8d769c4ef695bc5b6c1a4f3",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 5657,
            "upload_time": "2017-11-27T10:16:21",
            "url": "https://files.pythonhosted.org/packages/0d/b0/b1f2d5be09b16e2d44175eede16fd4fa4b17643b1124f35b361c0f771c62/alertbook-0.0.4.tar.gz"
        }
    ]
}