Registry / devops / spm-agent-mongodb

spm-agent-mongodb

library3.0.4jsnpmunverified

SPM Agent for MongoDB (v3.0.4) is a monitoring agent that collects and reports MongoDB metrics to Sematext Cloud (APM). It supports MongoDB clusters, replica sets, and standalone instances, providing real-time visibility into performance, queries, connections, and disk usage. The agent runs as a system service and requires Node.js and admin privileges (ClusterAdmin role) to access MongoDB internal metrics. Key differentiators include seamless integration with Sematext's monitoring stack, support for Kerberos authentication, Docker deployment via SPM-Client image, and automatic anomaly detection. It is released regularly but no fixed cadence is published.

devops

npm install spm-agent-mongodb

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SPM-AGENT-MONGODB

spm-agent-mongodb

devopsjavascriptv3.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SPM Agent for MongoDB (CLI tool)

✓ Install globally: npm i spm-agent-mongodb -g

✗ Cannot be imported as a module; use spm-mongodb-setup or spm-agent-mongodb CLI.

This package is a CLI agent, not a library. It is installed globally or used via Docker. No programmatic imports.

MongoDB metrics agent

✓ spm-agent-mongodb TOKEN URL

✗ Do not use require() as it is a CLI tool.

Run from command line: spm-agent-mongodb <SPM_TOKEN> <MONGODB_URL>. Also configurable via environment or config file.

Installs the agent globally, configures it with a Sematext token and MongoDB URL, then starts the monitoring agent as a service or interactive process.

sudo npm i spm-agent-mongodb -g sudo spm-mongodb-setup -t YOUR_SPM_TOKEN -m mongodb://localhost:27017/local # Then start the agent as a service (systemd): sudo systemctl start spm-agent-mongodb # Or run directly: spm-agent-mongodb YOUR_SPM_TOKEN mongodb://localhost:27017/local

Debug

Known issues

gotchaThe agent requires admin rights (ClusterAdmin role) and read access to any database. Without proper permissions, metrics collection will fail silently.

fix

Grant clusterMonitor role or clusterAdmin and read on any database to the MongoDB user used by the agent.

affects: >=0.0.0

gotchaKerberos authentication requires libkrb5-dev system package. Missing it leads to build failures during npm install.

fix

Install libkrb5-dev via apt-get before npm install: apt-get install libkrb5-dev

affects: >=0.0.0

deprecatedEarlier versions used a different config file location and format. v3.x uses /etc/sematext/spm-agent-mongodb.config.

fix

Migrate from old config (e.g., /etc/spm-agent-mongodb.cfg) to new location and format.

affects: >=3.0.0

gotchaThe agent does not support running multiple instances on the same host out-of-the-box; each MongoDB cluster requires a separate agent installation or Docker container.

fix

Deploy multiple Docker containers for different MongoDB endpoints.

affects: >=0.0.0

gotchaThe setup script spm-mongodb-setup may overwrite existing config file if run again. Backup your config before re-running.

fix

Backup /etc/sematext/spm-agent-mongodb.config before running spm-mongodb-setup again.

affects: >=0.0.0

Errors

Common errors & fixes

Error: getaddrinfo ENOTFOUND apps.sematext.com

DNS resolution failure when connecting to Sematext US endpoint.

fix

If using Sematext EU, run 'sudo spm-mongodb-setup -r EU' to configure EU API endpoints.

MongoError: not authorized on db to execute command

Agent's MongoDB user lacks required roles.

fix

Ensure the MongoDB user has clusterMonitor and read on any database roles.

npm ERR! gyp: No 'target_arch' was specified.

Missing system build tools (C++ compiler, make) required for Kerberos native module.

fix

Install build-essential: sudo apt-get install build-essential

Upgrade

Version history

3.0.4latest on npm

Audit

Dependencies

mongodbrequiredNative MongoDB driver for Node.js; required to connect and query MongoDB instances.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/sematext/spm-agent-mongodb ↗

packagespm-agent-mongodb ↗

homepagehttp://www.sematext.com ↗