pktvisor: an edge agent that turns packet captures, dnstap, sFlow and IPFIX into OpenTelemetry-style metrics

The problem pktvisor targets: summarizing high-volume network streams at the edge

The README frames pktvisor as an observability agent for "high volume, information dense network data streams" that extracts insights "directly from the edge." That phrasing describes a real constraint. A DNS resolver or a peering router produces far more traffic than most teams can afford to ship to a central collector, and full packet capture is rarely the answer. pktvisor instead taps a stream, analyzes it in process, and emits summaries. The project states it has origins in observability of critical internet infrastructure for DDoS protection and traffic engineering, which explains the emphasis on heavy hitters, cardinality and GeoIP/ASN rather than on payload inspection. The intended user is an operator who wants to know which clients, domains or ASNs dominate traffic on a specific host or interface, and who wants that answer on the node, in near real time, with the same numbers also flowing into Prometheus and Grafana. It is not aimed at application developers debugging a single request, and it is not a replacement for a full IDS or a packet broker.

Inputs, handlers and the API: how the agent is put together

The architecture splits into two module families. The input stream system, under src/inputs, taps data streams. The README lists packet capture, dnstap, sFlow and NetFlow/IPFIX as supported today, with envoy taps and eBPF named as planned. The stream analyzer system, under src/handlers, does application layer analysis and summarizes into counters, histograms and quantiles, timers and rates, heavy hitters and top N, set cardinality, and GeoIP/ASN. The README states that input and analyzer modules "may be dynamically loaded at runtime," and that the agent is controlled in real time via API and YAML policies. That control surface is the part worth understanding before adopting it: the running agent is not configured once at startup and left alone. Policies define what runs. The CLI (pktvisor-cli) talks to the agent over the built in REST API rather than reading a local file, so the same API that serves the terminal UI is the integration point for anything else you want to build. Metric output exists in two directions at once: on-node for immediate inspection, and centrally collected into Prometheus and Grafana. The repository also includes a centralized_collection directory, and the README points to a Current Metrics wiki page and a sample output page rather than enumerating fields inline. That is where you should look to decide whether the DNS and network handlers expose the fields you need.

Getting it running: container, AppImage or standalone static binaries

The README gives three installation paths. The Docker image is the shortest: docker pull netboxlabs/pktvisor, then docker run --net=host -d netboxlabs/pktvisor pktvisord eth0. The final two arguments select the agent and the capture interface. Host networking is required to see traffic outside the container, and the README notes that currently only Linux supports host networking. The CLI runs separately: docker run -it --rm --net=host netboxlabs/pktvisor pktvisor-cli. If the container exits, the README points you at docker logs, which is the first place to look when the agent fails to bind an interface. The second path is the AppImage for x86_64 Linux: curl -L http://pktvisor.com/download -o pktvisor-x86_64.AppImage, chmod +x, then ./pktvisor-x86_64.AppImage pktvisord -h to check options. Running the agent on eth0 is ./pktvisor-x86_64.AppImage pktvisord eth0. The README suggests -d to daemonize and either --log-file or --syslog to record logs when using the AppImage, which matters because a daemonized agent with no log destination is hard to debug. The third path is individual static binaries for pktvisord, pktvisor-cli and pktvisor-reader, each downloaded from pktvisor.com/download and made executable. All three tools ship in every package: the collector agent, the CLI, and the pcap and dnstap file analyzer. The first argument to the AppImage or container selects which one runs.

Platform limits and the cost of a fast-moving develop branch

The packaging story is narrower than the feature list suggests. The README offers an AppImage and standalone static binaries for x86_64 Linux, and states that support for additional operating systems, CPU architectures and packaging systems is in progress. There is no Windows or ARM build described in the material, and the Docker host networking path is Linux only. If your edge fleet is not x86_64 Linux, you are in build-it-yourself territory, and the README's Build section is the entry point. The release history is the second constraint. The listed releases are v4.5.0 (January 2024), v4.4.0 (June 2023), and a toolchains release in September 2025. The default branch is develop, and the Docker instructions explicitly offer netboxlabs/pktvisor:latest-develop as the way to get the latest development version. That combination means the tagged stable line and the development line can diverge. Pinning to a tag is the conservative choice; following develop gets you fixes and new handlers but no compatibility promise that this material documents. The README does not describe an upgrade procedure, a migration path between versions, or a stability policy for the policy YAML and API. Treat the policy schema as something to test against your pinned version rather than as a stable contract.

Where pktvisor is the wrong tool

Three cases stand out. First, if you need payload-level inspection or protocol decoding outside the shipped handlers, pktvisor is the wrong layer. Its analyzers summarize; they do not reconstruct sessions or inspect application payloads. A team investigating a specific malformed DNS response or a TLS handshake failure will want a packet capture tool that writes pcap and a decoder, not a streaming summarizer. Second, if your infrastructure cannot give the agent a tap, nothing else matters. The supported inputs are packet capture, dnstap, sFlow and NetFlow/IPFIX. A cloud environment where you have no interface to capture on and no flow export configured gives pktvisor nothing to read. The README notes envoy taps and eBPF as future additions, not current ones, so do not plan around them. Third, if you want a single centrally managed platform with a long-term schema guarantee, the API-and-policy model here is more hands-on than that. You are running an agent per node, defining policies per agent, and collecting metrics yourself. The project supplies the agent and the collection examples; it does not supply a managed control plane in the material shown. Teams without an existing Prometheus and Grafana setup should count that as part of the adoption cost.

Alternatives and the actual difference in approach

The natural comparison is with flow-based collectors such as a standard NetFlow or IPFIX collector, and with full capture stacks built on libpcap plus a decoder. A flow collector receives pre-aggregated records from routers and switches. It scales because the aggregation already happened in the network device, but you only see what the exporter chose to export, and the export interval sets your resolution. pktvisor inverts that: it taps the stream itself, including raw packet capture on an interface, and does the aggregation in the agent. You get finer resolution and control over what is computed, and you pay for it with a process running on the host with access to the interface. Against a libpcap-plus-decoder stack, the difference is what leaves the box. A capture stack writes packets or streams them to a central analyzer; pktvisor writes summaries. For DNS specifically, the dnstap input is the interesting middle path: you get structured DNS events from a resolver without capturing packets, and the DNS handler summarizes them. Which of these fits depends on whether your bottleneck is collection bandwidth, storage, or the need to inspect individual messages. pktvisor addresses the first two and deliberately not the third.

Licence and what to verify before you deploy

pktvisor is licensed under MPL-2.0, a file-level copyleft licence. In practical terms for most users, that means you can run it and combine it with other software, but modifications to files covered by the licence carry obligations when distributed. This is not legal advice; if you plan to modify pktvisor and redistribute it, or to embed it in a product, have counsel review the MPL-2.0 terms and any notices in the repository. The maintenance question is more concrete than the licence one. The agent is C++ with dynamically loaded modules, so a build from source pulls in a toolchain and the dependencies of the input and handler modules you enable. The project publishes static binaries and an AppImage precisely so that most users avoid that build. Choose the package that matches your update process: a pinned Docker tag if you deploy containers, the AppImage if you want a single file per host, or standalone binaries if you want the smallest artifacts. Before rolling out, confirm three things against your own environment. That your chosen tap exists and is reachable from the agent's network namespace. That the handlers for your protocol produce the fields you intend to alert on, by checking the Current Metrics wiki page and the sample output page. And that your pinned version's policy YAML and API behave as your automation expects, since the README documents neither a schema version nor an upgrade path.

Editorial conclusion

Adopt pktvisor if you run DNS or network edge infrastructure and want streaming summaries (heavy hitters, quantiles, cardinality, GeoIP/ASN) close to the traffic without shipping full packet captures to a central store. Do not adopt it if you need deep packet inspection, protocol decoding beyond what the shipped handlers cover, or Windows and ARM support today. Before committing, verify two things yourself: which input tap your environment actually provides (packet capture, dnstap, sFlow or NetFlow/IPFIX) and whether the shipped analyzer handlers cover your protocol. Then run the AppImage with pktvisord -h against a test interface and confirm the metric output matches the fields listed on the Current Metrics wiki page.

Official sources

1. License: MPL-2.0
2. netboxlabs/pktvisor on GitHub
3. Project website
4. README
5. Releases