NetFlow

Plugin: netflow-plugin Module: netflow

Overview

Collect network flow records from NetFlow v5, v7, and v9 exporters such as routers, switches, and firewalls. Each record exposes source and destination IP, ports, protocol, bytes, packets, ToS, TCP flags, and ingress/egress interface indices. Enrichment adds GeoIP country/city/ASN, static metadata, and classifier tags.

Cisco ASA NSEL over NetFlow v9 is recognized automatically. Event-5 interval updates become directional traffic rows; create, teardown, deny, malformed, and counterless events remain diagnostics and do not enter the flow database.

For full documentation including vendor configuration examples, sampling caveats, template handling and verification steps, see the Network Flows Overview.

The plugin listens on configurable UDP listener sockets for NetFlow datagrams. NetFlow v5 and v7 records are decoded directly. NetFlow v9 records are decoded using dynamic templates cached from the exporter and persisted across restarts. Validated Cisco ASA NSEL templates automatically activate event-aware directional decoding. Decoded records are enriched in-memory and appended to disk-backed journal tiers (raw, 1-minute, 5-minute, 1-hour rollups).

This integration is supported on all platforms.

This integration runs as a single instance per Netdata Agent.

Default Behavior

Auto-Detection

The stock configuration enables the plugin and listens on the configured UDP ports.

Limits

Operational limits are driven by sustained flow records/s, exporter batching, cardinality, retention, storage speed, and enrichment. On modern hardware with fast storage, plan around 50k-100k sustained flow records/s per well-provisioned agent for the full raw + rollup pipeline, provided the underlying disks can sustain the required journal write activity; use distributed agents for larger deployments.

Performance Impact

Disabled until exporters send traffic. Once active, CPU and disk I/O scale with flow-record rate, template volume, and cardinality; size retention and storage from observed flow records/s.

Setup

Prerequisites

NetFlow-capable exporter

A router, switch, or firewall configured to export NetFlow v5, v7, or v9 datagrams to the Netdata agent’s UDP listener.

Configuration

Options

The plugin is configured via netflow.yaml in the Netdata configuration directory.

via File

The configuration file name for this integration is netflow.yaml.

You can edit the configuration file using the edit-config script from the Netdata config directory.

cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config netflow.yaml

Examples

Basic NetFlow v5/v9 collection

Use Netdata’s stock listener set for v5 and v9 records.

enabled: true
listener:
  listen:
    - "0.0.0.0:2055"
    - "0.0.0.0:6343"
protocols:
  v5: true
  v9: true

NetFlow v9 only with extended retention

Accept only v9 records, keep one day of raw data, and keep longer rollups.

enabled: true
listener:
  listen: "0.0.0.0:2055"
protocols:
  v5: false
  v7: false
  v9: true
journal:
  journal_dir: flows
  tiers:
    raw:      { size_of_journal_files: 50GB, duration_of_journal_files: 24h }
    minute_1: { size_of_journal_files: 10GB, duration_of_journal_files: 14d }
    minute_5: { size_of_journal_files: 10GB, duration_of_journal_files: 30d }
    hour_1:   { size_of_journal_files: 10GB, duration_of_journal_files: 365d }

Metrics

Metrics grouped by scope.

The scope defines the instance that the metric belongs to. An instance is uniquely identified by a set of labels.

Network flow data is stored as journal records, not as traditional metrics. Use the Network Flows view in the Netdata dashboard to query and visualize flow data. For the full list of fields and the per-protocol availability matrix, see the Field Reference. Cisco ASA NSEL event 5 emits initiator and nonzero responder directions as separate rows. Create, teardown, deny, malformed, and counterless events are excluded from traffic. The plugin also publishes the operational health metrics below. They describe collector input and processing; they are not the stored flow traffic queried by Network Flows. For visualisation guidance see Sankey and Table, Time-Series, and Maps and Globe.

Per global

These metrics describe the global Network Flows collector pipeline.

This scope has no labels.

Metrics:

Alerts

There are no alerts configured by default for this integration.

Verifying flow data is arriving and diagnosing failures

See Troubleshooting for the full diagnostic recipe – including UDP path checks, template-error analysis, Cisco ASA NSEL event handling, and the “looks like a bug but isn’t” section (doubling, mirroring, internal-IP geolocation). See also Validation and Data Quality and Anti-patterns.