Telegraf plugin
-
Telegraf is an open source agent that uses plugins to connect data sources to destinations.
Its RavenDB input plugin reads metrics from a RavenDB server's JSON monitoring endpoints and forwards them to the destination set in the Telegraf configuration, commonly InfluxDB, with the data charted by Grafana. -
The plugin reads the server, databases, indexes, and collections endpoints.
-
The plugin is included in Telegraf 1.18.0 and later, and works with RavenDB Server 5.2 and later.
-
In this article:
The RavenDB input plugin
The RavenDB input plugin polls the server, databases, indexes, and collections
endpoints at the interval set in the Telegraf configuration, and Telegraf forwards the
collected metrics to any destination it has an output plugin for.
Commonly, Telegraf stores the metrics in InfluxDB,
and Grafana charts them from there.
e.g., a live dashboard that tracks the server's CPU usage, memory usage, and indexing
activity.
The plugin reads only the four endpoints named above; the task endpoints
(etls,
ai-tasks, and
cdc-sinks)
are not covered.
To collect task metrics, read those three JSON endpoints directly, without Telegraf, or
use the
Prometheus endpoint,
whose metric set includes ETL and AI task health.
Configuring the plugin
To collect RavenDB metrics, add an [[inputs.ravendb]] section to your telegraf.conf:
[[inputs.ravendb]]
## The URL of the RavenDB node to collect metrics from
url = "https://a.example.com"
## The client certificate to use on a secure server.
## The certificate requires Operator clearance or higher.
# tls_cert = "/etc/telegraf/raven.crt"
# tls_key = "/etc/telegraf/raven.key"
## Request timeout
# timeout = "5s"
## The endpoints to read. At least one is required.
## Allowed values: server, databases, indexes, collections
# stats_include = ["server", "databases", "indexes", "collections"]
## Databases the databases endpoint reports on. Empty = all databases.
# db_stats_dbs = []
## Databases the indexes endpoint reports on. Empty = all databases.
# index_stats_dbs = []
## Databases the collections endpoint reports on. Empty = all databases.
# collection_stats_dbs = []
The options:
| Option | Description |
|---|---|
url | The URL of the RavenDB node to collect metrics from. e.g. http://localhost:8080 for an unsecure local server. |
tls_cert, tls_key | Paths to a client certificate and its private key, for a secure server. The certificate requires Operator clearance or higher. |
timeout | Request timeout.5s by default. |
stats_include | The endpoints to read: any of server, databases, indexes, collections.At least one is required; by default all four are read. |
db_stats_dbs | Databases the databases endpoint reports on.An empty list (the default) covers all databases. |
index_stats_dbs | Databases the indexes endpoint reports on.An empty list (the default) covers all databases. |
collection_stats_dbs | Databases the collections endpoint reports on.An empty list (the default) covers all databases. |
The metric names
Telegraf renames the metrics it collects: each field of an endpoint's JSON is published under a flat, lowercase name, grouped into a measurement (Telegraf's term for a named group of metrics). The plugin fills four measurements:
| Measurement | Source |
|---|---|
ravendb_server | The server endpoint |
ravendb_databases | The databases endpoint |
ravendb_indexes | The indexes endpoint |
ravendb_collections | The collections endpoint |
The published names follow the JSON structure, with a field's group and name joined and
lowercased.
e.g., the databases endpoint's Counts.Documents field becomes counts_documents in
the ravendb_databases measurement.
Note that some values are published as numeric codes where the JSON returns strings.
e.g., the JSON's Cluster.NodeState value Leader becomes: cluster_node_state = 4
The complete field lists of the four measurements are documented in the
plugin's reference.
The meaning of each value is documented on the
JSON monitoring endpoints page,
under the endpoint the measurement is built from.