# pktvisor: a C++ packet and flow agent that turns taps into OpenTelemetry and Prometheus metrics

> pktvisor taps packet capture, dnstap, sFlow and NetFlow/IPFIX, runs streaming analyzers over them, and exposes the results through a REST API, a CLI UI and a Prometheus endpoint. It is built for edge deployments where you want summaries, not full packet retention.

**netboxlabs/pktvisor** — pktvisor is a dynamic network observability agent that smartly analyzes network traffic and generates opentelemetry metrics

- Repository: https://github.com/netboxlabs/pktvisor
- Website: https://orb.community
- Stars: 525 · Forks: 33
- Language: C++
- License: MPL-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/netboxlabs-pktvisor

## What pktvisor solves, and who it is for

Most network monitoring tools make you choose between two bad options: keep every packet and pay for storage, or collect coarse interface counters and learn nothing about what the traffic actually was. pktvisor sits in between. The README describes it as an observability agent for analyzing high volume, information dense network data streams and extracting actionable insights directly from the edge. The output is not raw packets. It is counters, histograms and quantiles, timers and rates, heavy hitters and top N, set cardinality, and GeoIP or ASN enrichment.

The intended audience is visible in the project's own history. The README says pktvisor has its origins in observability of critical internet infrastructure in support of DDoS protection, traffic engineering, and ongoing operations. That is a specific crowd: network operators and SREs who run DNS resolvers, authoritative servers or edge routers and need to know, in near real time, which client is flooding them, which query names dominate, and how the traffic mix shifts. It is less obviously a fit for application developers who want request traces; pktvisor works at the packet and flow layer, not inside your service.

## Taps in, stream analyzers out: the pktvisor data path

The architecture has two halves, and the repository layout reflects them. The input stream system lives under src/inputs and is described as designed to tap into data streams. It currently supports packet capture, dnstap, sFlow and NetFlow/IPFIX, with envoy taps and eBPF named as future additions. The stream analyzer system lives under src/handlers and performs application layer analysis on top of those taps.

What makes this more than a fixed pipeline is the control surface. The README states that pktvisor is modular and dynamically controlled in real time via API and YAML policies, and that input and analyzer modules may be dynamically loaded at runtime. So the agent process is not reconfigured by editing a file and restarting; policies are applied through the API. That matters at the edge, where you may want to start a DNS-focused policy on one interface and a NetFlow policy on another without dropping the running capture.

Output goes two directions at once. On-node, the command line UI gives what the README calls localized, hyper real-time views. Centrally, metrics are collected into Prometheus and Grafana. The repository also contains a centralized_collection directory and a k8s directory, so the project anticipates a fleet of agents reporting upward rather than a single host.

## Installing pktvisor with Docker and running a first capture

The README calls Docker one of the easiest ways to get started. The published image contains three tools: the collector agent pktvisord, the command line UI pktvisor-cli, and the pcap and dnstap file analyzer pktvisor-reader. You choose which one runs by passing it as the first argument.

Pull the image first. The README notes that netboxlabs/pktvisor:latest-develop is available if you want the development version instead of the default tag.

```bash
docker pull netboxlabs/pktvisor
```

Then start the agent. The final two arguments select pktvisord and the eth0 interface for capture; the README says you may substitute eth0 for any known interface on your device. Host networking is required for the container to observe traffic outside itself, and the README states that currently only Linux supports host networking.

```bash
docker run --net=host -d netboxlabs/pktvisor pktvisord eth0
```

If the container does not stay running, the README points you at docker logs for the reason. Once it is up, the CLI connects to the local agent over the built-in REST API and renders results in the foreground until you press Ctrl-C.

```bash
docker run -it --rm --net=host netboxlabs/pktvisor pktvisor-cli
```

The alternative install path is the AppImage, an all-in-one x86_64 Linux binary available from the Releases page. The README says it is designed to work on all modern Linux distributions and does not require installation or any other dependencies. The download endpoint given is pktvisor.com/download, and the first argument again picks the tool, so the same binary can run the agent or the CLI.

```shell
curl -L http://pktvisor.com/download -o pktvisor-x86_64.AppImage
chmod +x pktvisor-x86_64.AppImage
./pktvisor-x86_64.AppImage pktvisord eth0
```

When running the AppImage agent, the README suggests the -d argument to daemonize and either --log-file or --syslog to record logs. Separate standalone static binaries for pktvisord, pktvisor-cli and pktvisor-reader are also published, and the README describes them as the smallest, most compact versions.

## Where pktvisor is the wrong tool

The streaming algorithm approach is the point and also the boundary. pktvisor summarizes. If your problem is "reconstruct this TCP session byte for byte" or "show me the payload of the request that triggered this alert," a summarizer is the wrong layer. You want full packet capture with retention, and pktvisor is not that.

Platform coverage is the second constraint, and it is narrower than the README's tone suggests. The Docker quick start depends on host networking, which the README explicitly limits to Linux. The AppImage and the standalone static binaries are described as x86_64. The README acknowledges this directly: it says the project is working on support for additional operating systems, CPU architectures and packaging systems, and points readers who do not see their binary at the Build section. On macOS or Windows, the documented path is to build your own, and the build system is Conan plus CMake, which is a real commitment.

The third boundary is what the analyzers actually know. The README lists Network and DNS stream processors as the illustrated examples, and links to a wiki page for current metrics. If your protocol is not covered by an existing handler, the packet is still tapped but the application layer insight you wanted is not there. The README's promise of future envoy taps and eBPF support is a statement of intent, not a capability you can plan around today.

## How pktvisor differs from tcpdump plus a metrics pipeline

The obvious alternative is the familiar combination of tcpdump or a flow exporter, a text log, and something that parses it later. The difference is where the summarization happens. With tcpdump you get packets and you own the parsing, the aggregation and the cardinality control; the classic failure there is that a top-N query over a high-cardinality field either blows up memory or gets computed after the fact.

pktvisor moves that work into the agent and uses streaming algorithms for it. The README lists heavy hitters, frequent items, top N and set cardinality as first-class outputs, which is exactly the set of things that are awkward to compute correctly over a firehose. It also means the agent is doing bounded work per packet rather than buffering.

The other difference is the control plane. A tcpdump invocation is a command line. pktvisor is API-driven with YAML policies, and modules can be loaded at runtime, so a fleet can be steered centrally. The trade-off is that you give up ad hoc inspection: you cannot ask pktvisor a question its loaded analyzers do not answer.

## Maintenance, releases and licence

The repository is not archived, and the last push was on 2026-08-26. The release history is uneven, and that is worth reading carefully before you commit. The most recent release entry is tagged toolchains and dated 2025-09-18. Before that, v4.5.0 is dated 2024-01-05 and v4.4.0 is dated 2023-06-07. So the tagged version stream shows a long gap between v4.4.0 and v4.5.0, and the latest tag is not a versioned agent release at all. Development activity on the default branch, develop, is more recent than any of those tags, which is consistent with the README's mention of a latest-develop image.

Practically, that means you should decide whether you are tracking develop or a tagged release, and the README does not document a rollback procedure for either. The upgrade cost is mostly in policy compatibility: because inputs and analyzers are loaded dynamically and driven by YAML policies, a change in a handler's metric set can change what your dashboards receive without the agent failing to start.

pktvisor is licensed under MPL-2.0, a file-level copyleft licence. Modifications to files covered by the licence carry obligations when distributed; using the agent as a separate process and consuming its metrics does not. That is a general description of the licence's structure, not legal advice, and the LICENSE file in the repository is the authority.

## Conclusion

Adopt pktvisor when you need summarized traffic and DNS visibility on a host you control and you already run Prometheus or Grafana. Skip it if you need full packet retention for forensic replay, or if you cannot give the container host networking on Linux, since that is how the documented Docker path observes traffic outside the container. Before rolling it out, confirm that your interface name works with the pktvisord argument, that your preferred install path exists for your architecture, and that the analyzer you want is listed in the current metrics wiki page.

## FAQ

### Which tool is used for network packet analysis in pktvisor?

The pktvisor agent runs as pktvisord, which performs the packet capture and stream analysis. The same distribution also ships pktvisor-cli for the on-node command line UI and pktvisor-reader for analyzing pcap and dnstap files.

### Does pktvisor need host networking in Docker?

Yes. The README states that the Docker step requires host networking to observe traffic outside the container, and that currently only Linux supports host networking.

### Which input types can pktvisor tap into?

The input stream system currently supports packet capture, dnstap, sFlow and NetFlow/IPFIX. The README names envoy taps and eBPF as additions that are planned but not yet supported.

### Is pktvisor a full packet capture tool?

No. It is designed to summarize streams into counters, histograms and quantiles, timers and rates, heavy hitters and top N, set cardinality, and GeoIP or ASN. It does not retain full packets for later replay.

## Sources

- [License: MPL-2.0](https://github.com/netboxlabs/pktvisor/blob/develop/LICENSE)
- [netboxlabs/pktvisor on GitHub](https://github.com/netboxlabs/pktvisor)
- [Project website](https://orb.community)
- [README](https://github.com/netboxlabs/pktvisor/blob/develop/README.md)
- [Releases](https://github.com/netboxlabs/pktvisor/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/netboxlabs-pktvisor