| 1 | <!--startmeta |
| 2 | custom_edit_url: "https://github.com/netdata/netdata/edit/master/docs/network-flows/visualization/dashboard-cards.md" |
| 3 | sidebar_label: "Plugin Health Charts" |
| 4 | learn_status: "Published" |
| 5 | learn_rel_path: "Network Flows/Visualization" |
| 6 | keywords: ['plugin health', 'metrics', 'operational charts', 'monitoring'] |
| 7 | endmeta--> |
| 8 | |
| 9 | <!-- markdownlint-disable-file --> |
| 10 | |
| 11 | # Plugin Health Charts |
| 12 | |
| 13 | The netflow plugin publishes its own operational charts under the `netdata.netflow.*` chart context. These appear on the standard Netdata charts page (alongside system metrics like CPU and memory), **not** inside the Network Flows view. They are how you monitor the plugin itself: is it receiving data, are templates flowing, is memory growing, is disk being written. |
| 14 | |
| 15 | This is also where you look first when something seems wrong — long before opening the Network Flows view. |
| 16 | |
| 17 | All charts update every 1 second. |
| 18 | |
| 19 | ## The charts |
| 20 | |
| 21 | | Chart | Type | What it shows | |
| 22 | |---|---|---| |
| 23 | | `netflow.input_packets` | line, packets/s | Datagrams: received, parsed, errored, per-protocol counts | |
| 24 | | `netflow.input_bytes` | line, bytes/s | UDP byte rate | |
| 25 | | `netflow.raw_journal_ops` | line, ops/s | Raw journal: writes, sync calls, errors | |
| 26 | | `netflow.raw_journal_bytes` | line, bytes/s | Raw journal logical bytes written | |
| 27 | | `netflow.materialized_tier_ops` | line, ops/s | Rollup tiers: rows produced per tier, flushes, errors | |
| 28 | | `netflow.materialized_tier_bytes` | stacked, bytes/s | Rollup tier byte rate, broken down by tier | |
| 29 | | `netflow.open_tiers` | stacked, rows | Rows currently open per tier | |
| 30 | | `netflow.journal_io_ops` | line, ops/s | Decoder-state persist operations and errors | |
| 31 | | `netflow.journal_io_bytes` | line, bytes/s | Decoder-state persist byte rate | |
| 32 | | `netflow.decoder_scopes` | line, scopes | Distinct (exporter, observation domain) scopes the decoder tracks | |
| 33 | | `netflow.memory_resident_bytes` | line, bytes | Process RSS, peak RSS, breakdown | |
| 34 | | `netflow.memory_resident_mapping_bytes` | stacked, bytes | RSS broken down by what's in it | |
| 35 | | `netflow.memory_allocator_bytes` | line, bytes | Allocator-internal stats | |
| 36 | | `netflow.memory_accounted_bytes` | stacked, bytes | RSS attributed to known components, plus `unaccounted` | |
| 37 | | `netflow.memory_tier_index_bytes` | stacked, bytes | Tier-index memory drilldown | |
| 38 | |
| 39 | ## Reading the most useful charts |
| 40 | |
| 41 | ### `netflow.input_packets` |
| 42 | |
| 43 | The single most important chart. Five families of dimensions: |
| 44 | |
| 45 | - **`udp_received`** — datagrams pulled off the socket. If this is zero, nothing is reaching the plugin (firewall, no exporter, wrong port). |
| 46 | - **`parse_attempts`, `parsed_packets`** — should track each other on a healthy collector. If `parse_attempts` is high but `parsed_packets` is low, datagrams are arriving but failing to decode. |
| 47 | - **`parse_errors`** — counts datagrams that failed parsing for any reason (truncated, malformed, unsupported version). |
| 48 | - **`template_errors`** — counts data records arriving before their template (v9 / IPFIX). Should be near zero in steady state. A sustained non-zero rate means the exporter is sending templates too rarely or your collector has lost template state. |
| 49 | - **`netflow_v5`, `netflow_v7`, `netflow_v9`, `ipfix`, `sflow`** — per-protocol successful counts. Useful to identify "which protocol is actually arriving". |
| 50 | |
| 51 | ### `netflow.decoder_scopes` |
| 52 | |
| 53 | Cardinality of decoder state. Reports how many distinct `(exporter, observation domain)` template caches the plugin currently holds. Watch for unbounded growth — an exporter that frequently rotates template IDs (rare but real) will inflate this without bound. |
| 54 | |
| 55 | ### `netflow.materialized_tier_*` |
| 56 | |
| 57 | Show the rollup pipeline working. `*_rows` should track ingest. `flushes` should tick steadily; if it stops, tiering is stalled. |
| 58 | |
| 59 | ### `netflow.memory_resident_bytes` and `netflow.memory_accounted_bytes` |
| 60 | |
| 61 | If RSS climbs over time: |
| 62 | |
| 63 | - Check `netflow.memory_accounted_bytes` to see where it's going. |
| 64 | - The `unaccounted` dimension is `RSS - sum(known components)`. **A growing `unaccounted` is your leak signal.** |
| 65 | - `tier_indexes` and `open_tiers` are normal sources of growth — they should track ingest rate. |
| 66 | - `geoip_asn` and `geoip_geo` are mmap'd MMDB files. Their size grows as the kernel pages the file in under read pressure. |
| 67 | |
| 68 | ### `netflow.memory_resident_mapping_bytes` |
| 69 | |
| 70 | This one breaks RSS down by what's mapped. Useful when you want to attribute "this process is using 800 MB" — heap, journals (per tier), MMDB files, anonymous mappings, etc. |
| 71 | |
| 72 | ## What's NOT in these charts |
| 73 | |
| 74 | These charts do not include: |
| 75 | |
| 76 | - **Per-exporter ingest counter.** No per-source rate dimension. Decoder-scope cardinality tells you how many sources, not how busy each one is. |
| 77 | - **UDP socket drops.** Kernel-level drops (full receive buffer, NIC drops) are not surfaced. Use OS-level signals: `sudo ss -uamn sport = :2055` for per-socket drops, or `grep ^Udp: /proc/net/snmp` for the system-wide `RcvbufErrors` counter. |
| 78 | - **Template cache hit ratio.** `template_errors` counts misses; there's no corresponding "hits" counter to form a ratio. |
| 79 | - **GeoIP staleness signal.** No "MMDB last loaded" timestamp or version. The mapping memory dimensions tell you if a database is loaded, not how old it is. |
| 80 | - **Per-tier query latency.** These charts cover ingest and storage; query-side performance isn't observable. |
| 81 | - **BioRIS counters.** BioRIS routing-state details are not published as chart dimensions. |
| 82 | |
| 83 | ## How to use these charts for diagnosis |
| 84 | |
| 85 | | Symptom | Look at | What it means | |
| 86 | |---|---|---| |
| 87 | | Network Flows view is empty | `netflow.input_packets` `udp_received` | Zero = no datagrams arriving (firewall? wrong port?). Non-zero with `parsed_packets` zero = wrong protocol or all datagrams malformed. | |
| 88 | | Sudden drop in flows | per-protocol dimensions | Identifies which protocol stopped (helps narrow whether it's a router, a router class, or all routers). | |
| 89 | | Templates failing | `template_errors` rising | Exporter not sending templates often enough; collector lost cache; cache mismatch after firmware update. | |
| 90 | | Cache growing without bound | `decoder_scopes` rising over hours | Exporter churn or unstable template IDs. Investigate per-router behaviour. | |
| 91 | | Memory pressure | `netflow.memory_resident_bytes`, `netflow.memory_accounted_bytes` | If `rss` climbs and `unaccounted` is the dimension growing → unattributed allocation, possibly a leak. If `tier_indexes` or `open_tiers` climbs → ingest backpressure, flushing stalled. | |
| 92 | | Disk write stalls | `netflow.raw_journal_ops` `write_errors`, `sync_errors` | Disk full, permission denied, fs error. | |
| 93 | | Decoder state not persisting | `netflow.journal_io_ops` | `decoder_state_persist_calls` should tick periodically. `*_errors` should be 0. | |
| 94 | |
| 95 | ## Where these are NOT shown |
| 96 | |
| 97 | These charts are **not** in the Network Flows view. Look for them on the standard Netdata charts page, in the family `netflow`. The Network Flows view itself shows traffic data, not plugin health. |
| 98 | |
| 99 | ## What's next |
| 100 | |
| 101 | - [Troubleshooting](/docs/network-flows/troubleshooting.md) — Concrete diagnostic workflows. |
| 102 | - [Validation and Data Quality](/docs/network-flows/validation.md) — Cross-checking plugin counters against SNMP. |
| 103 | - [Configuration](/docs/network-flows/configuration.md) — Tuning that affects what these charts show. |