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 Telemetry.

See the telemetry direction conventions for information on the meanings of local and other prefixes.

Requirements

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.

Stats: Bytes, Rates and Packets

The byte, rate, and packet counters in the flow record reflect activity observed during a specific interval of the flow lifecycle. While these values are useful for quick analysis and real-time decision-making, they are not intended for calculating cumulative flow totals.

For accurate aggregation and historical analysis, flow stats data should be used, as it is designed to capture detailed metrics across defined time buckets.

Attributes

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

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 in the current lifecycle.

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 in the current lifecycle.

flow.local_port

integer

Local endpoint port.

flow.local_rate

number

Burst local rate for the flow in the current lifecycle.

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 in the current lifecycle.

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 in the current lifecycle.

flow.other_port

integer

Other endpoint port.

flow.other_rate

number

Current other transmit rate for the flow in the current lifecycle.

flow.other_type

string

Other endpoint network type classification.

Values:

local remote broadcast multicast unsupported error unknown

flow.risks

object

Risk assessment data derived from nDPI protocol driver.

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.risks.risks

array

Set of nDPI risk identifiers triggered for this flow.

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

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

flow.ssl.alpn_server

array

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.tags

array

List of tags associated with this 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.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.

type

string

Telemetry record type. Always flow.

Values:

flow flow_dpi_update flow_dpi_complete

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,
      "risks": []
    },
    "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"
}