MongoDB data source for Grafana

The MongoDB data source plugin allows you to visualize data from MongoDB in Grafana.

Requirements

The MongoDB data source has the following requirements:

  • Valid license for Grafana Enterprise; refer to Activate an Enterprise license.
  • Grafana user with a server or organization administration role; refer to Permissions.
  • A MongoDB instance with at least one user.

Known limitations

  • Only find and aggregate read commands are supported
  • Currently ISODate is the only object constructor supported
  • For diagnostics commands that are currently supported refer to Diagnostics

Install the plugin

To install the data source, refer to Installation.

Configure the data source in Grafana

Add a data source by filling in the following fields:

Field NameDescription
NameA name for this particular MongoDB data source.
Connection StringConnection string for your MongoDB instance.
AuthenticationCredentials Enter your user name and password. CA Certificate Enter your CA certificate and decide whether to skip TLS cert validation. Client Certificate Enter your server name, client certificate, and client key.

Configure the data source with provisioning

Data sources can be configured with Grafana’s provisioning system. You can read more about how it works and all the settings you can set for data sources at Provisioning Grafana.

apiVersion: 1

datasources:
  - name: MongoDB
    type: grafana-mongodb-datasource
    access: proxy
    basicAuth: false
    editable: true
    enabled: true
    jsonData:
      connection: Connection string
      user: user name
    secureJsonData:
      password: password

Query the data source

The query editor supports the same syntax as the MongoDB Shell, with some limitations:

  • You can only run one command or query in each query.
  • Only find and aggregate read commands are supported.
  • ISODate is the only supported object constructor.

Additional syntax

The editor extends the MongoDB Shell syntax by means of database selection, where you can use a database name instead of db. For example, sample_mflix.movies.find(). You can still use db to refer to the default database in your connection string.

It also extends it by means of aggregate sorting. Sorting typically happens within the aggregate pipeline. The extended syntax is allowed on aggregate similarly to find. For example, sample_mflix.movies.aggregate({}).sort({"time": 1}).

Note: MongoDB does not perform the sort with this syntax. The sort happens after the results are queried from the collection.

Shortcuts

Press Ctrl + Space to show code completion, which is displayed after entering a . after a database, collection, query method, or aggregation method name.

Cmd + S runs the query.

Query as time series

Make a time series query by aliasing a date field to time.

Note: You can coerce non-date fields into date fields and alias them to time to use them to make a time series query.

The following example converts the int field year to a date that is projected as time using the MongoDB $dateFromParts pipeline operator:

sample_mflix.movies.aggregate([
{"$match": { "year": {"$gt" : 2000} }},
{"$group": { "_id": "$year", "count": { "$sum": 1 }}},
{"$project": { "_id": 0, "count": 1, "time": { "$dateFromParts": {"year": "$_id", "month": 2}}}}
]
).sort({"time": 1})

If you want to group your time series by Metric, project a field called __metric.

The following example displays the count of movies over time by movie rating using __metric:

sample_mflix.movies.aggregate([
{"$match": { "year": {"$gt" : 2000}}},
{"$group": { "_id": {"year":"$year", "rated":"$rated"}, "count": { "$sum": 1 } }},
{"$project": { "_id": 0, "time": { "$dateFromParts": {"year": "$_id.year", "month": 2}}, "__metric": "$_id.rated", "count": 1}}
]
).sort({"time": 1})

Diagnostics

For information about diagnostics commands, refer to Diagnostic Commands.

This plugin supports the following diagnostic commands:

  • stats
  • serverStatus
  • replSetGetStatus
  • getLog
  • connPoolStats
  • connectionStatus
  • buildInfo
  • dbStats
  • hostInfo
  • lockInfo

Macros

To simplify syntax and to allow for dynamic times, you can write queries that contain macros.

$__timeFrom
Will be replaced by the start of the currently active time selection converted to time data type.
$__timeTo()
Will be replaced by the end of the currently active time selection converted to time data type.

Templates and variables

To add a new MongoDB query variable, refer to Add a query variable. Use your MongoDB data source as your data source.

Here is an example of a query that gets all movie titles after 1980:

sample_mflix.movies.aggregate([
    {"$match": {year: {"$gt": 1980}}},
    {"$project": {"_id": 0, "movie_title": "$title"}} 
])

MongoDB supports compound variables, where one variable is used as multiple variables to perform complex multi-key filters.

  • Name your compound variable by starting each individual name with an underscore (_), such as _var1_var2. Do not use spaces.
  • Query for the compound variable by making the alias use the same individual names separated by a hyphen (-), such as val1-val2.
  • Call your variable by using normal variable syntax. For example, $_var1 or $_var2.

Filtering results on both movie name and year

  1. Create a variable and name it _movie_year.
  2. Select MongoDB as the data source.
  3. Get an array of items with one movie-year property by setting the query as follows:
sample_mflix.movies.aggregate([
    {"$match": {year: {"$gt": 1980}}},
    {"$project": {"_id": 0, "movie_year": {"$concat": ["$title", " - ", {"$toString":"$year"}]}}} 
])

// [{"movie-year": "Ted - 2016"}, {"movie-year": "The Terminator - 1985"}]
  1. Within your query, reference $_movie and $_year as separate template variables:
sample_mflix.movies.find({"title":"$_movie", year: $_year})
  1. Use the variable in your MongoDB queries by using Variable syntax.

For more information about variables, refer to Templates and variables.

Get the most out of the plugin

Using Ad-Hoc Filters

In addition to the standard “ad-hoc filter” type variable of any name, a second helper variable must be created. It should be a “constant” type with the name mongodb_adhoc_query and a value compatible with the query editor. The query result will be used to populate the UI’s selectable filters. You may choose to hide this variable from view as it serves no further purpose.

A query of:

sample_mflix.movies.aggregate([ {"$group": { "_id": "$year"}},  {"$project": { "year": "$_id", "_id": 0 }} ] )

…and a value selected, would look like: ad_hoc_filter