Skip to main content

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

The stats section is reloadable, except for stats.message_metrics and stats.lighthouse_metrics. A reload can switch the backend, turn stats on or off, change the listen or host address, and re-resolves the Graphite host's DNS name.

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​

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, and follow a new interval on reload.

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.

This setting is not reloadable.

stats.lighthouse_metrics​

Default: false

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

This setting is not reloadable.

Notable metrics​

Some recently added metrics worth watching:

MetricMeaning
udp.tx.droppedPackets queued for the UDP socket that the kernel did not accept
udp.gro.enabled, udp.gso.enabledLinux only. 1 when the UDP socket is using GRO or GSO, see listen.udp_offloads
lighthouse.query.droppedLighthouse queries dropped because handshakes.query_buffer was full
handshake_manager.rejected.blocklistedHandshakes refused because the peer's certificate is in pki.blocklist
messages.tx.exhaustedPackets 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​

Config options if stats.type is chosen to be graphite

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​

Default: tcp Reloadable

Choose which protocol is used for passing stats to Graphite. The options are tcp, tcp4, and tcp6. UDP is not supported. Each push to Graphite times out after 30 seconds.

stats.host​

Required Reloadable

IP address of the host that Graphite should push stats updates to.

Prometheus options​

Config options if stats.type is chosen to be prometheus

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​

Required Reloadable

Path to serve stats to, normally /metrics.

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​

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/