netbox-opentelemetry-plugin¶
netbox-opentelemetry-plugin exports NetBox telemetry over OTLP to an OpenTelemetry Collector, directly from inside the NetBox processes (web workers, RQ workers, RQ work-horses). Each signal is an independent module, switched on or off in configuration.
Signals¶
| Signal | Default | Description |
|---|---|---|
| Logs | on | NetBox's Python logs, exported through the OTel Logs API. |
| Audit records | on | One structured record per ObjectChange (create, update, delete). |
| Traces | off | Spans for Django requests, PostgreSQL, Redis, outbound HTTP and RQ jobs. |
| Metrics | off | HTTP and job metrics, change counters, optional process runtime metrics. |
Quick start¶
Install the package into the NetBox virtual environment (see Installation), then add this to configuration.py:
PLUGINS = ["netbox_opentelemetry_plugin"]
PLUGINS_CONFIG = {
"netbox_opentelemetry_plugin": {
"exporter": {"endpoint": "http://otel-collector:4318"},
},
}
Restart NetBox and the RQ workers to pick up the change.
Compatibility¶
| Plugin | NetBox | Python |
|---|---|---|
| 0.4.x | 4.7.2 to 4.7.x | 3.12, 3.13, 3.14 |
| 0.1.x to 0.3.x | 4.7.0 to 4.7.x | 3.12, 3.13, 3.14 |
NetBox 4.7.0 and 4.7.1 recorded plaintext API tokens created through background bulk requests in job results, fixed in 4.7.2. On those versions, upgrade NetBox before upgrading the plugin to 0.4.x, or stay on 0.3.x: NetBox skips a plugin whose min_version is above its own version with a warning, and nothing is exported.
What stays outside the exporters¶
Some things never go through the plugin's exporters, and are left to stdout, stderr and platform log collection instead:
- Web server access logs, typically on stdout.
- Startup errors and crashes, typically on stderr.
- The plugin's own warnings, on the
netbox_opentelemetry_pluginlogger, which is never exported; with NetBox's defaultLOGGING = {}these reach stderr through Python's last-resort handler.
Related work¶
There is a related upstream request to bring native OpenTelemetry support into NetBox core: netbox-community/netbox#22642.