Skip to content
Nebula logoNebula logoNebula Docs

stats

Nebula can provide stats for Graphite or Prometheus. Options passed / required will depend on stats.type.

stats:
  type: graphite
  prefix: nebula
  protocol: tcp
  host: 127.0.0.1:9999
  interval: 10s


  message_metrics: false
  lighthouse_metrics: false
stats:
  type: prometheus
  listen: 127.0.0.1:8080
  path: /metrics
  namespace: prometheusns
  subsystem: nebula
  interval: 10s

stats.type

Section titled “stats.type”
Reloadable

Choose your stats provider. Options are graphite and prometheus. If unset or none, nebula will not report statistics to a provider. This will determine other available options. A difference between the two is that Prometheus is a polling based system, whereas Graphite is push based.

stats.interval

Section titled “stats.interval”
Required Reloadable

The speed at which Graphite will push stats updates to the consumer + the speed at which some internal services will push updates to the main stats service.

A golang Duration. Recommended to be set to 60s.

Gauges such as certificate.*, firewall.*, hostmap.*, and the per-socket udp.* stats are refreshed at this interval.

stats.message_metrics

Section titled “stats.message_metrics”
Default: false

Enables counter metrics for meta packets, e.g.: messages.tx.handshake_ixpsk0. NOTE: messages.{tx,rx}.recv_error is always emitted.

stats.lighthouse_metrics

Section titled “stats.lighthouse_metrics”
Default: false

Enables detailed counter metrics for lighthouse packets, e.g.: lighthouse.rx.HostQuery.

Notable metrics

Section titled “Notable metrics”

Some metrics worth watching:

Metric Meaning
udp.tx.dropped Packets queued for a batched UDP send that were not written, including ones to unreachable or stale remotes
udp.gro.enabled, udp.gso.enabled Linux only. 1 when the UDP socket is using GRO or GSO, see listen.udp_offloads
lighthouse.query.dropped Lighthouse queries dropped because handshakes.query_buffer was full
handshake_manager.rejected.blocklisted Handshakes refused because the peer's certificate is in pki.blocklist
messages.tx.exhausted Packets dropped because a tunnel's message counter reached its limit. Only with stats.message_metrics: true

With Prometheus, Nebula also exports an info gauge whose labels carry the version, goversion, boringcrypto, fips140Version, fips140Enabled, and fips140Enforced of the running binary.

Graphite options

Section titled “Graphite options”

Config options if stats.type is chosen to be graphite

stats.prefix

Section titled “stats.prefix”
Default: nebula Reloadable

The prefix for Graphite metrics that nebula will prepend: https://graphite.readthedocs.io/en/latest/feeding-carbon.html#step-1-plan-a-naming-hierarchy

stats.protocol

Section titled “stats.protocol”
Default: tcp Reloadable

Choose which protocol is used for passing stats to Graphite. The options are tcp, tcp4, and tcp6. UDP is not supported.

stats.host

Section titled “stats.host”
Required Reloadable

Address of the Graphite host to push stats updates to, as host:port. A hostname is accepted and resolved when the config loads.

Prometheus options

Section titled “Prometheus options”

Config options if stats.type is chosen to be prometheus

stats.listen

Section titled “stats.listen”
Required Reloadable

Interface for the Prometheus stats server to listen on. TCP address of 0.0.0.0:8080 or :8080 or 192.168.14.12:1234, for instance.

stats.path

Section titled “stats.path”
Required Reloadable

Path to serve stats to, normally /metrics.

stats.namespace

Section titled “stats.namespace”
Reloadable

The prefix that nebula should add to stats to add context within Prometheus. It's recommended to set this to nebula by default. Must be in the shape: https://prometheus.io/docs/concepts/data_model/

stats.subsystem

Section titled “stats.subsystem”
Reloadable

Describe which sort of subsystem these stats fall into: https://prometheus.io/docs/practices/instrumentation/#subsystems. Must be in the shape: https://prometheus.io/docs/concepts/data_model/