NetBox and Nautobot¶

Two packages report platform job runs to the value ledger: the netbox-lumatrack plugin and the nautobot-lumatrack app. Install one, restart the workers, and every job your platform finishes shows up as measured evidence.

Both are built on one shared core, so they behave identically apart from the hook each platform gives them.

Install¶

For NetBox, inside its virtualenv:

pip install netbox-lumatrack

# /opt/netbox/netbox/netbox/configuration.py
PLUGINS = ["netbox_lumatrack"]

PLUGINS_CONFIG = {
    "netbox_lumatrack": {
        "api_url": "https://lumatrack.io",
        "api_key": "lmt_...",
    },
}

sudo systemctl restart netbox netbox-rq

For Nautobot:

pip install nautobot-lumatrack

# nautobot_config.py
PLUGINS = ["nautobot_lumatrack"]

PLUGINS_CONFIG = {
    "nautobot_lumatrack": {
        "api_url": "https://lumatrack.io",
        "api_key": "lmt_...",
    },
}

sudo systemctl restart nautobot nautobot-worker

The worker restart is the one people miss

Jobs run in the worker process (RQ for NetBox, Celery for Nautobot), so that is where the receiver has to be loaded. Restarting only the web process leaves a plugin that reports nothing and looks broken.

Add the package to local_requirements.txt so a platform upgrade keeps it.

The API key¶

An ingest-only key is enough and is the one to use: if it leaks, an attacker can post junk runs, and they cannot read or restate your ledger. Create it in LumaTrack under Settings, API keys.

Leave api_url and api_key out of the config file and both packages read LUMATRACK_API_URL and LUMATRACK_API_KEY from the environment, which is how a containerized install supplies a key without writing it into a config file.

Settings¶

Setting	Default	Notes
`api_url`	from `LUMATRACK_API_URL`	Your LumaTrack host
`api_key`	from `LUMATRACK_API_KEY`	Ingest-only key from Settings, API keys
`automation_map`	`{}`	Job name to automation slug
`only_jobs`	`[]`	When set, only these job names report
`slugify_unmapped`	`True`	Report unmapped jobs under the slugified job name
`timeout`	`5.0`	Seconds. Short on purpose, so a LumaTrack outage cannot slow jobs down
`enabled`	`True`	Set `False` to stop reporting without uninstalling

Job names become slugs¶

LumaTrack builds an automation's slug by slugifying its name, and both packages slugify the job name the same way. Name the automation after the job and reporting works with no mapping at all:

Platform job	Reports as
Device Onboarding	`device-onboarding`
Sync Cisco DNA (prod)	`sync-cisco-dna-prod`

When the names differ, map them, and use only_jobs to keep the integration to the jobs you actually want measured:

"automation_map": {"Device Onboarding": "onboarding-v2"},
"only_jobs": ["Device Onboarding", "Nightly Config Backup"],

Without only_jobs every job the platform runs is reported, its own system jobs included. Each one whose slug matches no automation gets a 404 back, logged as a warning and otherwise harmless, so only_jobs is mostly about keeping the log quiet.

Statuses¶

NetBox	Nautobot	Recorded as	Reason
`completed`	`SUCCESS`	`success`
`errored`	`FAILURE`	`failure`	`netbox/errored`, `nautobot/failure`
`failed`		`failure`	`netbox/failed`
	`REVOKED`	`cancelled`	`nautobot/revoked`

Failures report exactly like successes, because they cost money and save nothing and the ledger prices that honestly. Nautobot's REVOKED is an operator stopping a job: it did not break, so it books as a cancellation and stays out of the failure count. Whether a cancellation carries the automation's per-run cost is set per automation.

The reason recorded is a category rather than the error text, which is what keeps the failure-reason Pareto readable. The message and traceback go into the run's metadata instead.

Duration and idempotency¶

Duration comes from the platform's own timestamps: started to completed on NetBox, date_started to date_done on Nautobot. A job with no recorded start reports no duration rather than a guessed one.

The external id is the platform's own execution id, prefixed per platform (netbox-<job_id>, nautobot-<pk>). A repeated delivery is an idempotent replay the ledger answers with a 200 instead of a second run. This matters more on Nautobot, where the hook is post_save and one finished job can be saved several times.

Reporting cannot break your platform¶

Both receivers run inline while the platform finishes a job, so both are built to stay out of the way. The HTTP timeout is 5 seconds by default. Neither receiver can raise: NetBox's signal comes from inside Job.terminate() and Nautobot's post_save runs inside the caller's transaction, so an exception escaping either one would break the platform's own job bookkeeping.

Everything therefore goes to a log rather than to an exception. Watch the lumatrack_ledger logger:

LOGGING = {
    "version": 1,
    "loggers": {"lumatrack_ledger": {"handlers": ["console"], "level": "INFO"}},
}

It records each recorded run, each refusal with the server's own message, each run held over the plan's monthly cap, and each field the server did not recognize. A non-empty ignored-fields list means a payload key was misspelled; treat it as a bug rather than a silent success.

Reporting from a job instead¶

If you want a job to report its own volume, e.g. one run with units set to the number of devices it touched, call the API from the job directly with the Python emitter or plain HTTP. The plugin reports one run per job execution with units left at the server default of 1, which is the right shape for a job whose value is per execution rather than per record.