Local listening processes discovery

Kind: net_listeners

Overview

Netdata can automatically discover services running on the local host by inspecting the kernel’s listening sockets. This is the discoverer that powers Netdata’s “zero-config” experience for most database, cache, web-server, and exporter monitoring — if the service is listening on a known port and runs as a recognisable process, Netdata picks it up and starts collecting metrics without you writing any configuration.

This page covers net_listeners-specific setup. For the broader Service Discovery model and the shared template-helper reference, see Service Discovery.

How it works

Each discovery cycle, the discoverer:

1. Reads the kernel’s TCP/UDP listening-socket table via the bundled local-listeners helper, which reads Linux procfs socket and process data.
2. Builds one target per (protocol, IP, port, process) tuple, exposing .Protocol, .IPAddress, .Port, .Comm (process basename), .Cmdline (full command line), and .Address (the convenience IPAddress:Port).
3. Caches each target for 10 minutes so a brief disappearance (process restart) does not churn collector jobs.
4. Runs the services: rules against each target. The stock conf carries ~100 curated rules covering the bulk of go.d modules (databases, web servers, caches, message queues, exporters).
5. Reconciles disappeared listeners — when a process stops listening, its target is removed and the corresponding collector job stops on the next reconcile.

Limitations

• Only local listeners are visible. Discovering services on other hosts requires another discoverer (http, snmp, k8s, or a custom one).
• The discoverer needs to read kernel socket information. On Linux this works for processes owned by other users only when Netdata can read the appropriate /proc/<pid>/net files; the Netdata installer configures this via the local-listeners setuid helper.
• The bundled local-listeners helper is currently built for Linux. A missing or non-executable helper makes both normal discovery and the DynCfg operational test fail.
• Containerised services in host networking appear as listeners and are picked up here, not by the Docker discoverer. Services in private container networks must be discovered by the Docker discoverer instead.
• The discoverer does not introspect process runtime — anything beyond port/comm/cmdline (e.g. config-file path, version, runtime URL prefix) must be inferred via service rules or known by convention.

Setup

You can configure the net_listeners discoverer in two ways:

Prerequisites

Discovery is enabled by default

The stock conf at /etc/netdata/go.d/sd/net_listeners.conf ships with disabled: no and a curated set of rules. To turn discovery off, set disabled: yes at the top of the file.

Trust the curated stock rules

The stock rule set covers most commonly-monitored services out of the box (Apache, Nginx, MySQL, PostgreSQL, Redis, RabbitMQ, MongoDB, Elasticsearch, etc.). Most users do not need to author their own rules — start by enabling the relevant collector module and let the stock rules find local instances.

Configuration

Options

The configuration file has two top-level blocks: discoverer: (the options below) and services: (rules that turn discovered listeners into collector jobs — see Service Rules).

After editing the file, restart the Netdata Agent to load the updated discovery pipeline.

via UI

1. Open the Netdata Dynamic Configuration UI.
2. Go to Collectors -> go.d -> ServiceDiscovery -> net_listeners.
3. Add a new discovery pipeline and give it a name.
4. Fill in the discoverer-specific settings and the service rules.
5. Save the discovery pipeline.

via File

Define the discovery pipeline in /etc/netdata/go.d/sd/net_listeners.conf.

The file has two top-level blocks: discoverer: (the options above) and services: (rules that turn discovered targets into collector jobs — see Service Rules).

After editing the file, restart the Netdata Agent to load the updated discovery pipeline.

Examples

Default — keep stock rules

Most users should not need to touch this file. The stock conf carries ~100 curated rules. Set disabled: yes if you want to disable local-listener discovery entirely.

disabled: no
discoverer:
  net_listeners: { }

# services rules ship in the stock conf — the snippet below is illustrative only
services:
  - id: redis
    match: '{{ or (eq .Port "6379") (eq .Comm "redis-server") }}'
    config_template: |
      name: local
      address: redis://@{{.Address}}      

Faster scan interval

Bump the scan rate to once per minute. Useful for very dynamic environments where services come and go often (e.g. ephemeral test runners).

disabled: no
discoverer:
  net_listeners:
    interval: 1m
services: [ ]

Troubleshooting

A locally-running service is not picked up

Check, in order:

• Is the service actually listening (ss -tlnp | grep <name>)?
• Does the stock conf have a rule for it? See /etc/netdata/go.d/sd/net_listeners.conf.
• Is the service on a non-standard port? Stock rules typically gate on the canonical port. Add a rule keyed on .Comm or .Cmdline for non-default ports.
• Is the process name truncated past 15 chars? .Comm is kernel-truncated; use .Cmdline instead.

Wrong module picked

The stock exporter catch-all rule (last in the file) is greedy by design — anything on a known Prometheus port gets the prometheus module. Add a more specific rule above it if you want a different module to win.

Generated jobs fail to start

The discoverer creates jobs but does not run them. Common causes: the rendered template assumes credentials the local service rejects (e.g. RabbitMQ default guest:guest); a rule renders the wrong port or protocol; or the service has TLS but the template uses HTTP.