by on July 16, 2018
I recently wanted to have an easy and interactive way to integrate our Grafana metrics and dashboards into our Slack workspace. It turns out this is really easy and convenient to achieve using hubot - a versatile and customizable bot implementation originally built at github.
In case I have to come back to my steps I will shortly summarize what I tried just now in here.
The hubot service we are about to create has to be registered in your Slack workspace beforehand. This is just a few clicks away given you have an existing Slack workspace and the necessary permissions to create and administrate the workspace:
"Bot User" page and create a new bot user with the desired “display name”"App page" and register the bot with the workspace you want the bot to live in. After authorization you can copy the Bot OAuth Access Token - we will need this token for the hubot configuration laterNow that we have established the basic setup to integrate a slack bot we are going to setup hubot itself. There are numerous ways to achieve that - this is what I did:
# install yeoman and the hubot generator
# you may install either locally or globally (-g)
$ npm install -g yo generator-hubot
$ mkdir uhlebot
$ cd uhlebot
# start the scaffolding script
$ yo hubot
# answer the questions you are asked (name, author, adapter ...)
# ...
# install hubot-grafana integration
$ npm install hubot-grafana --saveAfter that you are almost ready to start - you have to add the hubot-grafana plugin to the external-scripts.json configuration file first:
// external-scripts.json
[
"hubot-diagnostics",
"hubot-help",
"hubot-rules",
"hubot-shipit",
// ...
"hubot-grafana"
]Moreover there are a couple of configuration values you can or must set via environment variables.
The bare minimum set of configuration values are the following three:
HUBOT_GRAFANA_HOST: specify the HTTP endpoint to your Grafana instance (CAUTION: without a trailing slash!)HUBOT_GRAFANA_API_KEY: a proper Grafana API key or "Viewer" (if anonymous access is possible and desired)HUBOT_SLACK_TOKEN: a Slack Bot user token (see Bot OAuth Access Token above)Instead of directly uploading the PNG image files to Slack you will probably want to utilize a publicly available S3 bucket to store the generated metrics files. The following additional configuration values are needed in that case:
HUBOT_GRAFANA_S3_ENDPOINT: Endpoint of the S3 API (defaults to s3.amazonaws.com)HUBOT_GRAFANA_S3_BUCKET: Name of the S3 bucket to copy the images intoHUBOT_GRAFANA_S3_ACCESS_KEY_ID: Access key ID for S3HUBOT_GRAFANA_S3_SECRET_ACCESS_KEY: Secret access key for S3HUBOT_GRAFANA_S3_PREFIX: Bucket prefix (useful for shared buckets)HUBOT_GRAFANA_S3_REGION: Bucket region (defaults to us-standard)That’s all you have to do - you can now start the bot by specifying the slack adapter:
By default hubot chooses the listen on port 8080 - you may change that by overriding the PORT environment variable:
Once started and connected to your Slack workspace you can interact with the bot either via direct messages or via mentions in all channels the bot was invited into before.
Please refer to the documentation of hubot-grafana for all the possible commands - the most common ones are probably:
graf list: list all available dashboardsgraf db <dashboard>: query all panels of the given dashboardgraf db <dashboard>:<panel>: query a specific panel of the given dashboardgraf db <dashboard> now-30m now: query a dashboard with a specified time range (here: last 30 minutes)