Skip to content

Commit a167a0b

Browse files
Copilotranas-mukminov
Copilot
and
ranas-mukminov
committed
Update runtime dependencies to fix security vulnerabilities
Co-authored-by: ranas-mukminov <[email protected]>
1 parent d64040b commit a167a0b

File tree

8 files changed

+3783
-1651
lines changed

8 files changed

+3783
-1651
lines changed

‎dist/README.md‎

Lines changed: 181 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,134 +1,237 @@
1-
# MongoDB datasource for Grafana
1+
# MongoDB datasource for Grafana (run-as-daemon fork)
22

3-
## Features
4-
Allows MongoDB to be used as a data source for Grafana by providing a proxy to convert the Grafana Data source [API](http://docs.grafana.org/plugins/developing/datasources/) into MongoDB aggregation queries
3+
**Production-ready MongoDB datasource plugin for Grafana with professional support**
4+
5+
[English] | [Русский](README.ru.md)
6+
7+
> This is a maintained fork of [JamesOsgood/mongodb-grafana](https://github.com/JamesOsgood/mongodb-grafana) with improvements, Russian documentation, and professional SRE/DevOps services from [run-as-daemon.ru](https://run-as-daemon.ru)
8+
9+
---
10+
11+
## What this plugin does
12+
13+
This plugin allows you to use MongoDB as a data source in Grafana. It works by running a Node.js HTTP proxy server that translates Grafana's data source API calls into MongoDB aggregation pipeline queries. This enables you to visualize MongoDB data directly in Grafana dashboards without writing custom code.
14+
15+
**Key capabilities:**
16+
- Query MongoDB collections using aggregation pipelines
17+
- Time-series visualizations with automatic date range macros (`$from`, `$to`)
18+
- Template variables for dynamic dashboards
19+
- Table panel support for aggregated data
20+
- Auto-bucketing support with `$bucketAuto` and `$dateBucketCount`
21+
22+
- **Grafana**: version 3.x.x or higher
23+
- **MongoDB**: version 3.4.x or higher
24+
- **Node.js**: version 6.10.0 or higher (for running the proxy server)
525

626
## Requirements
727

8-
* **Grafana** > 3.x.x
9-
* **MongoDB** > 3.4.x
28+
- **Grafana**: >= 3.x.x
29+
- **MongoDB**: >= 3.4.x (aggregation pipeline support required)
30+
- **Node.js**: >= 6.10.0 (for the proxy server)
31+
32+
---
1033

1134
## Installation
1235

13-
### Install the Grafana plugin components
36+
### 1. Install the Grafana plugin
37+
38+
Copy the plugin directory into your Grafana plugins folder:
39+
40+
```bash
41+
# Default Grafana plugins directory
42+
cp -r dist /var/lib/grafana/plugins/mongodb-grafana
43+
44+
# Homebrew installation (macOS)
45+
cp -r dist /usr/local/var/lib/grafana/plugins/mongodb-grafana
46+
47+
# Restart Grafana
48+
sudo systemctl restart grafana-server # Linux
49+
brew services restart grafana # macOS
50+
```
51+
# Local MongoDB
52+
mongodb://localhost:27017
53+
54+
### 2. Install and start the MongoDB proxy server
55+
56+
The proxy server runs separately from Grafana and handles the MongoDB connections:
57+
58+
```bash
59+
# Install dependencies
60+
npm install
1461

15-
* Copy the whole mongodb-grafana dir into the Grafana plugins dir ( /usr/local/var/lib/grafana/plugins )
16-
* Restart the Grafana server. If installed via Homebrew, this will be `brew services restart grafana`
62+
# Build the plugin
63+
npm run build
1764

18-
### Install and Start the MongoDB proxy server
65+
# Start the proxy server (default port 3333)
66+
npm run server
67+
```
1968

20-
* Open a command prompt in the mongodb-grafana directory
21-
* Run `npm install` to install the node.js dependencies
22-
* Run `npm run server` to start the REST API proxy to MongoDB. By default, the server listens on http://localhost:3333
69+
The server will listen on `http://localhost:3333` by default.
2370

24-
## Examples
71+
---
2572

26-
Create a new data source of type MongoDB as shown below. The MongoDB details are :
73+
## Quick Start with Docker
2774

28-
* **MongoDB URL** - `mongodb://rpiread:[email protected]:27017,rpi-sensor-data-shard-00-01-ifxxs.mongodb.net:27017,rpi-sensor-data-shard-00-02-ifxxs.mongodb.net:27017/test?ssl=true&replicaSet=rpi-sensor-data-shard-0&authSource=admin`
29-
* **MongoDB Database** - `rpi`
75+
For a quick demo or development setup, use Docker Compose:
3076

31-
<img src="src/img/sample_datasource.png" alt="Sample Data Source" style="width: 500px;"/>
77+
```bash
78+
cd examples
79+
docker-compose up -d
80+
```
3281

33-
Then save the data source
82+
This starts:
83+
- Grafana on http://localhost:3000 (admin/admin)
84+
- MongoDB proxy on http://localhost:3333
85+
- MongoDB instance for testing
3486

35-
#### Example 1 - Simple aggregate to rename fields
87+
See [examples/README.md](examples/README.md) for detailed instructions.
3688

37-
Import the dashboard in `examples\RPI MongoDB - Atlas.json`
89+
---
3890

39-
This should show a graph of light sensor values from a Raspberry PI with an [EnviroPHAT](https://thepihut.com/products/enviro-phat) board feeding readings every minute into a MongoDB Atlas database.
91+
## Basic Usage
4092

41-
<img src="src/img/sample_dashboard.png" alt="Sample Dashboard" style="width: 800px;"/>
93+
### Configure the data source in Grafana
4294

43-
Clicking on the title of the graph allows you to see the aggregation query being run against the 'RPI Atlas' data source
95+
1. In Grafana, go to **Configuration → Data Sources**
96+
2. Click **Add data source**
97+
3. Select **MongoDB**
98+
4. Configure:
99+
- **Name**: Choose a descriptive name
100+
- **URL**: `http://localhost:3333` (the proxy server)
101+
- **MongoDB URL**: Your MongoDB connection string
102+
Example: `mongodb://user:pass@host:27017/database?authSource=admin`
103+
- **MongoDB Database**: The database name to query
104+
5. Click **Save & Test**
44105

45-
<img src="src/img/sample_query.png" alt="Sample Query" style="width: 800px;"/>
106+
### Write your first query
46107

47-
The query here is
108+
In a dashboard panel, use MongoDB aggregation syntax:
48109

49110
```javascript
50-
db.sensor_value.aggregate ( [
51-
{ "$match" : { "sensor_type" : "$sensor", "host_name" : "$host", "ts" : { "$gte" : "$from", "$lte" : "$to" } } },
52-
{"$sort" : {"ts" : 1}},
53-
{"$project" : { "name" : "value", "value" : "$sensor_value", "ts" : "$ts", "_id" : 0} } ])
54-
```
111+
db.collection_name.aggregate([
112+
{ "$match": { "ts": { "$gte": "$from", "$lte": "$to" } } },
113+
{ "$sort": { "ts": 1 } },
114+
{ "$project": {
115+
"name": "series_name",
116+
"value": "$field_name",
117+
"ts": "$timestamp_field",
118+
"_id": 0
119+
}}
120+
])
121+
```
55122

56-
The API is expecting back documents with the following fields
123+
**Required fields in output:**
124+
- `name` - Series name (displayed in legend)
125+
- `value` - Numeric value for the data point
126+
- `ts` - Timestamp as a BSON date
57127

58-
* `name` - Name of the series ( will be displayed on the graph)
59-
* `value` - The float value of the point
60-
* `ts` - The time of the point as a BSON date
128+
**Macros:**
129+
- `$from`, `$to` - Automatically replaced with dashboard time range (as BSON dates)
130+
- `$dateBucketCount` - Number of buckets for time-series aggregation
131+
- Template variables like `$variableName` are substituted from Grafana variables
61132

62-
These documents are then converted into the [Grafana API](http://docs.grafana.org/plugins/developing/datasources/)
133+
### Sample dashboards
63134

64-
`$from` and `$to` are expanded by the plugin as BSON dates based on the range settings on the UI.
135+
Check the [examples/](examples/) directory for:
136+
- `RPI MongoDB - Atlas.json` - Simple time-series dashboard
137+
- `RPI MongoDB Bucket - Atlas.json` - Using `$bucketAuto` for aggregation
138+
- `Sensor Value Counts - Atlas.json` - Table panel example
65139

66-
`$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.
140+
---
67141

142+
## Limitations and Notes
68143

69-
<img src="src/img/sample_template.png" alt="Sample Templates" style="width: 800px;"/>
144+
- **Aggregation only**: This plugin uses MongoDB's aggregation framework. Direct find queries are not supported.
145+
- **Time-series format**: Output documents must have `name`, `value`, and `ts` fields for graph panels.
146+
- **Table panels**: Use `_id: 0` projection and return `name`, `value`, `ts` fields.
147+
- **Authentication**: Ensure the MongoDB user has read permissions on queried collections.
148+
- **Network**: The proxy server must have network access to MongoDB and be reachable by Grafana.
70149

71-
#### Example 2 - Using $bucketAuto to push data point aggregation to the server
150+
---
72151

73-
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](https://docs.mongodb.com/manual/reference/operator/aggregation/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
152+
## Professional SRE/DevOps Services
74153

75-
```javascript
76-
db.sensor_value.aggregate( [
77-
{ "$match" : { "sensor_type" : "$sensor", "host_name" : "$host" , "ts" : { "$gte" : "$from", "$lt" : "$to" }}},
78-
{ "$bucketAuto" : { "groupBy" : "$ts",
79-
"buckets" : "$dateBucketCount",
80-
"output" : { "maxValue" : { "$max" : "$sensor_value" } } } },
81-
{ "$project" : { "name" : "value", "value" : "$maxValue", "ts" : "$_id.min", "_id" : 0 } } ] )
82-
```
83-
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
154+
This fork is maintained by **[run-as-daemon.ru](https://run-as-daemon.ru)** – a team of SRE and DevOps engineers specializing in monitoring, observability, and database operations.
84155

85-
The dashboard in `examples\RPI MongoDB Bucket - Atlas.json` shows this.
156+
### Available Services
86157

87-
#### Example 3 - Using a Tabel Panel
158+
🔧 **MongoDB + Grafana Monitoring Stack Design & Deployment**
159+
Complete setup of production-grade monitoring infrastructure with MongoDB as a data source, including HA configuration, security hardening, and custom dashboards.
88160

89-
<img src="src/img/table_panel.png" alt="Table Panel" style="width: 800px;"/>
161+
⚡ **MongoDB Performance Tuning & Index Optimization**
162+
Expert analysis and optimization of MongoDB queries, aggregation pipelines, and indexes to ensure fast dashboard load times and efficient data retrieval.
90163

91-
Table panels are now supported with queries of the form
164+
📊 **Production Dashboard & Alert Development**
165+
Custom Grafana dashboards tailored to your business metrics, SLIs/SLOs, with intelligent alerting rules integrated with your incident management tools.
92166

93-
```javascript
94-
db.sensor_value.aggregate(
95-
[
96-
{ "$match" : { "ts" : { "$gte" : "$from", "$lt" : "$to" }}},
97-
{ "$group": { "_id": { "sensor_name" : "$sensor_name", "sensor_type" : "$sensor_type" }, "cnt" : { "$sum" : 1 }, "ts" : { "$max" : "$ts" } } },
98-
{ "$project": { "name" : { "$concat" : ["$_id.sensor_name",":","$_id.sensor_type" ]}, "value" : "$cnt", "ts" : 1, "_id" : 0} }
99-
])
100-
```
167+
🏗️ **High Availability & Backup Strategies for MongoDB**
168+
Design and implementation of MongoDB replica sets, sharding strategies, automated backups, and disaster recovery procedures.
169+
170+
📈 **Observability Consulting & Training**
171+
Team training on MongoDB monitoring best practices, query optimization, and Grafana dashboard development.
172+
173+
**Contact us**: [run-as-daemon.ru](https://run-as-daemon.ru)
174+
**Email**: [email protected]
175+
**Telegram**: @run_as_daemon
176+
177+
---
178+
179+
## Support / Thanks
180+
181+
If you find this plugin useful:
182+
183+
- ⭐ **Star this repository** to show your support
184+
- 📢 **Share it** with colleagues who use Grafana + MongoDB
185+
- 💬 **Report issues** or request features via [GitHub Issues](https://github.com/ranas-mukminov/mongodb-grafana/issues)
186+
- 💝 **Sponsor**: Use the Sponsor button on GitHub or visit [run-as-daemon.ru/support](https://run-as-daemon.ru/support)
187+
188+
Your support helps maintain this project and keep it compatible with the latest Grafana and MongoDB versions.
189+
190+
---
191+
192+
## Contributing
193+
194+
Contributions are welcome! Please:
195+
1. Fork the repository
196+
2. Create a feature branch
197+
3. Make your changes (keeping compatibility with upstream)
198+
4. Submit a pull request
101199

102-
The dashboard in `examples\Sensor Values Count - Atlas.json` shows this.
200+
See our [Contributing Guidelines](CONTRIBUTING.md) for more details.
103201

104-
## Running the proxy as a service on a Mac
202+
---
105203

106-
* Install [forever-mac](https://www.npmjs.com/package/forever-mac)
107-
* Copy server/mongodb-grafana-proxy.plist to ~/Library/LaunchAgents
108-
* run `launchctl load mongodb-grafana-proxy` from ~/Library/LaunchAgents
204+
## License
109205

110-
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
206+
ISC License
111207

112-
## Development
208+
Original work by James Osgood
209+
Fork maintained by [run-as-daemon.ru](https://run-as-daemon.ru)
113210

114-
To run grafana against a dev version of the plugin on a mac using grafana installed via Homebrew
115-
116-
* Stop the grafana service `brew services stop grafana`
117-
* Open a command prompt in /debugging
118-
* Run ./start_grafana.sh
119-
* Alter code
120-
* npm run build to build the UI
121-
* Developer tools -> empty cache and hard reload
211+
---
122212

123-
Note
213+
**Made with ❤️ by the MongoDB + Grafana community and [run-as-daemon.ru](https://run-as-daemon.ru)**
124214

125-
* Homebrew grafana versions in /usr/local/Cellar
215+
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
126216

217+
---
127218

219+
## License
128220

221+
ISC License
129222

223+
Original work by James Osgood
224+
Fork maintained by [run-as-daemon.ru](https://run-as-daemon.ru)
130225

226+
---
131227

228+
## Links
132229

230+
- [Original Repository](https://github.com/JamesOsgood/mongodb-grafana)
231+
- [Grafana Documentation](https://grafana.com/docs/)
232+
- [MongoDB Aggregation Pipeline](https://docs.mongodb.com/manual/core/aggregation-pipeline/)
233+
- [run-as-daemon Services](https://run-as-daemon.ru)
133234

235+
---
134236

237+
**Made with ❤️ by the MongoDB-Grafana community and [run-as-daemon.ru](https://run-as-daemon.ru)**

0 commit comments

Comments
 (0)