{"id":14235463,"url":"https://github.com/klen/graphite-beacon","last_synced_at":"2025-06-17T10:13:14.609Z","repository":{"id":22385178,"uuid":"25721897","full_name":"klen/graphite-beacon","owner":"klen","description":"Simple alerting system for Graphite metrics","archived":false,"fork":false,"pushed_at":"2021-03-25T21:37:52.000Z","size":460,"stargazers_count":451,"open_issues_count":52,"forks_count":117,"subscribers_count":24,"default_branch":"develop","last_synced_at":"2025-06-10T09:54:54.591Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/klen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-10-25T06:02:18.000Z","updated_at":"2025-02-19T01:47:00.000Z","dependencies_parsed_at":"2022-08-21T03:31:09.810Z","dependency_job_id":null,"html_url":"https://github.com/klen/graphite-beacon","commit_stats":null,"previous_names":[],"tags_count":66,"template":false,"template_full_name":null,"purl":"pkg:github/klen/graphite-beacon","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klen%2Fgraphite-beacon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klen%2Fgraphite-beacon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klen%2Fgraphite-beacon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klen%2Fgraphite-beacon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/klen","download_url":"https://codeload.github.com/klen/graphite-beacon/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/klen%2Fgraphite-beacon/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260336371,"owners_count":22993742,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-20T21:01:57.473Z","updated_at":"2025-06-17T10:13:09.597Z","avatar_url":"https://github.com/klen.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"graphite-beacon\n===============\n\n![logo](https://raw.github.com/klen/graphite-beacon/develop/beacon.png)\n\nSimple alerting system for [Graphite](http://graphite.wikidot.com/) metrics.\n\nFeatures:\n\n- Simple installation\n- No software dependencies (Databases, AMQP and etc)\n- Light and fully asynchronous\n- SMTP, HipChat, Slack, PagerDuty, HTTP handlers (PRs for additional handlers are welcome!)\n- Easily configurable and supports historical values\n\n[![Build status](http://img.shields.io/travis/klen/graphite-beacon.svg?style=flat-square)](http://travis-ci.org/klen/graphite-beacon)\n[![Coverage](http://img.shields.io/coveralls/klen/graphite-beacon.svg?style=flat-square)](https://coveralls.io/r/klen/graphite-beacon)\n[![Version](http://img.shields.io/pypi/v/graphite-beacon.svg?style=flat-square)](https://pypi.python.org/pypi/graphite_beacon)\n[![License](http://img.shields.io/pypi/l/graphite-beacon.svg?style=flat-square)](https://pypi.python.org/pypi/graphite_beacon)\n[![Downloads](http://img.shields.io/pypi/dm/graphite-beacon.svg?style=flat-square)](https://pypi.python.org/pypi/graphite_beacon)\n\nExample:\n```js\n{\n\"graphite_url\": \"http://g.server.org\",\n\"smtp\": {\n    \"from\": \"beacon@server.org\",\n    \"to\": [\"me@gmail.com\"]\n},\n\"alerts\": [\n    {   \"name\": \"MEM\",\n        \"format\": \"bytes\",\n        \"query\": \"aliasByNode(sumSeriesWithWildcards(collectd.*.memory.{memory-free,memory-cached}, 3), 1)\",\n        \"rules\": [\"critical: \u003c 200MB\", \"warning: \u003c 400MB\", \"warning: \u003c historical / 2\"] },\n    {   \"name\": \"CPU\",\n        \"format\": \"percent\",\n        \"query\": \"aliasByNode(sumSeriesWithWildcards(collectd.*.cpu-*.cpu-user, 2), 1)\",\n        \"rules\": [\"critical: \u003e= 80%\", \"warning: \u003e= 70%\"] }\n]}\n```\n\nRequirements\n------------\n\n- python (2.7, 3.3, 3.4)\n- tornado\n- funcparserlib\n- pyyaml\n\n\nInstallation\n------------\n\n### Python package\n\n**graphite-beacon** can be installed using pip:\n\n    pip install graphite-beacon\n\n### Debian package\n\nUsing the command line, add the following to your /etc/apt/sources.list system config file:\n\n    echo \"deb http://dl.bintray.com/klen/deb /\" | sudo tee -a /etc/apt/sources.list\n    echo \"deb-src http://dl.bintray.com/klen/deb /\" | sudo tee -a /etc/apt/sources.list\n\nInstall the package using apt-get:\n\n    apt-get update\n    apt-get install graphite-beacon\n\n### Ansible role\n\nThere is an ansible role to install the package: https://github.com/Stouts/Stouts.graphite-beacon\n\n## Docker\n\nBuild a config.json file and run :\n\n    docker run -v /path/to/config.json:/srv/alerting/etc/config.json deliverous/graphite-beacon\n\n\nUsage\n-----\n\nJust run `graphite-beacon`:\n\n    $ graphite-beacon\n    [I 141025 11:16:23 core:141] Read configuration\n    [I 141025 11:16:23 core:55] Memory (10minute): init\n    [I 141025 11:16:23 core:166] Loaded with options:\n    ...\n\n### Configuration\n\n___\n\nTime units:\n\n\u003e '2second', '3.5minute', '4hour', '5.2day', '6week', '7month', '8year'\n\n\u003e short formats are: '2s', '3m', '4.1h' ...\n\nValue units:\n\n\u003e short: '2K', '3Mil', '4Bil', '5Tri'\n\n\u003e bytes: '2KB', '3MB', '4GB'\n\n\u003e bits: '2Kb', '3Mb', '4Gb'\n\n\u003e bps: '2Kbps', '3Mbps', '4Gbps'\n\n\u003e time: '2s', '3m', '4h', '5d'\n\nThe default options are:\n\n\u003e Note: comments are not allowed in JSON, but graphite-beacon strips them\n\n```js\n\n    {\n        // Graphite server URL\n        \"graphite_url\": \"http://localhost\",\n\n        // Public graphite server URL\n        // Used when notifying handlers, defaults to graphite_url\n        \"public_graphite_url\": null,\n\n        // HTTP AUTH username\n        \"auth_username\": null,\n\n        // HTTP AUTH password\n        \"auth_password\": null,\n\n        // Path to a pidfile\n        \"pidfile\": null,\n\n        // Default values format (none, bytes, s, ms, short)\n        // Can be redefined for each alert.\n        \"format\": \"short\",\n\n        // Default query interval\n        // Can be redefined for each alert.\n        \"interval\": \"10minute\",\n\n        // Default time window for Graphite queries\n        // Defaults to query interval, can be redefined for each alert.\n        \"time_window\": \"10minute\",\n\n        // Notification repeat interval\n        // If an alert is failed, its notification will be repeated with the interval below\n        \"repeat_interval\": \"2hour\",\n\n        // Default end time for Graphite queries\n        // Defaults to the current time, can be redefined for each alert.\n        \"until\": \"0second\",\n\n        // Default loglevel\n        \"logging\": \"info\",\n\n        // Default method (average, last_value, sum, minimum, maximum).\n        // Can be redefined for each alert.\n        \"method\": \"average\",\n\n        // Default alert to send when no data received (normal = no alert)\n        // Can be redefined for each alert\n        \"no_data\": \"critical\",\n\n        // Default alert to send when loading failed (timeout, server error, etc)\n        // (normal = no alert)\n        // Can be redefined for each alert\n        \"loading_error\": \"critical\"\n\n        // Default prefix (used for notifications)\n        \"prefix\": \"[BEACON]\",\n\n        // Default handlers (log, smtp, hipchat, http, slack, pagerduty)\n        \"critical_handlers\": [\"log\", \"smtp\"],\n        \"warning_handlers\": [\"log\", \"smtp\"],\n        \"normal_handlers\": [\"log\", \"smtp\"],\n\n        // Send initial values (Send current values when reactor starts)\n        \"send_initial\": true,\n\n        // used together to ignore the missing value\n        \"default_nan_value\": -1,\n        \"ignore_nan\": false,\n\n        // Default alerts (see configuration below)\n        \"alerts\": [],\n\n        // Path to other configuration files to include\n        \"include\": []\n    }\n```\n\nYou can setup options with a configuration file. See examples for\n[JSON](examples/example-config.json) and\n[YAML](examples/example-config.yml).\n\nA `config.json` file in the same directory that you run `graphite-beacon`\nfrom will be used automatically.\n\n#### Setup alerts\n\nCurrently two types of alerts are supported:\n- Graphite alert (default) - check graphite metrics\n- URL alert - load http and check status\n\n\u003e Note: comments are not allowed in JSON, but graphite-beacon strips them\n\n```js\n\n  \"alerts\": [\n    {\n      // (required) Alert name\n      \"name\": \"Memory\",\n\n      // (required) Alert query\n      \"query\": \"*.memory.memory-free\",\n\n      // (optional) Alert type (graphite, url)\n      \"source\": \"graphite\",\n\n      // (optional) Default values format (none, bytes, s, ms, short)\n      \"format\": \"bytes\",\n\n      // (optional) Alert method (average, last_value, sum, minimum, maximum)\n      \"method\": \"average\",\n\n      // (optional) Alert interval [eg. 15second, 30minute, 2hour, 1day, 3month, 1year]\n      \"interval\": \"1minute\",\n\n      // (optional) What kind of alert to send when no data received (normal = no alert)\n      \"no_data\": \"warning\",\n\n      // (optional) Alert interval end time (see \"Alert interval\" for examples)\n      \"until\": \"5second\",\n\n      // (required) Alert rules\n      // Rule format: \"{level}: {operator} {value}\"\n      // Level one of [critical, warning, normal]\n      // Operator one of [\u003e, \u003c, \u003e=, \u003c=, ==, !=]\n      // Value (absolute value: 3000000 or short form like 3MB/12minute)\n      // Multiple conditions can be separated by AND or OR conditions\n      \"rules\": [ \"critical: \u003c 200MB\", \"warning: \u003c 300MB\" ]\n    }\n  ]\n```\n\n##### Historical values\n\ngraphite-beacon supports \"historical\" values for a rule.\nFor example you may want to get warning when CPU usage is greater than 150% of normal usage:\n\n    \"warning: \u003e historical * 1.5\"\n\nOr memory is less than half the usual value:\n\n    \"warning: \u003c historical / 2\"\n\n\nHistorical values for each query are kept. A historical value\nrepresents the average of all values in history. Rules using a historical value will\nonly work after enough values have been collected (see `history_size`).\n\nHistory values are kept for 1 day by default. You can change this with the `history_size`\noption.\n\nSee the below example for how to send a warning when today's new user count is\nless than 80% of the last 10 day average:\n\n```js\nalerts: [\n  {\n    \"name\": \"Registrations\",\n    // Run once per day\n    \"interval\": \"1day\",\n    \"query\": \"Your graphite query here\",\n    // Get average for last 10 days\n    \"history_size\": \"10day\",\n    \"rules\": [\n      // Warning if today's new user less than 80% of average for 10 days\n      \"warning: \u003c historical * 0.8\",\n     // Critical if today's new user less than 50% of average for 10 days\n      \"critical: \u003c historical * 0.5\"\n    ]\n  }\n],\n```\n\n### Handlers\n\nHandlers allow for notifying an external service or process of an alert firing.\n\n#### Email Handler\n\nSends an email (enabled by default).\n\n```js\n{\n    // SMTP default options\n    \"smtp\": {\n        \"from\": \"beacon@graphite\",\n        \"to\": [],                   // List of email addresses to send to\n        \"host\": \"localhost\",        // SMTP host\n        \"port\": 25,                 // SMTP port\n        \"username\": null,           // SMTP user (optional)\n        \"password\": null,           // SMTP password (optional)\n        \"use_tls\": false,           // Use TLS?\n        \"html\": true,               // Send HTML emails?\n\n        // Graphite link for emails (By default is equal to main graphite_url)\n        \"graphite_url\": null\n    }\n}\n```\n\n#### HipChat Handler\n\nSends a message to a HipChat room.\n\n```js\n{\n    \"hipchat\": {\n        // (optional) Custom HipChat URL\n        \"url\": 'https://api.custom.hipchat.my',\n\n        \"room\": \"myroom\",\n        \"key\": \"mykey\"\n    }\n}\n```\n\n#### Webhook Handler (HTTP)\n\nTriggers a webhook.\n\n```js\n{\n    \"http\": {\n        \"url\": \"http://myhook.com\",\n        \"params\": {},                 // (optional) Additional query(data) params\n        \"method\": \"GET\"               // (optional) HTTP method\n    }\n}\n```\n\n#### Slack Handler\n\nSends a message to a user or channel on Slack.\n\n```js\n{\n    \"slack\": {\n        \"webhook\": \"https://hooks.slack.com/services/...\",\n        \"channel\": \"#general\",          // #channel or @user (optional)\n        \"username\": \"graphite-beacon\",\n    }\n}\n```\n\n#### Command Line Handler\n\nRuns a command.\n\n```js\n{\n    \"cli\": {\n        // Command to run (required)\n        // Several variables that will be substituted by values are allowed:\n        //  ${level} -- alert level\n        //  ${name} -- alert name\n        //  ${value} -- current metrics value\n        //  ${limit_value} -- metrics limit value\n        \"command\": \"./myscript ${level} ${name} ${value} ...\",\n\n        // Whitelist of alerts that will trigger this handler (optional)\n        // All alerts will trigger this handler if absent.\n        \"alerts_whitelist\": [\"...\"]\n    }\n}\n```\n\n#### PagerDuty Handler\n\nTriggers a PagerDuty incident.\n\n```js\n{\n    \"pagerduty\": {\n        \"subdomain\": \"yoursubdomain\",\n        \"apitoken\": \"apitoken\",\n        \"service_key\": \"servicekey\",\n    }\n}\n```\n\n#### Telegram Handler\n\nSends a Telegram message.\n\n```js\n{\n    \"telegram\": {\n        \"token\": \"telegram bot token\",\n        \"bot_ident\": \"token you choose to activate bot in a group\"\n        \"chatfile\": \"path to file where chat ids are saved, optional field\"\n    }\n}\n```\n\n### Command Line Usage\n\n```\n  $ graphite-beacon --help\n  Usage: graphite-beacon [OPTIONS]\n\n  Options:\n\n    --config                         Path to an configuration file (JSON/YAML)\n                                     (default config.json)\n    --graphite_url                   Graphite URL (default http://localhost)\n    --help                           show this help information\n    --pidfile                        Set pid file\n\n    --log_file_max_size              max size of log files before rollover\n                                     (default 100000000)\n    --log_file_num_backups           number of log files to keep (default 10)\n    --log_file_prefix=PATH           Path prefix for log files. Note that if you\n                                     are running multiple tornado processes,\n                                     log_file_prefix must be different for each\n                                     of them (e.g. include the port number)\n    --log_to_stderr                  Send log output to stderr (colorized if\n                                     possible). By default use stderr if\n                                     --log_file_prefix is not set and no other\n                                     logging is configured.\n    --logging=debug|info|warning|error|none\n                                     Set the Python log level. If 'none', tornado\n                                     won't touch the logging configuration.\n                                     (default info)\n```\n\nBug tracker\n-----------\n\nIf you have any suggestions, bug reports or annoyances please report them to\nthe issue tracker at https://github.com/klen/graphite-beacon/issues\n\nContributors\n-------------\n\n* Andrej Kuročenko (https://github.com/kurochenko)\n* Cody Soyland (https://github.com/codysoyland)\n* Garrett Heel (https://github.com/GarrettHeel)\n* George Ionita (https://github.com/georgeionita)\n* James Yuzawa (https://github.com/yuzawa-san)\n* Kirill Klenov (https://github.com/klen)\n* Konstantin Bakulin (https://github.com/kbakulin)\n* Lammert Hellinga (https://github.com/Kogelvis)\n* Miguel Moll (https://github.com/MiguelMoll)\n* Nick Pillitteri (https://github.com/56quarters)\n* Niku Toivola (https://github.com/nikut)\n* Olli-Pekka Puolitaival (https://github.com/OPpuolitaival)\n* Phillip Hagedorn (https://github.com/phagedorn)\n* Raine Virta (https://github.com/raine)\n* Scott Nonnenberg (https://github.com/scottnonnenberg)\n* Sean Johnson (https://github.com/pirogoeth)\n* Terry Peng (https://github.com/tpeng)\n* Thomas Clavier (https://github.com/tclavier)\n* Yuriy Ilyin (https://github.com/YuriyIlyin)\n* dugeem (https://github.com/dugeem)\n* Joakim (https://github.com/VibyJocke)\n\nLicense\n--------\n\nLicensed under a [MIT license](http://www.linfo.org/mitlicense.html)\n\nIf you wish to express your appreciation for the role, you are welcome to send\na postcard to:\n\n    Kirill Klenov\n    pos. Severny 8-3\n    MO, Istra, 143500\n    Russia\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklen%2Fgraphite-beacon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fklen%2Fgraphite-beacon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fklen%2Fgraphite-beacon/lists"}