diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 636c774db33..fd91a28693a 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -69,7 +69,7 @@ pages: - ['datasources/kairosdb.md', 'Data Sources', 'KairosDB'] - ['tutorials/index.md', 'Tutorials', 'Tutorials'] -- ['tutorials/stack_guide_graphite.md', 'Tutorials', 'Stack setup: Grafana + Graphite + StatsD'] +- ['tutorials/hubot_howto.md', 'Tutorials', 'How To integrate Hubot and Grafana'] - ['project/building_from_source.md', 'Project', 'Building from Source'] - ['project/cla.md', 'Project', 'Contributor License Agreement'] diff --git a/docs/sources/tutorials/hubot_howto.md b/docs/sources/tutorials/hubot_howto.md new file mode 100644 index 00000000000..388f3237022 --- /dev/null +++ b/docs/sources/tutorials/hubot_howto.md @@ -0,0 +1,125 @@ +--- +page_title: How To integrate Hubot and Grafana +page_description: Hubot Grafana install guide +page_keywords: grafana, tutorials, hubot, slack, hipchat, setup, install, config +author: Torkel Ödegaard +--- + +# How to integrate Hubot with Grafana + +Grafana 2.0 shipped with a great feature that enables it render any graph or panel to a PNG image. +No matter what data source you are using, the PNG image of the Graph will look the same +as it does in your browser. + +This guide will show you how to install and configure the [Hubot-Grafana](https://github.com/stephenyeargin/hubot-grafana) +plugin. This plugin allows you to tell hubot to render any dashboard or graph right from a channel in +Slack, Hipchat or Basecamp. The bot will respond with an image of the graph and a link that will +take you the graph. + +
+ +
+ +## What is Hubot? +[Hubot](https://hubot.github.com/) is an universal and extensible chat bot that can be used with many chat +services and has a huge library of third party plugins that allow you to automate anything from your +chat rooms. + +## Install Hubot +Hubot is very easy to install and host. If you do not already have a bot up and running please +read the official [Getting Started With Hubot](https://hubot.github.com/docs/) guide. + +## Install Hubot-Grafana script + +In your Hubot project repo install the Grafana plugin using `npm`: + + npm install hubot-grafana --save + +Edit the file external-scripts.json, and add hubot-grafana to the list of plugins. + +```json +[ +"hubot-pugme", +"hubot-shipit", +"hubot-grafana" +] +``` + +## Configure + +The `hubot-grafana` plugin requires a number of environment variables to be set in order to work properly. + + export HUBOT_GRAFANA_HOST=http://play.grafana.org + export HUBOT_GRAFANA_API_KEY=abcd01234deadbeef01234 + export HUBOT_GRAFANA_S3_BUCKET=mybucket + export HUBOT_GRAFANA_S3_ACCESS_KEY_ID=ABCDEF123456XYZ + export HUBOT_GRAFANA_S3_SECRET_ACCESS_KEY=aBcD01234dEaDbEef01234 + export HUBOT_GRAFANA_S3_PREFIX=graphs + export HUBOT_GRAFANA_S3_REGION=us-standard + +### Grafana server side rendering +The hubot plugin will take advantage of the Grafana server side rendering feature that can +render any panel on the server using phantomjs. Grafana ships with a phantomjs binary (linux only). + +To verify that this freature work try the `Direct link to rendered image` link in the panel share dialog. +If you do not get an image when opening this link verify that the required font packages are installed for phantomjs to work. + +### Grafana API Key + +You need to set the environment variable `HUBOT_GRAFANA_API_KEY` to a Grafana API Key. +You can add these from the API Keys page wich you find in the Organization dropdown. + +### Amazon S3 +The `S3` options are optional but for the images to work properly in services like Slack and Hipchat they need +to publicly available. By specifying the `S3` options the hubot-grafana script will publish the rendered +panel to `S3` it will use that URL when it posts to Slack or Hipchat. + +For everything to work + +## Hubot commands + +- `hubot graf db graphite-carbon-metrics` + - Graph all panels in the dashboard +- `hubot graf db graphite-carbon-metrics:3` + - Graph only panel with id 3 of a particular dashboard +- `hubot graf db graphite-carbon-metrics:cpu` + - Graph only the panels containing "cpu" (case insensitive) in the title +- `hubot graf db graphite-carbon-metrics now-12hr` + - Get a dashboard with a window of 12 hours ago to now +- `hubot graf db graphite-carbon-metrics now-24hr now-12hr` + - Get a dashboard with a window of 24 hours ago to 12 hours ago +- `hubot graf db graphite-carbon-metrics:3 now-8d now-1d` + - Get only the third panel of a particular dashboard with a window of 8 days ago to yesterday +- `hubot graf db graphite-carbon-metrics host=carbon-a` + - Get a templated dashboard with the `$host` parameter set to `carbon-a` +- `hubot graf list` + - Lists the available dashboards + +## Aliases +Some of the hubot commands above can lengthy and you might have to remember dashboard slug (url id). +If you have a few favorite graphs you want to be able check up on often (lets say from your mobile) you +can create hubot command aliases with the hubot script `hubot-alias`. + +Install it: + + npm i --save hubot-alias + +Now add `hubot-alias` to the list of plugins in `external-scripts.json` and restart hubot. + +Now you can add an alias like this: + +- `hubot alias graf-lb=graf db loadbalancers:2 now-20m` + +
+ Using the alias:
+ +
+ +## Summary + +Grafana is going to ship with integrated Slack and Hiptchat features some day but you do +not have to wait for that. Grafana 2 shipped with a very clever server side rendering feature +that can render any panel to a png using phantomjs. The hubot plugin for Grafana is something +you can install and use today! + + diff --git a/docs/sources/tutorials/index.md b/docs/sources/tutorials/index.md index bef16715c66..6c800457072 100644 --- a/docs/sources/tutorials/index.md +++ b/docs/sources/tutorials/index.md @@ -6,4 +6,14 @@ page_keywords: grafana, tutorials # Tutorials +This section of the docs contains a series for tutorials and stack setup guides. + +## Articles + +- [How to integrate Hubot with Grafana](hubot_howto.md) + +## External links + +- [Monitoring Urbancode deployments with Docker, Graphite, Grafana, collectd and chef!](http://cloud.boriskuschel.com/2015/08/monitoring-urbancode-deploments-with.html) +- [Scripting Grafana dashboards](http://anatolijd.blogspot.se/2014/07/scripting-grafana-dashboards.html)