Configuration¶

Where settings live¶

Every setting lives under PLUGINS_CONFIG["netbox_opentelemetry_plugin"] in NetBox's configuration.py, resolved once per process at startup. There is no live reload: change a setting, then restart the process (or the container) to pick it up.

The plugin's defaults are its own (conf.DEFAULTS), not NetBox's PluginConfig.default_settings. NetBox merges default_settings into PLUGINS_CONFIG one level deep only, so a nested dict such as exporter or logs would be replaced wholesale rather than merged key by key, and a pre-filled default would make an explicit value indistinguishable from one the operator never set, which breaks the OTEL_* environment fallback described below.

Precedence¶

For every setting, in order: an explicit PLUGINS_CONFIG value, then a signal-specific OTEL_* environment variable, then the generic OTEL_* variable, then the default. Setting OTEL_SDK_DISABLED=true in the environment disables the whole plugin. That check runs after the top-level type check and after scanning PLUGINS_CONFIG for unknown keys (any unknown-key warnings from that scan are still produced), but before every other setting is resolved.

Two things do not fit that simple per-key picture:

• The exporter.* values in PLUGINS_CONFIG (protocol, headers, timeout, insecure, certificate, insecure_skip_verify) apply to every signal at once, and an explicit exporter.* value beats even a signal-specific environment variable such as OTEL_EXPORTER_OTLP_TRACES_TIMEOUT.
• The plugin has no per-signal headers or timeout setting of its own in PLUGINS_CONFIG. To give one signal its own headers or timeout, use the signal-specific environment variable (OTEL_EXPORTER_OTLP_<SIGNAL>_HEADERS, OTEL_EXPORTER_OTLP_<SIGNAL>_TIMEOUT) instead, and leave exporter.headers / exporter.timeout unset in PLUGINS_CONFIG.

Endpoints¶

Each signal (logs, traces, metrics) resolves its own OTLP endpoint in this order:

1. The signal's own endpoint (logs.endpoint, traces.endpoint, metrics.endpoint), used as is.
2. exporter.endpoint. Over HTTP, the signal's path is appended; over gRPC, the value is used as is.
3. OTEL_EXPORTER_OTLP_<SIGNAL>_ENDPOINT (for example OTEL_EXPORTER_OTLP_TRACES_ENDPOINT), used as is.
4. OTEL_EXPORTER_OTLP_ENDPOINT. Over HTTP, the signal's path is appended; over gRPC, the value is used as is.

If none of these resolve to a value, that signal logs one warning and disables itself; the rest of the plugin keeps running.

For example, with exporter.endpoint = "http://collector:4318" and the default HTTP protocol, logs export to http://collector:4318/v1/logs, traces to http://collector:4318/v1/traces, and metrics to http://collector:4318/v1/metrics. Over gRPC, exporter.endpoint = "http://collector:4317" is used as is for every signal, since gRPC has no per-signal path.

Audit records use the logs endpoint: logs.endpoint, then exporter.*, the same order as above. This means audit records still export even with logs.enabled = False, as long as an endpoint resolves for the logs pipeline.

Reference¶

Every key in conf.DEFAULTS, its default, and its environment fallback if it has one.

Other environment variables¶

These are read by the OpenTelemetry SDK or the OTLP exporters directly, not by this plugin's own configuration code, so there is no corresponding PLUGINS_CONFIG key:

• OTEL_RESOURCE_ATTRIBUTES: merged into the Resource by the SDK itself, underneath resource_attributes and the plugin's own resource keys. See How it works.
• OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE: honoured by the metrics exporter; the default is cumulative temporality.
• OTEL_SEMCONV_STABILITY_OPT_IN: the plugin sets this to http (selecting the stable HTTP semantic conventions) unless it is already set in the environment, so an operator's own value is always kept.
• OTEL_PROPAGATORS: selects the trace-context formats used for inbound and outbound HTTP (default tracecontext,baggage). Baggage propagation is off, whatever this variable lists, in every process where the plugin's traces or metrics are on (web and worker processes); see Traces, baggage.

Validation¶

The plugin resolves PLUGINS_CONFIG once per process, and a bad value never stops NetBox from starting:

• An unknown key logs one warning and is otherwise ignored (this does not apply inside exporter.headers or resource_attributes, whose keys are chosen by the operator).
• A wrong type or an invalid value inside logs, audit, traces, metrics or rq disables only that section, with one warning; the rest of the plugin keeps running.
• An invalid exporter.* value (protocol, timeout, headers, insecure, certificate, insecure_skip_verify) is resolved separately for each enabled signal, so it disables every enabled signal that uses the exporter, each with its own warning: logs and audit together (they share one exporter), traces, and metrics, whichever of those are enabled. A signal that is off to begin with is not affected, since its exporter is never resolved.
• An invalid top-level value (enabled, service_name, resource_attributes or exporter not of the expected type) disables the whole plugin, with one warning.
• A signal with no endpoint that resolves at all logs one warning and disables itself; the other signals are unaffected.
• The resolved configuration is logged once at DEBUG level, with every header value replaced and any URL credentials in an endpoint replaced by ***.

Every one of these warnings goes to the netbox_opentelemetry_plugin logger and is never exported: nothing about a misconfiguration leaves the process. With NetBox's default LOGGING = {}, that logger has no handler of its own, so a warning falls through to Python's last-resort handler, which writes to stderr; configure LOGGING to send it elsewhere. See Failure behaviour and Data safety.

Examples¶

Each example below is a complete PLUGINS_CONFIG block.

Minimal, everything else at its default (the endpoint can also come from OTEL_EXPORTER_OTLP_ENDPOINT instead):

PLUGINS_CONFIG = {
    "netbox_opentelemetry_plugin": {
        "exporter": {"endpoint": "http://collector:4318"},
    },
}

gRPC, with a bearer token header and a private CA certificate:

PLUGINS_CONFIG = {
    "netbox_opentelemetry_plugin": {
        "exporter": {
            "endpoint": "collector.example.com:4317",
            "protocol": "grpc",
            "headers": {"authorization": "Bearer secret-token"},
            "certificate": "/etc/ssl/certs/otel-ca.pem",
        },
    },
}

HTTP to a Collector behind a self-signed certificate, without verifying it (see exporter.insecure_skip_verify above before using this outside a lab):

PLUGINS_CONFIG = {
    "netbox_opentelemetry_plugin": {
        "exporter": {
            "endpoint": "https://collector.lab.example:4318",
            "insecure_skip_verify": True,
        },
    },
}

Traces and metrics on, sampling 10% of traces:

PLUGINS_CONFIG = {
    "netbox_opentelemetry_plugin": {
        "exporter": {"endpoint": "http://collector:4318"},
        "traces": {"enabled": True, "sampler": "parentbased_traceidratio", "sampler_arg": 0.1},
        "metrics": {"enabled": True},
    },
}

A separate Collector per signal, each given as a full endpoint URL:

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

Audit records with field values included, and a longer list of excluded fields:

PLUGINS_CONFIG = {
    "netbox_opentelemetry_plugin": {
        "exporter": {"endpoint": "http://collector:4318"},
        "audit": {
            "include_data": True,
            "exclude_fields": ["password", "secret", "token", "key", "api_key", "private_key"],
        },
    },
}