netbox-opentelemetry-plugin

netbox-opentelemetry-plugin exports NetBox telemetry (logs, audit records, traces and metrics) 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

Compatibility

min_version = "4.7.0" and max_version = "4.7.99" in the plugin's PluginConfig enforce this NetBox range; NetBox refuses to load the plugin outside it.

Dependencies

Installing the package pulls in these OpenTelemetry packages, no others:

• opentelemetry-api ~= 1.44.0
• opentelemetry-sdk ~= 1.44.0
• opentelemetry-exporter-otlp-proto-http ~= 1.44.0
• opentelemetry-exporter-otlp-proto-grpc ~= 1.44.0
• opentelemetry-instrumentation-django == 0.65b0
• opentelemetry-instrumentation-psycopg == 0.65b0
• opentelemetry-instrumentation-redis == 0.65b0
• opentelemetry-instrumentation-requests == 0.65b0
• opentelemetry-instrumentation-system-metrics == 0.65b0

No NetBox model, no database migration and no UI of its own.

Quick start

Install the package into the NetBox virtual environment:

source /opt/netbox/venv/bin/activate
pip install netbox-opentelemetry-plugin

netbox-docker's venv has no pip, only uv: use uv pip install netbox-opentelemetry-plugin in a custom image built on top of the upstream one. See the installation page for netbox-docker, the Helm chart, and bare metal gunicorn and uWSGI.

Enable the plugin in configuration.py:

PLUGINS = ["netbox_opentelemetry_plugin"]
PLUGINS_CONFIG = {
    "netbox_opentelemetry_plugin": {
        "exporter": {"endpoint": "http://otel-collector:4318"},
    },
}

Turn on traces and metrics too:

PLUGINS_CONFIG = {
    "netbox_opentelemetry_plugin": {
        "exporter": {"endpoint": "http://otel-collector:4318"},
        "traces": {"enabled": True},
        "metrics": {"enabled": True},
    },
}

Restart the NetBox web processes and the RQ workers to pick up the change.

Documentation

• Full documentation
• Installation
• Configuration reference
• Logs, audit records, traces, metrics
• How it works
• Data safety
• Failure behaviour
• Collector on Kubernetes
• Limitations
• Changelog

Licence

Apache 2.0. See the LICENSE file.