search

JamesOsgood / mongodb-grafana

MongoDB plugin for Grafana
MIT License
463 stars 213 forks source link

readme

MongoDB datasource for Grafana

Features

Allows MongoDB to be used as a data source for Grafana by providing a proxy to convert the Grafana Data source API into MongoDB aggregation queries

Requirements

Installation

Install the Grafana plugin components

Install and Start the MongoDB proxy server

Examples

Create a new data source of type MongoDB as shown below. The MongoDB details are :

Sample Data Source

Then save the data source

Example 1 - Simple aggregate to rename fields

Import the dashboard in examples\RPI MongoDB - Atlas.json

This should show a graph of light sensor values from a Raspberry PI with an EnviroPHAT board feeding readings every minute into a MongoDB Atlas database.

Sample Dashboard

Clicking on the title of the graph allows you to see the aggregation query being run against the 'RPI Atlas' data source

Sample Query

The query here is

db.sensor_value.aggregate ( [ 
{ "$match" :    {   "sensor_type" : "$sensor",   "host_name" : "$host",   "ts" : { "$gte" : "$from", "$lte" : "$to" } }  },        
 {"$sort" : {"ts" : 1}},            
 {"$project" :   {  "name" : "value",   "value" : "$sensor_value",  "ts" : "$ts",  "_id" : 0} } ])

The API is expecting back documents with the following fields

$from and $to are expanded by the plugin as BSON dates based on the range settings on the UI.

Template Variables

$sensor and $host are template variables that are filled in by Grafana based on the drop down. The sample template queries are shown below. They expect documents to be returned with a single _id field.

Sample Templates

Example 2 - Using $bucketAuto to push data point aggregation to the server

Grafana tells the backend server the date range along with the size of the buckets that should be used to calculate points. Therefore it's possible to use the MongoDB aggregation operator $bucketAuto to automatically bucket the data points into display points. To support this the backend provides the $dateBucketCount macro so that queries such as the one below can be written

db.sensor_value.aggregate( [ 
{  "$match" :  {  "sensor_type" : "$sensor", "host_name" : "$host" , "ts" : { "$gte" : "$from", "$lt" : "$to" }}},
{  "$bucketAuto" :  { "groupBy" : "$ts",  
                           "buckets" : "$dateBucketCount", 
                            "output" :  {  "maxValue" : { "$max" : "$sensor_value" }  }   }   },  
{  "$project" :  {  "name" : "value",  "value" : "$maxValue",  "ts" : "$_id.min",  "_id" : 0  }  }  ]  )

Note that _id field of the bucketAuto output contains the start and end of the bucket so we can use that as the ts value

The dashboard in examples\RPI MongoDB Bucket - Atlas.json shows this.

Example 3 - Using a Tabel Panel

Table Panel

Table panels are now supported with queries of the form

db.sensor_value.aggregate(
[
    {  "$match" :  {  "ts" : { "$gte" : "$from", "$lt" : "$to"  }}},
    {  "$group":    {  "_id":  { "sensor_name" : "$sensor_name",  "sensor_type" : "$sensor_type"  }, "cnt" : { "$sum" : 1 },  "ts" : { "$max" : "$ts" }  } }, 
    { "$project": {  "name" : { "$concat" : ["$_id.sensor_name",":","$_id.sensor_type" ]},  "value" : "$cnt",  "ts" : 1, "_id" : 0} } 
])

The dashboard in examples\Sensor Values Count - Atlas.json shows this.

Running the proxy as a service on a Mac

This launch ctrl plist runs the node script via forever. To check it's running, use forever list. Logs go into /usr/local/var/lib/grafana/plugins/mongodb-grafana/dist/server

Development

To run grafana against a dev version of the plugin on a mac using grafana installed via Homebrew

Note