{"id":23888348,"url":"https://github.com/netboxlabs/pktvisor","last_synced_at":"2025-05-15T16:07:20.685Z","repository":{"id":37056349,"uuid":"241899022","full_name":"netboxlabs/pktvisor","owner":"netboxlabs","description":"pktvisor is a dynamic network observability agent that smartly analyzes network traffic and generates opentelemetry metrics","archived":false,"fork":false,"pushed_at":"2025-04-25T23:11:01.000Z","size":16738,"stargazers_count":497,"open_issues_count":5,"forks_count":34,"subscribers_count":36,"default_branch":"develop","last_synced_at":"2025-04-26T00:19:27.797Z","etag":null,"topics":["agent","api-first","collector-agent","dnstap","grafana","monitoring","observability","packet-capture","pcap","prometheus","stream-processors"],"latest_commit_sha":null,"homepage":"https://orb.community","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/netboxlabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-02-20T14:03:08.000Z","updated_at":"2025-04-24T13:55:45.000Z","dependencies_parsed_at":"2024-01-05T19:34:07.596Z","dependency_job_id":"b77ce7be-571d-44c2-a6c2-6b7b5d4db201","html_url":"https://github.com/netboxlabs/pktvisor","commit_stats":{"total_commits":834,"total_committers":18,"mean_commits":"46.333333333333336","dds":0.552757793764988,"last_synced_commit":"6b532ae15507d7997522a9b5c5849480c3b9ccd3"},"previous_names":["ns1/pktvisor","netboxlabs/pktvisor","orb-community/pktvisor"],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netboxlabs%2Fpktvisor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netboxlabs%2Fpktvisor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netboxlabs%2Fpktvisor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/netboxlabs%2Fpktvisor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/netboxlabs","download_url":"https://codeload.github.com/netboxlabs/pktvisor/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374475,"owners_count":22060611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","api-first","collector-agent","dnstap","grafana","monitoring","observability","packet-capture","pcap","prometheus","stream-processors"],"created_at":"2025-01-04T08:10:32.772Z","updated_at":"2025-05-15T16:07:15.677Z","avatar_url":"https://github.com/netboxlabs.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![pktvisor](docs/images/pktvisor-header.png)\n\n[![Build status](https://github.com/netboxlabs/pktvisor/workflows/Build/badge.svg)](https://github.com/netboxlabs/pktvisor/actions)\n[![CodeQL](https://github.com/netboxlabs/pktvisor/workflows/CodeQL/badge.svg)](https://github.com/netboxlabs/pktvisor/security/code-scanning)\n[![CodeCov](https://codecov.io/gh/netboxlabs/pktvisor/branch/develop/graph/badge.svg)](https://app.codecov.io/gh/netboxlabs/pktvisor/tree/develop)\n\n\u003cp align=\"left\"\u003e\n  \u003cstrong\u003e\n    \u003ca href=\"#what-is-pktvisor\"\u003eIntroduction\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u0026bull;\u0026nbsp;\u0026nbsp;\n    \u003ca href=\"#get-started\"\u003eGet Started\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u0026bull;\u0026nbsp;\u0026nbsp;\n    \u003ca href=\"#docs\"\u003eDocs\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u0026bull;\u0026nbsp;\u0026nbsp;\n    \u003ca href=\"#build\"\u003eBuild\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u0026bull;\u0026nbsp;\u0026nbsp;\n    \u003ca href=\"#contribute\"\u003eContribute\u003c/a\u003e\u0026nbsp;\u0026nbsp;\u0026bull;\u0026nbsp;\u0026nbsp;    \n    \u003ca href=\"#contact-us\"\u003eContact Us\u003c/a\u003e\n  \u003c/strong\u003e\n\u003c/p\u003e\n\n## What is pktvisor?\n\n**pktvisor** (pronounced \"packet visor\") is an **observability agent** for analyzing high volume, information dense\nnetwork data streams and extracting actionable insights directly from the edge while integrating tightly with modern observability stacks.\n\nIt is resource efficient and built from the ground up to be modular and dynamically controlled in\nreal time via API and YAML policies. Input and analyzer modules may be dynamically loaded at runtime. Metric output can be used and visualized\nboth on-node via command line UI (for localized, hyper real-time actions)\nas well as centrally collected into industry standard observability stacks like Prometheus and Grafana..\n\nThe [input stream system](src/inputs) is designed to _tap into_ data streams. It currently supports [packet capture](https://en.wikipedia.org/wiki/Packet_analyzer),\n[dnstap](https://dnstap.info/), [sFlow](https://en.wikipedia.org/wiki/SFlow) and [Netflow](https://en.wikipedia.org/wiki/NetFlow)/[IPFIX](https://en.wikipedia.org/wiki/IP_Flow_Information_Export) and will soon support additional taps such as\n[envoy taps](https://www.envoyproxy.io/docs/envoy/latest/operations/traffic_tapping), and [eBPF](https://ebpf.io/).\n\nThe [stream analyzer system](src/handlers) includes full application layer analysis, and [efficiently](https://en.wikipedia.org/wiki/Streaming_algorithm) summarizes to:\n\n* Counters\n* Histograms and Quantiles\n* Timers and Rates\n* Heavy Hitters/Frequent Items/Top N\n* Set Cardinality\n* GeoIP/ASN\n\nPlease see the list of [current metrics](https://github.com/netboxlabs/pktvisor/wiki/Current-Metrics) or the [sample metric output](https://github.com/netboxlabs/pktvisor/wiki/Sample-pktvisor-Output-Data).\n\npktvisor has its origins in observability of critical internet infrastructure in support of DDoS protection, traffic\nengineering, and ongoing operations.\n\nThese screenshots display both the [command line](golang/) and [centralized views](centralized_collection/) of\nthe [Network](src/handlers/net) and [DNS](src/handlers/dns) stream processors, and the types of summary information provided:\n\n![Image of CLI UI](docs/images/pktvisor3-cli-ui-screenshot.png)\n![Image 1 of Grafana Dash](docs/images/pktvisor-grafana-screenshot1.png)\n![Image 2 of Grafana Dash](docs/images/pktvisor-grafana-screenshot2.png)\n\n## Get Started\n\n### Docker\n\nOne of the easiest ways to get started with pktvisor is to use\nthe [public docker image](https://hub.docker.com/r/netboxlabs/pktvisor). The image contains the collector\nagent (`pktvisord`), the command line UI (`pktvisor-cli`) and the pcap and dnstap file analyzer (`pktvisor-reader`). When running\nthe container, you specify which tool to run.\n\n1. *Pull the container*\n\n```\ndocker pull netboxlabs/pktvisor\n``` \n\nor use `netboxlabs/pktvisor:latest-develop` to get the latest development version.\n\n2. *Start the collector agent*\n\nThis will start in the background and stay running. Note that the final two arguments select `pktvisord` agent and\nthe `eth0` ethernet interface for packet capture. You may substitute `eth0` for any known interface on your device.\n_Note that this step requires docker host networking_ to observe traffic outside the container, and\nthat [currently only Linux supports host networking](https://docs.docker.com/network/host/):\n\n```\ndocker run --net=host -d netboxlabs/pktvisor pktvisord eth0\n```\n\nIf the container does not stay running, check the `docker logs` output.\n\n3. *Run the command line UI*\n\nAfter the agent is running, you can observe results locally with the included command line UI. This command will run the\nUI (`pktvisor-cli`) in the foreground, and exit when Ctrl-C is pressed. It connects to the running agent locally using\nthe built in REST API.\n\n```\ndocker run -it --rm --net=host netboxlabs/pktvisor pktvisor-cli\n```\n\n### Linux Static Binary (AppImage, x86_64)\n\nYou may also use the Linux all-in-one binary, built with [AppImage](https://appimage.org/), which is available for\ndownload [on the Releases page](https://github.com/netboxlabs/pktvisor/releases). It is designed to work on all modern\nLinux distributions and does not require installation or any other dependencies.\n\n```shell\ncurl -L http://pktvisor.com/download -o pktvisor-x86_64.AppImage\nchmod +x pktvisor-x86_64.AppImage\n./pktvisor-x86_64.AppImage pktvisord -h\n```\n\nFor example, to run the agent on ethernet interface `eth0`:\n\n```\n./pktvisor-x86_64.AppImage pktvisord eth0\n```\n\nThe AppImage contains the collector agent (`pktvisord`), the command line UI (`pktvisor-cli`) and the pcap and dnstap file\nanalyzer (`pktvisor-reader`). You can specify which tool to run by passing it as the first argument:\n\nFor example, to visualize the running agent started above with the pktvisor command line UI:\n\n```shell\n./pktvisor-x86_64.AppImage pktvisor-cli\n```\n\nNote that when running the AppImage version of the agent, you may want to use the `-d` argument to daemonize (run in the\nbackground), and either the `--log-file` or `--syslog` argument to record logs.\n\nAlso see [Advanced Agent Example](#advanced-agent-example).\n\n### Linux Static Binaries (Stand Alone, x86_64)\n\nFinally, pktvisor also provides statically linked, dependency free Linux binaries for each individual pktvisor tool (pktvisord, pktvisor-cli and pktvisor-reader). These are the smallest, most compact versions of the binaries.\n\npktvisord:\n```shell\ncurl -L http://pktvisor.com/download/pktvisord -o pktvisord-x86_64\nchmod +x pktvisord-x86_64\n./pktvisord-x86_64 -h\n```\n\npktvisor-cli:\n```shell\ncurl -L http://pktvisor.com/download/cli -o pktvisor-cli-x86_64\nchmod +x pktvisor-cli-x86_64\n./pktvisor-cli-x86_64 -h\n```\n\npktvisor-reader:\n```shell\ncurl -L http://pktvisor.com/download/reader -o pktvisor-reader-x86_64\nchmod +x pktvisor-reader-x86_64\n./pktvisor-reader-x86_64 -h\n```\n\n### Other Platforms\n\nWe are working on support for additional operating systems, CPU architectures and packaging systems. If you do not see your binary available, please see the [Build](#build) section below to build your own.\n\nIf you have a preferred installation method that you would like to see support\nfor, [please create an issue](https://github.com/ns1/pktvisor/issues/new).\n\n### Execute Pktvisord binary without root\nPktvisord uses libpcap to capture PCAP from the desired interface. To do so, it needs system network capture permissions.\nYou are able to authorize those specific requirements only once and then be able to run the binary without `sudo`.\n```shell\nsudo setcap cap_net_raw,cap_net_admin=eip /\u003cfull_path\u003e/pktvisord-x86_64\n```\n\n## Docs\n\n### Agent Usage\n\nCurrent command line options are described with:\n\n```\ndocker run --rm netboxlabs/pktvisor pktvisord --help\n```\n\nor\n\n```\n./pktvisor-x86_64.AppImage pktvisord --help\n```\n\n```\n\n    Usage:\n      pktvisord [options] [IFACE]\n      pktvisord (-h | --help)\n      pktvisord --version\n\n    pktvisord summarizes data streams and exposes a REST API control plane for configuration and metrics.\n\n    pktvisord operation is configured via Taps and Collection Policies. Taps abstract the process of \"tapping into\"\n    input streams with templated configuration while Policies use Taps to instantiate and configure Input and Stream\n    Handlers to analyze and summarize stream data, which is then made available for collection via REST API.\n\n    Taps and Collection Policies may be created by passing the appropriate YAML configuration file to\n    --config, and/or by enabling the admin REST API with --admin-api and using the appropriate endpoints.\n\n    Alternatively, for simple use cases you may specify IFACE, which is either a network interface, an\n    IP address (4 or 6), or \"auto\". If this is specified, \"default\" Tap and Collection Policies will be created with\n    a \"pcap\" input stream on the specified interfaced, along with the built in \"net\", \"dns\", and \"pcap\"\n    Stream Handler modules attached. If \"auto\" is specified, the most used ethernet interface will be chosen.\n    Note that this feature may be deprecated in the future.\n\n    For more documentation, see https://pktvisor.dev\n\n    Base Options:\n      -d                                    Daemonize; fork and continue running in the background [default: false]\n      -h --help                             Show this screen\n      -v                                    Verbose log output\n      --no-track                            Don't send lightweight, anonymous usage metrics\n      --version                             Show version\n    Web Server Options:\n      -l HOST                               Run web server on the given host or IP (default: localhost)\n      -p PORT                               Run web server on the given port (default: 10853)\n      --tls                                 Enable TLS on the web server\n      --tls-cert FILE                       Use given TLS cert. Required if --tls is enabled.\n      --tls-key FILE                        Use given TLS private key. Required if --tls is enabled.\n      --admin-api                           Enable admin REST API giving complete control plane functionality [default: false]\n                                            When not specified, the exposed API is read-only access to module status and metrics.\n                                            When specified, write access is enabled for all modules.\n    Geo Options:\n      --geo-city FILE                       GeoLite2 City database to use for IP to Geo mapping\n      --geo-asn FILE                        GeoLite2 ASN database to use for IP to ASN mapping\n      --geo-cache-size N                    GeoLite2 LRU cache size, 0 to disable. (default: 10000)\n      --default-geo-city FILE               Default GeoLite2 City database to be loaded if no other is specified\n      --default-geo-asn FILE                Default GeoLite2 ASN database to be loaded if no other is specified\n    Configuration:\n      --config FILE                         Use specified YAML configuration to configure options, Taps, and Collection Policies\n                                            Please see https://pktvisor.dev for more information\n    Crashpad:\n      --cp-disable                          Disable crashpad collector\n      --cp-token TOKEN                      Crashpad token for remote crash reporting\n      --cp-url URL                          Crashpad server url\n      --cp-custom USERDEF                   Crashpad optional user defined field\n      --cp-path PATH                        Crashpad handler binary\n    Modules:\n      --module-list                         List all modules which have been loaded (builtin and dynamic).\n      --module-dir DIR                      Set module load path. All modules in this directory will be loaded.\n    Logging Options:\n      --log-file FILE                       Log to the given output file name\n      --syslog                              Log to syslog\n    Prometheus Options:\n      --prometheus                          Ignored, Prometheus output always enabled (left for backwards compatibility)\n      --prom-instance ID                    Optionally set the 'instance' label to given ID\n    Metric Enrichment Options:\n      --iana-service-port-registry FILE     IANA Service Name and Transport Protocol Port Number Registry file in CSV format\n      --default-service-registry FILE       Default IANA Service Name Port Number Registry CSV file to be loaded if no other is specified\n    Handler Module Defaults:\n      --max-deep-sample N                   Never deep sample more than N% of streams (an int between 0 and 100) (default: 100)\n      --periods P                            Hold this many 60 second time periods of history in memory (default: 5)\n    pcap Input Module Options:              (applicable to default policy when IFACE is specified only)\n      -b BPF                                Filter packets using the given tcpdump compatible filter expression. Example: \"port 53\"\n      -H HOSTSPEC                           Specify subnets (comma separated) to consider HOST, in CIDR form. In live capture this\n                                            /may/ be detected automatically from capture device but /must/ be specified for pcaps.\n                                            Example: \"10.0.1.0/24,10.0.2.1/32,2001:db8::/64\"\n                                            Specifying this for live capture will append to any automatic detection.\n                                                          \n```\n\n### Using a Configuration File\n\npktvisord may be configured at startup by YAML configuration file with the `--config` option.\nThe configuration file can configure all options that are available on the command line,\nas well as defining [Policies](RFCs/2021-04-16-76-collection-policies.md) and [Taps](RFCs/2021-04-16-75-taps.md). All sections are optional.\n\nNote that Policies and Taps may also be maintained in real-time via [REST API](#rest-api).\n\n```yaml\nversion: \"1.0\"\n\nvisor:\n  # optionally define global configuration (see command line options)\n  config:\n    verbose: true\n  # optionally define taps\n  taps:\n    default_pcap:\n      input_type: pcap\n      config:\n        iface: eth0\n      filter:\n        bpf: \"port 53\"          \n    unix_dnstap:\n      input_type: dnstap\n      config:\n        socket: \"/tmp/dnstap.sock\"\n    tcp_dnstap:\n      input_type: dnstap\n      config:\n        tcp: \"127.0.0.1:53053\"\n  # optionally define policies\n  policies:\n    mysocket:\n      kind: collection\n      input:\n        tap: unix_dnstap\n        input_type: dnstap\n      handlers:\n        modules:\n          default_net:\n            type: net\n          default_dns:\n            type: dns\n            config:\n              only_qname_suffix:\n                - \".google.com\"\n                - \".netboxlabs.com\"\n    mytcp:\n      kind: collection\n      input:\n        tap: tcp_dnstap\n        input_type: dnstap\n      handlers:\n        modules:\n          default_net:\n            type: net\n          default_dns:\n            type: dns\n```\n\nIf running in a Docker container, you must mount the configuration file into the container. For example, if the configuration file\nis on the host at `/local/pktvisor/agent.yaml`, you can mount it into the container and use it with this command:\n\n```shell\ndocker run -v /local/pktvisor:/usr/local/pktvisor/ --net=host netboxlabs/pktvisor pktvisord --config /usr/local/pktvisor/agent.yaml --admin-api\n```\n\n\n### Command Line UI Usage\n\nThe command line UI (`pktvisor-cli`) connects directly to a pktvisord agent to visualize the real time stream\nsummarization, which is by default a sliding 5 minute time window. It can also connect to an agent running on a remote\nhost.\n\n```\ndocker run --rm netboxlabs/pktvisor pktvisor-cli -h\n```\n\n```shell\n./pktvisor-x86_64.AppImage pktvisor-cli -h\n```\n\n```\n\nUsage:\n  pktvisor-cli [-p PORT] [-H HOST]\n  pktvisor-cli -h\n  pktvisor-cli --version\n\nOptions:\n  -p PORT               Query pktvisord metrics webserver on the given port [default: 10853]\n  -H HOST               Query pktvisord metrics webserver on the given host [default: localhost]\n  -P POLICY             pktvisor policy to query [default: default]\n  --tls\t                Use TLS to communicate with pktvisord metrics webserver\n  --tls-noverify        Do not verify TLS certificate\n  -h                    Show this screen\n  --version             Show client version\n\n```\n\n### File Analysis (pcap and dnstap)\n\n`pktvisor-reader` is a tool that can statically analyze prerecorded packet capture and dnstap files.\n\npcap files can come from many sources, the most famous of which is [tcpdump](https://www.tcpdump.org/). Dnstap files\ncan be generated from most DNS server software that support dnstap logging, either directly or \nusing a tool such as [golang-dnstap](https://github.com/dnstap/golang-dnstap).\n\nBoth take many of the same options, and do all of the same analysis, as `pktvisord` for live capture. pcap files may include Flow capture data.\n\n```\ndocker run --rm netboxlabs/pktvisor pktvisor-reader --help\n```\n\n```shell\n./pktvisor-x86_64.AppImage pktvisor-reader --help\n```\n\n```\n\n    Usage:\n      pktvisor-reader [options] FILE\n      pktvisor-reader (-h | --help)\n      pktvisor-reader --version\n\n    Summarize a network (pcap, dnstap) file. The result will be written to stdout in JSON format, while console logs will be printed\n    to stderr.\n\n    Options:\n      -i INPUT              Input type (pcap|dnstap|sflow|netflow). If not set, default is pcap input\n      --max-deep-sample N   Never deep sample more than N% of streams (an int between 0 and 100) [default: 100]\n      --periods P           Hold this many 60 second time periods of history in memory. Use 1 to summarize all data. [default: 5]\n      -h --help             Show this screen\n      --version             Show version\n      -v                    Verbose log output\n      -b BPF                Filter packets using the given BPF string\n      --geo-city FILE       GeoLite2 City database to use for IP to Geo mapping (if enabled)\n      --geo-asn FILE        GeoLite2 ASN database to use for IP to ASN mapping (if enabled)\n      -H HOSTSPEC           Specify subnets (comma separated) to consider HOST, in CIDR form. In live capture this /may/ be detected automatically\n                            from capture device but /must/ be specified for pcaps. Example: \"10.0.1.0/24,10.0.2.1/32,2001:db8::/64\"\n                            Specifying this for live capture will append to any automatic detection.\n\n```\n\nYou can use the docker container by passing in a volume referencing the directory containing the pcap file. The standard\noutput will contain the JSON summarization output, which you can capture or pipe into other tools, for example:\n```\n\n$ docker run --rm -v /pktvisor/src/tests/fixtures:/pcaps netboxlabs/pktvisor pktvisor-reader /pcaps/dns_ipv4_udp.pcap | jq .\n\n[2021-03-11 18:45:04.572] [pktvisor] [info] Load input plugin: PcapInputModulePlugin dev.visor.module.input/1.0\n[2021-03-11 18:45:04.573] [pktvisor] [info] Load handler plugin: DnsHandler dev.visor.module.handler/1.0\n[2021-03-11 18:45:04.573] [pktvisor] [info] Load handler plugin: NetHandler dev.visor.module.handler/1.0\n...\nprocessed 140 packets\n{\n  \"5m\": {\n    \"dns\": {\n      \"cardinality\": {\n        \"qname\": 70\n      },\n      \"period\": {\n        \"length\": 6,\n        \"start_ts\": 1567706414\n      },\n      \"top_nxdomain\": [],\n      \"top_qname2\": [\n        {\n          \"estimate\": 140,\n          \"name\": \".test.com\"\n        }\n      ],\n...     \n```\n\nThe AppImage can access local files as any normal binary:\n\n```\n\n$ ./pktvisor-x86_64.AppImage pktvisor-reader /pcaps/dns_ipv4_udp.pcap | jq .\n\n[2021-03-11 18:45:04.572] [pktvisor] [info] Load input plugin: PcapInputModulePlugin dev.visor.module.input/1.0\n[2021-03-11 18:45:04.573] [pktvisor] [info] Load handler plugin: DnsHandler dev.visor.module.handler/1.0\n[2021-03-11 18:45:04.573] [pktvisor] [info] Load handler plugin: NetHandler dev.visor.module.handler/1.0\n...\nprocessed 140 packets\n{\n  \"5m\": {\n    \"dns\": {\n      \"cardinality\": {\n        \"qname\": 70\n      },\n      \"period\": {\n        \"length\": 6,\n        \"start_ts\": 1567706414\n      },\n      \"top_nxdomain\": [],\n      \"top_qname2\": [\n        {\n          \"estimate\": 140,\n          \"name\": \".test.com\"\n        }\n      ],\n...     \n```\n\n### Metrics Collection\n\n#### Metrics from the REST API\n\nThe metrics are available from the agent in JSON format via the [REST API](#rest-api).\n\nFor most use cases, you will want to collect the most recent full 1-minute bucket, once per minute:\n\n```\ncurl localhost:10853/api/v1/metrics/bucket/1\n```\n\nThis can be done with tools like [telegraf](https://docs.influxdata.com/telegraf/) and\nthe [standard HTTP plugin](https://github.com/influxdata/telegraf/blob/release-1.17/plugins/inputs/http/README.md).\nExample telegraf config snippet for the `default` policy:\n\n```\n\n[inputs]\n[[inputs.http]]\nurls = [ \"http://127.0.0.1:10853/api/v1/metrics/bucket/1\",]\ninterval = \"60s\"\ndata_format = \"json\"\njson_query = \"1m\"\njson_time_key = \"period_start_ts\"\njson_time_format = \"unix\"\njson_string_fields = [\n  \"dns_*\",\n  \"packets_*\",\n  \"dhcp_*\",\n  \"pcap_*\",\n]\n\n[inputs.http.tags]\nt = \"pktvisor\"\ninterval = \"60\"\n\n```\n\n#### Prometheus Metrics\n\n`pktvisord` has native Prometheus support. The `default` policy metrics are\navailable for collection at the standard `/metrics` endpoint, or use `/api/v1/policies/__all/metrics/prometheus` to collect metrics from all policies.\n\n```shell\n$ ./pktvisor-x86_64.AppImage pktvisord -d eth0\n$ curl localhost:10853/metrics\n# HELP dns_wire_packets_udp Total DNS wire packets received over UDP (ingress and egress)\n# TYPE dns_wire_packets_udp gauge\ndns_wire_packets_udp{instance=\"node\",policy=\"default\"} 28\n# HELP dns_rates_total Rate of all DNS wire packets (combined ingress and egress) per second\n# TYPE dns_rates_total summary\ndns_rates_total{instance=\"node\",policy=\"default\",quantile=\"0.5\"} 0\ndns_rates_total{instance=\"node\",policy=\"default\",quantile=\"0.9\"} 4\ndns_rates_total{instance=\"node\",policy=\"default\",quantile=\"0.95\"} 4\n...\n```\n\nYou can set the `instance` label by passing `--prom-instance ID`\n\nIf you are interested in centralized collection\nusing [remote write](https://prometheus.io/docs/operating/integrations/#remote-endpoints-and-storage), including to\ncloud providers, there is a [docker image available](https://hub.docker.com/r/netboxlabs/pktvisor-prom-write) to make this\neasy. See [centralized_collection/prometheus](centralized_collection/prometheus) for more.\n\nAlso see [getorb.io](https://getorb.io) for information on connecting pktvisor agents to the Orb observability platform.\n\n### REST API\n\nREST API documentation is available in [OpenAPI Format](https://app.swaggerhub.com/apis/netboxlabs/pktvisor/3.0.0-oas3)\n\nPlease note that the administration control plane API (`--admin-api`) is currently undergoing heavy iteration and so is\nnot yet documented. If you have a use case that requires the administration API, please [contact us](#contact-us) to\ndiscuss.\n\n### Advanced Agent Example\n\nStarting the collector agent from Docker with MaxmindDB GeoIP/GeoASN support and using the Host option to identify\ningress and egress traffic:\n\n```\ndocker run --rm --net=host -d \\\n    --mount type=bind,source=/opt/geo,target=/geo \\\n    netboxlabs/pktvisor pktvisord \\\n    --geo-city /geo/GeoIP2-City.mmdb \\\n    --geo-asn /geo/GeoIP2-ISP.mmdb \\\n    -H 192.168.0.54/32,127.0.0.1/32 \\\n    eth0\n```\n\nThe same command with AppImage and logging to syslog:\n\n```\n./pktvisor-x86_64.AppImage pktvisord -d --syslog \\\n    --geo-city /geo/GeoIP2-City.mmdb \\\n    --geo-asn /geo/GeoIP2-ISP.mmdb \\\n    -H 192.168.0.54/32,127.0.0.1/32 \\\n    eth0\n```\n\n### Further Documentation\n\nWe recognize the value of first class documentation, and we are working on further documentation including expanded and\nupdated REST API documentation, internal documentation for developers of input and handler modules (and those who want\nto contribute to pktvisor), and a user manual.\n\nPlease [contact us](#contact-us) if you have any questions on installation, use, or development.\n\n## Contact Us\n\nWe are very interested in hearing about your use cases, feature requests, and other feedback!\n\n* [File an issue](https://github.com/netboxlabs/pktvisor/issues/new)\n* See existing [issues](https://github.com/netboxlabs/pktvisor/issues)\n* Start a [Discussion](https://github.com/netboxlabs/pktvisor/discussions)\n* [Join us on Slack](https://join.slack.com/t/netboxlabs/shared_invite/zt-qqsm5cb4-9fsq1xa~R3h~nX6W0sJzmA)\n* Send mail to [info@pktvisor.dev](mailto:info@pktvisor.dev)\n\n## Build\n\nThe main code base is written in clean, modern C++. The `pktvisor-cli` command line interface is written in Go. The\nbuild system requires CMake and the [Conan](https://conan.io/) package manager system.\n\npktvisor adheres to [semantic versioning](https://semver.org/).\n\npktvisor is developed and tested on Linux and OSX. A Windows port is in progress. Both x86_64 and ARM architectures are known to function.\n\n#### Dependencies\n\n* [Conan](https://conan.io/) 2.X C++ package manager\n* CMake \u003e= 3.24 (`cmake`)\n* C++ compiler supporting C++17\n\nFor the list of packages included by conan, see [conanfile.py](conanfile.py)\n\n#### Building\n\nThe general build steps are:\n\n```\n# clone the repository\ngit clone https://github.com/netboxlabs/pktvisor.git\ncd pktvisor/\nconan profile detect -f\ncd build/\n# configure and handle dependencies \ncmake -DCMAKE_BUILD_TYPE=Release -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=./cmake/conan_provider.cmake ..\n\n# build and run tests\nmake all test\n\n# the binaries will be in the build/bin directory\nbin/pktvisord --help\n```\n\nAs development environments can vary widely, please see\nthe [Dockerfile](https://github.com/netboxlabs/pktvisor/blob/master/docker/Dockerfile)\nand [Continuous Integration build file](https://github.com/netboxlabs/pktvisor/blob/master/.github/workflows/build.yml) for\nreference.\n\n## Contribute\n\nThanks for considering contributing! We will expand this section with more detailed information to guide you through the\nprocess.\n\nPlease open Pull Requests against the `develop` branch. If you are considering a larger\ncontribution, [please contact us](#contact-us) to discuss your design.\n\nSee the [NS1 Contribution Guidelines](https://github.com/ns1/community) for more information.\n\n## License\n\nThis code is released under Mozilla Public License 2.0. You can find terms and conditions in the LICENSE file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetboxlabs%2Fpktvisor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnetboxlabs%2Fpktvisor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnetboxlabs%2Fpktvisor/lists"}