{"id":13624351,"url":"https://github.com/kvz/metriks","last_synced_at":"2025-07-23T10:06:38.954Z","repository":{"id":13220934,"uuid":"15905207","full_name":"kvz/metriks","owner":"kvz","description":"[UNMAINTAINED] A lightweight server graphing framework","archived":false,"fork":false,"pushed_at":"2016-11-08T12:25:56.000Z","size":595,"stargazers_count":55,"open_issues_count":2,"forks_count":9,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-07-20T08:48:06.536Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/kvz.png","metadata":{"files":{"readme":"README.md","changelog":null,"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-01-14T14:59:05.000Z","updated_at":"2025-05-10T15:19:41.000Z","dependencies_parsed_at":"2022-08-24T08:40:30.457Z","dependency_job_id":null,"html_url":"https://github.com/kvz/metriks","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/kvz/metriks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvz%2Fmetriks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvz%2Fmetriks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvz%2Fmetriks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvz%2Fmetriks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kvz","download_url":"https://codeload.github.com/kvz/metriks/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kvz%2Fmetriks/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266658023,"owners_count":23963615,"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","status":"online","status_checked_at":"2025-07-23T02:00:09.312Z","response_time":66,"last_error":null,"robots_txt_status":null,"robots_txt_updated_at":null,"robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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-01T21:01:41.602Z","updated_at":"2025-07-23T10:06:38.913Z","avatar_url":"https://github.com/kvz.png","language":"JavaScript","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=kevin%40vanzonneveld%2enet\u0026lc=NL\u0026item_name=Open%20source%20donation%20to%20Kevin%20van%20Zonneveld\u0026currency_code=USD\u0026bn=PP-DonationsBF%3abtn_donate_SM%2egif%3aNonHosted"],"categories":["JavaScript"],"sub_categories":[],"readme":"# [UNMAINTAINED] \n\nI might revisit this hobby project in the future, but I currently do not have time to maintain this.\n\n# Metriks\n\n\u003c!-- badges/ --\u003e\n[![Build Status](https://secure.travis-ci.org/kvz/metriks.png?branch=master)](http://travis-ci.org/kvz/metriks \"Check this project's build status on TravisCI\")\n[![NPM version](http://badge.fury.io/js/metriks.png)](https://npmjs.org/package/metriks \"View this project on NPM\")\n[![Dependency Status](https://david-dm.org/kvz/metriks.png?theme=shields.io)](https://david-dm.org/kvz/metriks)\n[![Development Dependency Status](https://david-dm.org/kvz/metriks/dev-status.png?theme=shields.io)](https://david-dm.org/kvz/metriks#info=devDependencies)\n\u003c!-- /badges --\u003e\n\nmetriks.io is a time-series graphing tool that runs on servers. if you can output a number, metriks will create a beautiful graph for you.\nit builds on top of 'ancient' `rrdtool` which has proven to work well in production. metriks tries to limit infrastructural dependencies and features in order to provide a robust and pleasant experience for simple graphing needs.\n\nplugins can be written in any language, or you can directly start graphing by tapping into metriks with node:\n\n```javascript\n// metriks is under development, plugins work but the following API is still under discussion:\nvar metriks = require('metriks');\nvar graph   = metriks.create('df');\ngraph.log({'/dev/sda1', '50%'});\n```\n\n## Features\n\n - Builds on `rrdtool`. The network industry standard of saving time-series data to disk with a constant storage footprint.\n - Builds on `nodejs` for optimal concurrency and the ability to run a server without dealing with cgi-bin, etc.\n - Minimal dependencies. If you have node.js/npm working, all you need is `aptitude install rrdtool` and you're ready to go\n - Writes RRDs \u0026 images to disk, so it works when everything else is down.\n - Idempotent. Metriks will create graphs that don't exist, and generally be eager to get you results.\n - Trivial to add graphs. It should Just Work by default. Write a plugin file in any language. If it outputs a single number, metriks will graph it for you. You can optionally output configuration strings like `# config.interval: 60` or `# graph.title: Load average` to finetune behavior. Newlines (`\\n`) separate graph lines. Other whitespaces separate graph label from value. See the [load plugin](https://github.com/kvz/metriks/blob/master/plugins/load.sh) for an example how to plot 3 load lines: 1 minute, 5 minute, 15 minute averages.\n - Can send out alerts when metrics go outside boundaries\n\nMetriks is basic. If you want advanced, there are plenty other good options out there like graphite, mrtg, observium, cacti, gnuplot, munin, influxdb, or (paid) librato. You may also want to have a look at druid, riemann and grafana.\nHowever **Metriks will never**:\n\n - Require you to deal with a flurry of perl modules / cgi-bin / xml / apache / java / tomcat / etc\n - Impose steep learning curves\n - Require a central piece of intelligence. Metriks runs distributed. Results can be aggregated centrally but are then saved as static html / json / images on e.g. S3.\n - Require networked components to be available to do it's job (in favor of graphing locally, optionally aggregating \u0026 uploading to e.g. S3)\n - Get in your way\n - Ask for your money\n\n## Example\n\nHere we'll add a simple graph with response times to different nameservers that looks like this:\n\n![kvz-imac-home-4 local-ping 1](https://f.cloud.github.com/assets/26752/2184319/a854bf90-97bd-11e3-9d78-8ba0b7178952.png)\n\nTo achieve this, open a text file `./plugins/ping.sh`, `chmod +x` it, and make it say:\n\n```bash\necho \"# config.interval: 60\"\necho \"# graph.title: Ping resolving nameservers\"\necho \"# graph.verticalLabel: Roundtrip in ms\"\n\nfor server in 8.8.8.8 4.2.2.2 208.67.222.222 172.16.0.23; do\n  echo \"ip_${server} $(ping -c 4 ${server} |tail -1 |awk '{print $4}' |cut -d '/' -f 2)\"\ndone\n```\n\n## Options\n\nIf you want to keep your plugin files outside of the Metriks source directory, simply point metriks to your own plugin dir via:\n\n```bash\nmetriks --plugin-dir ~/metriks/plugins\n```\n\nBy default, metriks writes rrds files to `~/metriks/rrd` and images to `~/metriks/png`. But you can change that with\n\n```bash\nmetriks --rrd-dir /var/lib/rrd\nmetriks --png-dir /var/www/graphs\n```\n\nMetriks contains an simple webserver so you can browse the `png` dir via:\n\n```bash\nmetriks --web-port 8000\n```\n\nIf you don't want to automatically build png files but are only interested in gathering data in rrd, use\n\n```bash\nmetriks --auto-write-png false\n```\n\nIf you want metriks to automatically upload to S3, use:\n\n```bash\nmetriks --auto-upload-s3 true\n```\n\nMetriks will look for the following environment variables to do the s3 upload:\n\n```bash\nexport METRIKS_S3_KEY=ABCDABCDABCDABCDABCD\nexport METRIKS_S3_SECRET=abcdabcdabcdabcdabcdabcdabcdabcdabcdabcd\nexport METRIKS_S3_BUCKET=metriks.example.com\n```\n\nThe default permission is `public-read`, so be careful with that.\n\n## Plugins\n\n### Configuration\n\nYou can echo any of these in your `plugin.sh` to change behavior of metriks, here are the defaults so you might as well set none of these, and get the same results:\n\n```bash\n# config-\u003einterval  : 60\n# config-\u003eenabled   : true\n\n# graphStore-\u003econsolidation: 'AVERAGE'\n# graphStore-\u003exff          : 0.5\n# graphStore-\u003estep         : 1\n# graphStore-\u003erows         : 300\n\n# graph-\u003ewidth        : 1000\n# graph-\u003eheight       : 600\n# graph-\u003ewatermark    : 'kvz.io'\n# graph-\u003efont         : 'DEFAULT:10:Inconsolata'\n# graph-\u003etabwidth     : 20\n# graph-\u003eborder       : 2\n# graph-\u003ezoom         : 1\n# graph-\u003efullSizeMode : true\n# graph-\u003edynamicLabels: true\n# graph-\u003eslopeMode    : true\n# graph-\u003eend          : 'now'\n# graph-\u003estart        : 'end-120000s'\n# graph-\u003everticalLabel: ''\n\n# lineStore-\u003e${dsName}-\u003edsType       : 'GAUGE'\n# lineStore-\u003e${dsName}-\u003eheartBeat    : 600\n# lineStore-\u003e${dsName}-\u003emin          : 'U'\n# lineStore-\u003e${dsName}-\u003emax          : 'U'\n\n# line-\u003e${dsName}-\u003etitle        : '${dsName}'\n# line-\u003e${dsName}-\u003ecolor        : '#44B824FF' .. '#3A96D0FF'\n# line-\u003e${dsName}-\u003eelement      : 'LINE1'\n# line-\u003e${dsName}-\u003econsolidation: 'AVERAGE'\n```\n\n## Todo\n\nMetriks is still in early stages of development, here's what needs to be done still:\n\n - [ ] Offer an API that so that you can programatically add values in Nodejs programs. e.g. `require('metriks').graph('df').addSeries([{'/': '50%'}])`\n - [ ] Offer *some* way to pipe data into it. I think STDIN vs using webserver as a dependency for that to accommodate decentralized / local preference\n   - Should already create a graph without the need to define a plugin or run a daemon\n   - Hence should trigger graph-\u003eupload\n   - Just check if graph hasn't been written in the last 60 seconds to avoid overhead\n   - Idea: I think this should be a separate tool.js that requires metriks and uses it's api to handle this. Vs having metriks support the stdin \u0026 configuration problems that come with that. More flexibel. Cleaner main program.\n - [ ] Checkout smokeping sources and try to build a plugin very similar to it. This should expose some limitations and make it more usable in different environments after fixing those. See [smokeping.md](smokeping.md).\n - [ ] Example plugin: top-10 memory heavy processes (may require \"Dynamically expand ds\" first)\n - [ ] Example plugins: http://word.bitly.com/post/74839060954/ten-things-to-monitor?h=2\n - [ ] Generate an index page/json of rrd/images. Maybe we can leverage existing `connect` webserver to write html to disk\n - [ ] Aggregate datasources into 1 graph using glob (maybe a separate process that uses s3 as source, can do indexes, aggegates, cleaning up old graphs)\n - [ ] Support for max \u0026 min values and a way to communicate problems to the outside world\n - [ ] Dynamically expand ds using rrdtool dump / import. It's hard, see http://stackoverflow.com/questions/13476226/adding-new-datasource-to-an-existing-rrd\n - [ ] More unit test coverage\n - [ ] Show min, max, avg for every ds on every graph by default\n - [ ] Write metriks version \u0026 datetime as watermark to every png\n - [ ] Should we ship an `upstart` file so people can daemonize/respawn/log metriks easily on ubuntu? [Yes](https://twitter.com/purefan/status/435409309858414592). Probably just output a possible config, and let the end user pipe/copy paste/change it, rather than writing to `/etc`\n - [ ] Ship Inconsolate or pick different widely-available font\n - [ ] Upgrade dependencies (async)\n - [x] Don't crash the main process on plugin fatals.\n - [x] Handle knox throwing: ECONNRESET. See https://github.com/LearnBoost/knox/issues/198\n - [x] Upload to s3 as a step after rrd -\u003e graph -\u003e upload\n - [x] Rename configs. some `graph` to `store`. `graph-\u003elines` to `lines`.\n - [x] Support for `graph-\u003elines-\u003e*-\u003e` for config that applies to all datasources\n - [x] More advanced rrd types (COUNTER vs GAUGE, ability to add a custom step, AREA graphs) as req in [#1](https://github.com/kvz/metriks/issues/1)\n - [x] Example plugin: network traffic\n - [x] Switch to `-\u003e` as a nesting delimiter. People will want to use `.` for IPs and such\n - [x] One theme object to determine colorscheme\n - [x] config nested per line. so `line.0.color` vs `lineColors.0`\n - [x] Install bin globally\n - [x] Add example section to readme with screenshots and plugin code\n - [x] Configurable line titles vs hardcoded ds name\n - [x] Upgrade flat once [this](https://github.com/hughsk/flat/issues/6) bug has been resolved. Until then, prefix all ds keys with a letter.\n - [x] Offer an optional webserver via e.g. [send](https://github.com/visionmedia/send) so you can browse through the generated pngs\n - [x] _.findWhere\n - [x] Refactoring: Plugin\n - [x] Refactoring: pluginmanager\n - [x] Refactoring: rrdtool\n - [x] Refactoring: cli\n - [x] Retire thong.tmpl for _.template\n - [x] Retire thong.sprintf for util.format\n - [x] Retire commander for cli\n - [x] Visually show integration test\n - [x] One integration test\n - [x] Test cases\n - [x] Explodetree/flatten, use it for plug-in config (linecolour slice to array) and rrdtool info\n - [x] _.isNumeric\n - [x] Librato colors\n - [x] Graph options need to be interpretted\n - [x] Configurable y-axis\n - [x] Lose rrd.js over rrdtool.js\n - [x] Async.parallel jobs\n - [x] Support for .go plugins\n\n## Prerequisites\n\nI'm assuming you already have [node 0.8+](http://nodejs.org/download/) and\n[Git](http://git-scm.com/downloads) available.\n\n### OSX\n\nTo run rrdtool on OSX you'll need [XQuartz](http://xquartz.macosforge.org).\nThen via [Homebrew](http://brew.sh/):\n\n```bash\nbrew install rrdtool coreutils\n```\n\ncoreutils is required for `timeout`, used in integration tests.\n\n### Ubuntu\n\n```bash\naptitude install rrdtool\n```\n\n## Install\n\n\n### Globally\n\n```bash\nnpm install -g metriks\n```\n\n### Development\n\n```bash\ngit clone https://github.com/kvz/metriks.git\ncd metriks\nnpm install\n```\n\n## Run\n\nWith debug output, and a built-in webserver to browse resulting png graphs on port 8000\n\n```bash\n./bin/metriks --debug --web-port 8000\n```\n\n## Test\n\n```bash\nmake test\n```\n\n## License\n\n[MIT LICENSE](LICENSE)\n\n\n## Sponsor development\n\n\u003c!-- badges/ --\u003e\n[![Gittip donate button](http://img.shields.io/gittip/kvz.png)](https://www.gittip.com/kvz/ \"Sponsor the development of metriks via Gittip\")\n[![Flattr donate button](http://img.shields.io/flattr/donate.png?color=yellow)](https://flattr.com/submit/auto?user_id=kvz\u0026url=https://github.com/kvz/metriks\u0026title=metriks\u0026language=\u0026tags=github\u0026category=software \"Sponsor the development of metriks via Flattr\")\n[![PayPal donate button](http://img.shields.io/paypal/donate.png?color=yellow)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=kevin%40vanzonneveld%2enet\u0026lc=NL\u0026item_name=Open%20source%20donation%20to%20Kevin%20van%20Zonneveld\u0026currency_code=USD\u0026bn=PP-DonationsBF%3abtn_donate_SM%2egif%3aNonHosted \"Sponsor the development of metriks via Paypal\")\n[![BitCoin donate button](http://img.shields.io/bitcoin/donate.png?color=yellow)](https://coinbase.com/checkouts/19BtCjLCboRgTAXiaEvnvkdoRyjd843Dg2 \"Sponsor the development of metriks via BitCoin\")\n\u003c!-- /badges --\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkvz%2Fmetriks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkvz%2Fmetriks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkvz%2Fmetriks/lists"}