Turning NetBox change events into Grafana annotations

#netbox #grafana #networking #opensource

NetBox is the source of truth for what's supposed to be true about your network — but Grafana is where people actually watch it behave, and today those two are disconnected. An engineer re-roles a device or flips a status, and nothing marks that moment anywhere near the graphs that matter. Debugging "did anything change around when this started" means manually opening NetBox's changelog and eyeballing timestamps against a graph.

I built a NetBox plugin to close that gap automatically.

How it works

You edit an object in NetBox — a device role change, a status flip, whatever your Event Rule is scoped to.
NetBox's own Event Rule/Webhook system (no custom signal handling) fires a POST at the plugin.
The plugin resolves which Grafana dashboard/panel that object maps to — either a Grafana tag search (netbox:{object_type}:{object_name}) or a NetBox custom field override — and posts an annotation via Grafana's Annotations API.
The marker's already on the graph before anyone thinks to look for it.

Where this actually helps

Correlating changes with metric shifts, either direction — a change just landed, did anything break? Or something broke, what changed recently? Same value, whichever direction you're coming from.
Faster incident triage — when several changes land close together, seeing them against real metrics narrows down which one's the likely cause vs. coincidence.
On-call gut check — a page fires, you glance at the graph, see a marker, and immediately know "yes, that's the change we just made."
Bridges NetOps and SRE/NOC tooling — neither team has to learn the other's tool to get the correlation.

Setup

pip install git+https://github.com/mfarook2/netbox-grafana-annotations-plugin

PLUGINS = ["netbox_grafana_annotations_plugin"]

PLUGINS_CONFIG = {
    "netbox_grafana_annotations_plugin": {
        "grafana_url": "https://grafana.example.com",
        "grafana_token": "<Grafana API token, Bearer auth>",
        "webhook_secret": "<random string, must match the NetBox Webhook's Secret>",
    },
}

Full setup walkthrough (Grafana token, webhook, event rule, dashboard tagging) is in the README.

One limitation, stated plainly

A marker means "this was recorded in NetBox at this time," not "the device's behavior changed at this time." NetBox doesn't push config to devices itself. For teams that deploy close-in-time to NetBox edits, that gap is usually minutes — but it's not a claim of exact causation, and I didn't want to market it as one.