Pktvisor

The pktvisor backend embeds the pktvisord process inside Orb Agent to run deep packet analytics, active probes, and streaming aggregations directly at the edge. Pktvisor policies let you decide which network taps to activate, which analyzers to run, and how the resulting metrics are exported to your observability stack.

Reference

The two sections of a policy have a folder each.

Configuration

Orb writes a temporary pktvisor configuration file on startup based on the orb.backends.pktvisor block. Any key that is not handled explicitly is forwarded to visor.config in the generated file, so you can pass through native pktvisor options such as logging, crashpad, or custom data paths when needed.

Backend settings

Pktvisor ships with the Orb agent container image. If you run Orb on a bare host, ensure the pktvisord binary is in $PATH or adjust your deployment accordingly.

Taps

A tap names a data source once, on the agent, so that policies can refer to it. Each tap sets an input_type, its config, and optional tags that a policy can select on. See Inputs for the configuration each input type accepts.

A tap has no filter key: filters belong to the policy's input, and a filter written on a tap is ignored without an error. For packet capture a BPF expression can also go in the tap's config, since pcap accepts bpf there.

orb:
  backends:
    pktvisor:
      host: 0.0.0.0
      port: "10853"
      taps:
        edge_dns:
          input_type: pcap
          config:
            iface: eth0
            bpf: "port 53"
        sflow:
          input_type: flow
          config:
            flow_type: sflow
            port: 6343
            bind: 192.168.1.1
          tags:
            virtual: false
            vhost: 2
    common:
      otlp:
        http: "http://otel-collector.monitoring.svc.cluster.local:4318"

Exporting pktvisor metrics

pktvisord can stream OpenTelemetry HTTP metrics directly to a collector. Configure the shared backends.common.otlp section, as in the example above, to point Orb Agent at your collector endpoint.

Policy structure

Define pktvisor policies under orb.policies.pktvisor. Each entry key becomes the policy name pushed to pktvisord, and the agent wraps the body you write in the envelope pktvisord expects, so the body is just the four sections below.

orb:
  policies:
    pktvisor:
      my_policy:
        input: ...
        handlers: ...
        config: ...
        kind: collection

A policy name must be unique within the backend. Policy, tap and handler module names must match [a-zA-Z_][a-zA-Z0-9_-]*, so they start with a letter or underscore and contain only letters, digits, _ or -.

Example policy

The following policy inspects DNS traffic captured from the edge_dns tap and runs both DNS-specific and network-wide analytics. Use this pattern when you want to reuse a tap across multiple handlers.

orb:
  policies:
    pktvisor:
      edge_dns_inspection:
        input:
          input_type: pcap
          tap: edge_dns
        config:
          merge_like_handlers: true
        handlers:
          window_config:
            num_periods: 5
            deep_sample_rate: 100
          modules:
            dns_summary:
              type: dns
              require_version: "2.0"
              metric_groups:
                enable:
                  - counters
                  - quantiles
              config:
                public_suffix_list: true
                topn_count: 25
            net_overview:
              type: net
        kind: collection

Note the require_version: "2.0" on the DNS module. A module that omits require_version runs version 1.0 of that handler; see available handlers.

Additional resources

• Pktvisor project home - feature overview, module reference, and deployment notes.