SNMP: Overview
SNMP support requires a license that includes the SNMP feature.
-
This page explains monitoring RavenDB over SNMP and lists the available metrics.
-
In this article:
Overview
-
SNMP (Simple Network Management Protocol) is an Internet-standard protocol for monitoring devices on IP networks.
A monitored device exposes its status as a set of variables (metrics), and monitoring applications query these variables remotely. -
RavenDB exposes a long list of metrics over SNMP, indicating: CPU and memory usage, request rates, the loaded databases, and per-database metrics like the number of documents written per second and the storage size a database takes.
Monitoring tools like Zabbix, PRTG, and Datadog read these metrics directly. -
You can also monitor a server using Studio or the JSON monitoring endpoints.
SNMP suits large deployments: rather than watch each of many RavenDB instances individually, you connect all of them to one monitoring system.
Enabling SNMP in RavenDB
-
To monitor RavenDB using SNMP, you must first set the Monitoring.Snmp.Enabled configuration key to
true. -
Learn how to customize configuration keys in the Configuration Overview article.
-
For example, add this key to your
settings.jsonfile and restart the server.{..."Monitoring.Snmp.Enabled": true...}
SNMP configuration options
There are several configurable SNMP properties in RavenDB:
General:
These keys apply regardless of the SNMP version in use.
- Monitoring.Snmp.Port
The SNMP port.
Default:161 - Monitoring.Snmp.SupportedVersions
List of supported SNMP versions.
Default:"V2C;V3"
For SNMPv2c:
- Monitoring.Snmp.Community
The community string is used as a password.
It is sent with each SNMPGETrequest and allows or denies access to the monitored device.
Default:"ravendb"
For SNMPv3:
- Monitoring.Snmp.AuthenticationProtocol
Authentication protocol.
Default:"SHA1" - Monitoring.Snmp.AuthenticationUser
The user for authentication.
Default:"ravendb" - Monitoring.Snmp.AuthenticationPassword
The authentication password.
When set tonullthe community string is used instead.
Default:null - Monitoring.Snmp.PrivacyProtocol
Privacy protocol.
Default:None - Monitoring.Snmp.PrivacyPassword
Privacy password.
Default:"ravendb"
See Monitoring Options for the full list of SNMP configuration keys.
The Metrics
Access metrics via monitoring tools
- Querying the exposed metrics using a monitoring tool is typically straightforward.
To set up Zabbix using the RavenDB community template, see Zabbix monitoring.
Access metrics via SNMP agents
-
The metrics can be accessed directly using any SNMP agent such as Net-SNMP.
Each metric has a unique object identifier (OID) and can be accessed individually. -
The most basic SNMP commands are
snmpget,snmpsetandsnmpwalk.
For example, you can execute the followingsnmpgetcommands to retrieve the server's up-time metric.For SNMPv2c:
# Request:snmpget -v 2c -c ravendb live-test.ravendb.net 1.3.6.1.4.1.45751.1.1.1.3# Result:iso.3.6.1.4.1.45751.1.1.1.3 = Timeticks: (29543973) 3 days, 10:03:59.73
ravendbis the community string (set via the Monitoring.Snmp.Community configuration key)."live-test.ravendb.net"is the host.
For SNMPv3:
snmpget -v 3 -l authNoPriv -u ravendb -a SHA \-A ravendb live-test.ravendb.net 1.3.6.1.4.1.45751.1.1.1.3
-l authNoPriv- sets the security level to use authentication but no privacy.-u ravendb- sets the user for authentication purposes toravendb.-a SHA- sets the authentication protocol to SHA.-A ravendb- sets the authentication password toravendb.
Access metrics via HTTP
On a secure server, these HTTP requests must present a client certificate with
Operator
clearance or higher.
On an unsecure server, no certificate is needed.
Access single OID value:
-
An individual OID value can be retrieved via HTTP
GETendpoint:
<serverUrl>/monitoring/snmp?oid=<oid> -
For example, a cURL request for the server up-time metric:
# Request:curl -X GET http://live-test.ravendb.net/monitoring/snmp?oid=1.3.6.1.4.1.45751.1.1.1.3# Result:{ "Value" : "4.21:32:56.0700000" }
Access multiple OID values:
-
Multiple OID values can be retrieved by making either a
GETor aPOSTrequest to the following HTTP endpoint:<serverUrl>/monitoring/snmp/bulk -
For example, cURL requests for the server managed memory and unmanaged memory metrics:
curl -X GET "http://live-test.ravendb.net/monitoring/snmp/bulk? \oid=1.3.6.1.4.1.45751.1.1.1.6.7&oid=1.3.6.1.4.1.45751.1.1.1.6.8"curl -X POST \-H "Content-Type: application/json" \-d '{ "OIDs": ["1.3.6.1.4.1.45751.1.1.1.6.7", "1.3.6.1.4.1.45751.1.1.1.6.8"]}' \http://localhost:8080/monitoring/snmp/bulk{"Results": [{ "OID": "1.3.6.1.4.1.45751.1.1.1.6.7", "Value": "410" },{ "OID": "1.3.6.1.4.1.45751.1.1.1.6.8", "Value": "4" }]}
-
You can get a list of all OIDs along with their description via this HTTP
GETendpoint:
<serverUrl>/monitoring/snmp/oids -
For example: http://live-test.ravendb.net/monitoring/snmp/oids
Rate values explained
Several OIDs below carry a (one minute rate) or (five second rate) qualifier.
The rates differ in the period they average over:
-
One minute rate
The number of events per second, averaged over the last 60 seconds.
Short bursts are smoothed out into the average. -
Five second rate
The number of events per second, averaged over the last 5 seconds.
Brief spikes stay visible instead of being averaged away.
When you monitor a metric, pick the qualifier that matches your goal:
- Use the one minute rate to track sustained load and longer-term trends.
- Use the five second rate to catch short bursts and request spikes as they happen.
List of OIDs
-
RavenDB's root OID is: 1.3.6.1.4.1.45751.1.1.
-
Values represented by
X,D, orIin the OIDs list below will be:X:
0- any kind of collection
1- a generation-0 or generation-1 collection
2- a blocking generation-2 collection
3- a background collection (this is always a generation 2 collection)D- Database numberI- Index numberT- Task number (used for per-task ETL, AI, and CDC Sink OIDs)
Server OIDs
| OID | Metric (Server) |
|---|---|
| 1.1.1 | Server URL |
| 1.1.2 | Server Public URL |
| 1.1.3 | Server TCP URL |
| 1.1.4 | Server Public TCP URL |
| 1.2.1 | Server version |
| 1.2.2 | Server full version |
| 1.3 | Server up-time |
| 1.3.6.1.2.1.1.3.0 | Server up-time (global) |
| 1.4 | Server process ID |
| 1.5.1 | Process CPU usage in % |
| 1.5.2 | Machine CPU usage in % |
| 1.5.3.1 | CPU Credits Base |
| 1.5.3.2 | CPU Credits Max |
| 1.5.3.3 | CPU Credits Remaining |
| 1.5.3.4 | CPU Credits Gained Per Second |
| 1.5.3.5 | CPU Credits Background Tasks Alert Raised |
| 1.5.3.6 | CPU Credits Failover Alert Raised |
| 1.5.3.7 | CPU Credits Any Alert Raised |
| 1.5.4 | IO wait in % |
| 1.5.5 | Number of open file descriptors (Linux only) |
| 1.5.6.1 | Machine load average over 1 minute (Linux only) |
| 1.5.6.2 | Machine load average over 5 minutes (Linux only) |
| 1.5.6.3 | Machine load average over 15 minutes (Linux only) |
| 1.6.1 | Server allocated memory in MB |
| 1.6.2 | Server low memory flag value |
| 1.6.3 | Server total swap size in MB |
| 1.6.4 | Server total swap usage in MB |
| 1.6.5 | Server working set swap usage in MB |
| 1.6.6 | Dirty Memory that is used by the scratch buffers in MB |
| 1.6.7 | Server managed memory size in MB |
| 1.6.8 | Server unmanaged memory size in MB |
| 1.6.9 | Server encryption buffers memory being in use in MB |
| 1.6.10 | Server encryption buffers memory being in pool in MB |
1.6.11.X.1 | GC info for X.Specifies if this is a compacting GC or not. |
1.6.11.X.2 | GC info for X.Specifies if this is a concurrent GC or not. |
1.6.11.X.3 | GC info for X.Gets the number of objects ready for finalization this GC observed. |
1.6.11.X.4 | GC info for X.Gets the total fragmentation (in MB) when the last garbage collection occurred. |
1.6.11.X.5 | GC info for X.Gets the generation this GC collected. |
1.6.11.X.6 | GC info for X.Gets the total heap size (in MB) when the last garbage collection occurred. |
1.6.11.X.7 | GC info for X.Gets the high memory load threshold (in MB) when the last garbage collection occurred. |
1.6.11.X.8 | GC info for X.The index of this GC. |
1.6.11.X.9 | GC info for X.Gets the memory load (in MB) when the last garbage collection occurred. |
1.6.11.X.10.1 | GC info for X.Gets the pause durations. First item in the array. |
1.6.11.X.10.2 | GC info for X.Gets the pause durations. Second item in the array. |
1.6.11.X.11 | GC info for X.Gets the pause time percentage in the GC so far. |
1.6.11.X.12 | GC info for X.Gets the number of pinned objects this GC observed. |
1.6.11.X.13 | GC info for X.Gets the promoted MB for this GC. |
1.6.11.X.14 | GC info for X.Gets the total available memory (in MB) for the garbage collector to use when the last garbage collection occurred. |
1.6.11.X.15 | GC info for X.Gets the total committed MB of the managed heap. |
1.6.11.X.16.3 | GC info for X.Gets the large object heap size (in MB) after the last garbage collection of given kind occurred. |
| 1.6.12.0 | Monitor /proc/meminfo/ metrics (unix/linux). The description of each metric is available via endpoint <serverUrl>/monitoring/snmp/oids.See Get all OIDs. |
| 1.6.13 | Available memory for processing (in MB) |
| 1.6.14 | Available memory for processing (in %) |
| 1.7.1 | Number of concurrent requests |
| 1.7.2 | Total number of requests since server startup |
| 1.7.3 | Number of requests per second (one minute rate) |
| 1.7.3.1 | Number of requests per second (five second rate) |
| 1.7.4 | Average request time in milliseconds |
| 1.8 | Server last request time |
| 1.8.1 | Server last authorized non cluster admin request time |
| 1.9.1 | Server license type |
| 1.9.2 | Server license expiration date |
| 1.9.3 | Server license expiration left |
| 1.9.4 | Server license utilized CPU cores |
| 1.9.5 | Server license max CPU cores |
| 1.10.1 | Server storage used size in MB |
| 1.10.2 | Server storage total size in MB |
| 1.10.3 | Remaining server storage disk space in MB |
| 1.10.4 | Remaining server storage disk space in % |
| 1.10.5 | IO read operations per second |
| 1.10.6 | IO write operations per second |
| 1.10.7 | Read throughput in kilobytes per second |
| 1.10.8 | Write throughput in kilobytes per second |
| 1.10.9 | Queue length |
| 1.11.1 | Server certificate expiration date |
| 1.11.2 | Server certificate expiration left |
| 1.11.3 | List of well known admin certificate thumbprints |
| 1.11.4 | List of well known admin certificate issuers |
| 1.11.5 | Number of expiring certificates |
| 1.11.6 | Number of expired certificates |
| 1.12.1 | Number of processor on the machine |
| 1.12.2 | Number of assigned processors on the machine |
| 1.13.1 | Number of backups currently running |
| 1.13.2 | Max number of backups that can run concurrently |
| 1.14.1 | Number of available worker threads in the thread pool |
| 1.14.2 | Number of available completion port threads in the thread pool |
| 1.15.1 | Number of active TCP connections |
| 1.16.1 | Indicates if any experimental features are used |
| 1.17.1 | Value of the '/proc/sys/vm/max_map_count' parameter |
| 1.17.2 | Number of current map files in '/proc/self/maps' |
| 1.17.3 | Value of the '/proc/sys/kernel/threads-max' parameter |
| 1.17.4 | Number of current threads |
| 1.18.1 | Monitor lock contention count |
| 1.19.1 | Time since creation of oldest transaction |
| 1.20.1 | Total number of ETL errors |
| 1.20.2 | Number of ETL tasks with Healthy health status |
| 1.20.3 | Number of ETL tasks with Impaired health status |
| 1.20.4 | Number of ETL tasks with Failed health status |
| 1.20.5 | Total number of ETL tasks |
| 1.20.6 | Number of active ETL tasks (processed at least one batch in the last minute) |
| 1.21.1 | Total number of AI task errors |
| 1.21.2 | Number of AI tasks with Healthy health status |
| 1.21.3 | Number of AI tasks with Impaired health status |
| 1.21.4 | Number of AI tasks with Failed health status |
| 1.21.5 | Total number of AI tasks |
| 1.21.6 | Number of active AI tasks (processed at least one batch in the last minute) |
| 1.22.1 | Total number of CDC Sink errors |
| 1.22.2 | Number of CDC Sink tasks with Healthy health status |
| 1.22.3 | Number of CDC Sink tasks with Impaired health status |
| 1.22.4 | Number of CDC Sink tasks with Failed health status |
| 1.22.5 | Total number of CDC Sink tasks |
| 1.22.6 | Number of active CDC Sink tasks (processed at least one batch in the last minute) |
Cluster OIDs
| OID | Metric (Cluster) |
|---|---|
| 3.1.1 | Current node tag |
| 3.1.2 | Current node state |
| 3.2.1 | Cluster term |
| 3.2.2 | Cluster index |
| 3.2.3 | Cluster ID |