Flow Telemetry

The Flow telemetry record contains per-flow metadata produced by the DPI engine and flow tracker. Emitted at detection and during DPI updates and completion, it reports detected application and protocol identifiers, hostnames (SNI/HTTP Host), TLS certificate details, and protocol-specific metadata used for classification and enrichment.

Use the Flow record for event-driven detection, enrichment, routing decisions, and early-alerting workflows. For periodic bandwidth and KPI reporting use the flow_stats telemetry, and for final per-session counters and end-state details use the flow_purge record.

See the telemetry direction conventions for information on loca meanings of local_ and other_ prefixes.

Requirements

Flow telemetry was introduced in the Core Plugin in version 1.0.20. To begin streaming the telemetry:

Install and configure the Netify Agent
Install and configure a Sink Plugin for receiving the telemetry
Install and configure the Core Plugin and add stream-flows to types

Source: Core Plugin
Plugin Release: 1.0.20

Flow Detection Lifecycle

The flow record format is used by three different stages of the flow detection lifecycle:

flow: Triggers the moment a new flow is detected.
flow_dpi_update: Triggers on a mid-stream refinement, for example, a TLS certificate detail after deeper packet analysis.
flow_dpi_complete: Marks the exact point the DPI engine has completed the flow analysis.

In most cases, the flow_dpi_complete is the only stage that you should be using for flow bandwidth stats and analytics. The flow and flow_dpi_update stages are typically used for special early-detection use cases involving routing, firewalling and QoS.

Optimizations

Flow Digests

The digest is a 7-tuple derived from the following flow properties:

source IP
destination IP
source port
destination port
IP protocol (TCP, UDP, etc)
VLAN ID
network interface

As protocol dissection and classification occurs, additional properties are added to the digest and tracked in the digest_prev array. As an integrator, the only value of interest is the very first index (0), which will always be the 7-tuple digest that will never change over the entire duration of the flow tracking. For Netify 5.2 or later, digest_prev will always exist. For earlier versions, the digest should be used if digest_prev does not exist.

Local Rate

The local_rate is a burst rate, not a sustained average. Within a standard 15-second stats interval, a 1-second flow will report its full bandwidth for that second, not the full 15-second interval. Here are some considerations:

Volatility: Rates calculated over short durations are statistically noisy and easily misinterpreted. Use this data knowing it reflects peak intensity, not long-term trends.
Non-Additive: Because local_rate represents a burst, you cannot sum it across multiple flows. Doing so will create an inaccurate "phantom" total.

Visualization Best Practice: Avoid standard line charts which can become noisy. Use heatmaps or scatterplots to identify outliers, and always provide actual bandwidth for context.

Attributes

type

string

Telemetry record type for flow events.

Values

flow flow_dpi_update flow_dpi_complete

flow

object

Container for per-flow network and DPI metadata.

flow.app_ip_override

boolean

Indicates whether application IP override logic was applied.

flow.app_proto_twins

boolean

Indicates whether protocol twin detection metadata was applied.

flow.bt

object

BitTorrent protocol metadata extracted from the flow.

flow.bt.info_hash

string

BitTorrent info hash represented as a hexadecimal SHA-1 digest.

flow.category

object

Application, domain, and protocol category identifiers.

flow.category.application

integer

Detected application category ID.

Reference: Application Categories

flow.category.domain

integer

Detected domain category ID.

Reference: Category Lists

flow.category.local_network

integer

Local network category ID.

Reference: Category Lists

flow.category.other_network

integer

Other network category ID.

Reference: Category Lists

flow.category.overlay

integer

Overlay network category ID, when applicable.

Reference: Overlay

flow.category.protocol

integer

Detected protocol category ID.

Reference: Protocol Categories

flow.conntrack

object

Connection tracking metadata.

flow.conntrack.id

integer

Conntrack flow identifier.

flow.conntrack.mark

integer

Conntrack mark value.

flow.conntrack.reply_dst_ip

string

Destination IP in the conntrack reply tuple.

flow.conntrack.reply_dst_port

integer

Destination port in the conntrack reply tuple.

flow.conntrack.reply_src_ip

string

Source IP in the conntrack reply tuple.

flow.conntrack.reply_src_port

integer

Source port in the conntrack reply tuple.

flow.detected_application

integer

Detected application ID.

Reference: Applications Catalog

flow.detected_application_name

string

Detected application tag.

Reference: Applications Catalog

flow.detected_protocol

integer

Detected protocol ID.

Reference: Protocols Catalog

flow.detected_protocol_name

string

Detected protocol name from the underlying DPI driver.

flow.detection_guessed

boolean

True when protocol classification is inferred by default port rather than fully dissected.

flow.detection_packets

integer

Number of packets used to complete DPI classification.

flow.detection_updated

boolean

True when additional packets update an earlier classification.

flow.dhc_hit

boolean

Indicates whether domain hint cache contributed to classification.

flow.dhcp

object

DHCP metadata extracted from protocol payloads when available.

flow.dhcp.class_ident

string

DHCP class identifier value observed in the flow.

flow.dhcp.fingerprint

string

DHCP fingerprint string extracted from client options.

flow.digest

string

Current unique flow digest based on known flow attributes.

flow.digest_prev

array[string]

List of previous sibling digests associated with this flow.

flow.dns_host_name

string

Hostname associated with a corresponding DNS query.

flow.fhc_hit

boolean

Indicates whether flow hash cache contributed to classification.

flow.first_seen_at

integer

Timestamp in Unix epoch milliseconds when the flow was first observed.

flow.gtp

object

GTP tunnel metadata when encapsulated traffic is detected.

flow.gtp.ip_dscp

integer

DSCP value observed for the inner GTP payload network context.

flow.gtp.ip_version

integer

IP version for the inner GTP payload network context.

Values

4 6

flow.gtp.local_ip

string

Local tunnel endpoint IP for the inner GTP flow.

flow.gtp.local_port

integer

Local tunnel endpoint port for the inner GTP flow.

flow.gtp.local_teid

integer

Local tunnel endpoint identifier (TEID) for the inner GTP flow.

flow.gtp.other_ip

string

Other tunnel endpoint IP for the inner GTP flow.

flow.gtp.other_port

integer

Other tunnel endpoint port for the inner GTP flow.

flow.gtp.other_teid

integer

Other tunnel endpoint identifier (TEID) for the inner GTP flow.

flow.gtp.other_type

string

Other endpoint network type for the inner GTP flow.

Values

local remote unsupported error

flow.gtp.version

integer

Observed GTP protocol version.

flow.host_server_name

string

Hostname extracted from protocol metadata (for example TLS SNI or HTTP Host header).

flow.http

object

HTTP metadata extracted from protocol payloads when available.

flow.http.url

string

HTTP URL observed in the flow payload.

flow.http.user_agent

string

HTTP User-Agent header value observed in the flow payload.

flow.ip_dscp

integer

Differentiated Services Code Point (DSCP) value.

flow.ip_nat

boolean

Indicates whether Network Address Translation (NAT) was detected.

flow.ip_protocol

integer

IP protocol number.

Reference: Wikipedia

flow.ip_version

integer

IP version used by the flow.

Values

4 6

flow.last_seen_at

integer

Timestamp in Unix epoch milliseconds when the flow was last observed.

flow.local_bytes

integer

Bytes sent from the local endpoint.

flow.local_ip

string

Local endpoint IP address.

flow.local_mac

string

Local endpoint MAC address.

flow.local_origin

boolean

Indicates whether the local endpoint originated the connection.

flow.local_packets

integer

Packets sent from the local endpoint.

flow.local_port

integer

Local endpoint port.

flow.local_rate

number

Burst local rate for the flow.

flow.mdns

object

mDNS metadata extracted from multicast DNS traffic when available.

flow.mdns.answer

string

mDNS answer domain name extracted from the flow.

flow.nfq

object

NFQUEUE interface metadata when packet queue integration is enabled.

flow.nfq.dst_iface

string

Destination interface name reported by NFQUEUE for this flow.

flow.nfq.src_iface

string

Source interface name reported by NFQUEUE for this flow.

flow.other_bytes

integer

Bytes sent from the other endpoint.

flow.other_ip

string

Other endpoint IP address.

flow.other_mac

string

Other endpoint MAC address when available.

flow.other_packets

integer

Packets sent from the other endpoint.

flow.other_port

integer

Other endpoint port.

flow.other_rate

number

Current other transmit rate for the flow.

flow.other_type

string

Other endpoint network type classification.

Values

local remote broadcast multicast

flow.risks

object

Risk assessment data derived from nDPI protocol driver.

flow.risks.risks

array[integer]

Set of nDPI risk identifiers triggered for this flow.

flow.risks.ndpi_risk_score

integer

Aggregate nDPI risk score for the flow.

flow.risks.ndpi_risk_score_client

integer

nDPI risk score associated with client-side indicators.

flow.risks.ndpi_risk_score_server

integer

nDPI risk score associated with server-side indicators.

flow.soft_dissector

boolean

Indicates whether a soft dissector was used.

flow.ssl

object

TLS/SSL metadata extracted when encrypted traffic is detected.

flow.ssl.alpn

array[string]

List of Application-Layer Protocol Negotiation (ALPN) protocol identifiers offered or negotiated for the TLS session.

flow.ssl.alpn_server

array[string]

List of Application-Layer Protocol Negotiation (ALPN) protocol identifiers provided.

flow.ssl.cipher_suite

string

Hexadecimal TLS cipher suite identifier (for example 0x1303).

flow.ssl.client_ja4

string

JA4 TLS client fingerprint extracted from the handshake.

flow.ssl.client_sni

string

Server Name Indication (SNI) value sent by the TLS client.

flow.ssl.encrypted_ch_version

string

Encrypted client hello (ECH) version.

flow.ssl.fingerprint

string

SHA-1 digest fingerprint of the observed TLS certificate.

flow.ssl.issuer_dn

string

TLS server certificate issuer distinguished name, e.g. Let's Encrypt.

flow.ssl.server_cn

string

TLS server common name.

flow.ssl.subject_dn

string

TLS server certificate issuer distinguished name.

flow.ssl.version

string

Hexadecimal TLS version value observed in handshake metadata.

flow.ssh

object

SSH handshake metadata extracted when available.

flow.ssh.client

string

SSH client agent or software identification string.

flow.ssh.server

string

SSH server agent or software identification string.

flow.ssdp

object

SSDP metadata extracted when available.

flow.ssdp.user_agent

string

SSDP User-Agent value observed in the flow.

flow.stun

object

STUN address metadata extracted from STUN payloads when available.

flow.stun.mapped

string

STUN mapped address (host:port) observed in the flow.

flow.stun.other

string

STUN other address (host:port) observed in the flow.

flow.stun.peer

string

STUN peer address (host:port) observed in the flow.

flow.stun.relayed

string

STUN relayed address (host:port) observed in the flow.

flow.stun.response

string

STUN response address (host:port) observed in the flow.

flow.tcp

object

TCP health and error counters for TCP flows.

flow.tcp.resets

integer

Count of observed TCP reset packets for the flow.

flow.tcp.retrans

integer

Count of observed TCP retransmissions for the flow.

flow.tcp.seq_errors

integer

Count of TCP sequence anomalies for the flow.

flow.total_bytes

integer

Total bytes seen for the flow in both directions.

flow.total_packets

integer

Total packets seen for the flow in both directions.

flow.tags

array[string]

List of tags associated with this flow.

flow.vlan_id

integer

Observed VLAN ID.

interface

string

Interface name associated with this flow record.

internal

boolean

Indicates whether this flow is internal to the local network context.

Flow Attributes - Example

{
  "flow": {
    "app_ip_override": false,
    "category": {
      "application": 28,
      "domain": 0,
      "local_network": 0,
      "other_network": 0,
      "overlay": 0,
      "protocol": 22
    },
    "conntrack": {
      "id": 3603527535,
      "mark": 0,
      "reply_dst_ip": "192.168.4.44",
      "reply_dst_port": 35636,
      "reply_src_ip": "192.200.0.102",
      "reply_src_port": 443
    },
    "detected_application": 11354,
    "detected_application_name": "netify.tailscale",
    "detected_protocol": 196,
    "detected_protocol_name": "HTTP/S",
    "detection_guessed": false,
    "detection_updated": false,
    "dhc_hit": false,
    "digest": "c4c07ca55baa19a7fe3652bcd356765a7...",
    "digest_prev": [
      "463c53093403fcce8eeb01df5b5125df66a0f53b"
    ],
    "dns_host_name": "login.tailscale.com",
    "fhc_hit": false,
    "first_seen_at": 1772738467573,
    "host_server_name": "login.tailscale.com",
    "ip_dscp": 0,
    "ip_nat": false,
    "ip_protocol": 6,
    "ip_version": 4,
    "last_seen_at": 1772738467684,
    "local_ip": "192.168.4.44",
    "local_mac": "f8:e9:03:01:69:13",
    "local_origin": true,
    "local_port": 35636,
    "other_ip": "192.200.0.102",
    "other_mac": "3c:7c:3f:a1:ed:58",
    "other_port": 443,
    "other_type": "remote",
    "risks": {
      "ndpi_risk_score": 0,
      "ndpi_risk_score_client": 0,
      "ndpi_risk_score_server": 0
    },
    "soft_dissector": false,
    "ssl": {
      "alpn": [
        "h2",
        "http/1.1"
      ],
      "cipher_suite": "0x0000",
      "client_ja4": "t13d1817h2_e8a523a41297_...",
      "client_sni": "login.tailscale.com",
      "encrypted_ch_version": "0xfe0d",
      "version": "0x0303"
    },
    "vlan_id": 0
  },
  "interface": "wlp3s0",
  "internal": true,
  "type": "flow"
}