KFL Reference

KFL (Kubeshark Filter Language) is the query language used across Kubeshark — the dashboard, MCP, and API all return results matching KFL queries. It uses Common Expression Language (CEL) to query traffic with Kubernetes, API, and network semantics.

KFL queries affect what traffic is returned from the indexed database. They do not impact which traffic is captured. For controlling what traffic is captured, see Capture Filters.

Using KFL

In the dashboard, enter a KFL expression in the query input box:

Every element visible in the dashboard has a green + button that can be clicked to automatically add query expressions — helping build complex queries without typing.

KFL queries also work via MCP (for AI agents) and the API, using the kfl parameter.

Quick Examples

# HTTP GET requests with errors
http && method == "GET" && status_code >= 400

# Traffic to a specific namespace
dst.pod.namespace == "production"

# DNS queries for specific domains
dns && "google.com" in dns_questions

# Large HTTP responses
http && response_body_size > 10000

# Failed gRPC calls
grpc && grpc_status != 0

# Slow requests (over 5 seconds)
http && elapsed_time > 5000000

# Recent traffic (last 5 minutes)
timestamp > now() - duration("5m")

Operators

String Functions

Collection Functions

Time Functions

Supported Variables

Network-Level Variables

Kubernetes Variables

Pod fields automatically fall back to service data when pod info is unavailable — dst.pod.namespace works even when only service-level resolution exists.

Local and Remote Peers

src/dst are derived from the entry’s underlying SrcIsLocal flag: when it is true, src is the local peer; otherwise, src is the remote peer. dst is the other peer. For request/response TCP entries, these normally identify the request sender and receiver, independently of which socket was traced.

Known exception: for wire-captured TCP streams first observed from the server (SYN-ACK-first or server-first mid-stream), the local peer is the inferred client but SrcIsLocal remains false. The derived src/dst can therefore be reversed. Do not assume request-direction invariance for those entries.

local/remote describe the two peer slots instead. Their orientation depends on both the capture source and the entry path:

TCP client/server inference uses the handshake when available and port heuristics for mid-stream pickup. Aggregated UDP flows use a port heuristic, which can misidentify roles for custom protocols. SCTP does not infer the association initiator. The per-packet UDP/DNS and separate UDP connection paths do not share the aggregate flow’s client-local policy.

For an L7 TCP request captured at both endpoint sockets under eBPF, there are two entries: one where local is the client and one where local is the server. An af_packet TCP stream produces one L7 entry per request, not one per connection; a persistent connection can carry multiple requests.

For TCP streams and aggregated flows, a filter using local_labels must target the inferred client to match both eBPF and af_packet. For example, when checkout is the client and payments is the server:

# Matches the client-local eBPF entry and the client-local af_packet entry
local_labels["app"] == "checkout"

# Matches the server on client-local entries under either capture source
remote_labels["app"] == "payments"

By contrast, local_labels["app"] == "payments" matches the server-local eBPF entry but not the client-local af_packet entry. These filters do not match both eBPF orientations. For request-direction IP, pod, service, or namespace filters, use src/dst, subject to the server-first TCP exception above.

Labels and Annotations

In these label and annotation maps, a missing key reads as "" rather than raising an error, so bracket and dot access are both safe:

local_labels["app"] == "checkout"
remote_labels.version == "canary"
"tier" in local_labels

map_get() also returns "" for a missing key in these wrapped string maps, even when a different default is supplied. To distinguish an absent key from a present key whose value is empty, use membership and a ternary expression:

# Select entries with no app label, or with app explicitly set to "none"
("app" in local_labels ? local_labels["app"] : "none") == "none"

DNS Resolution

Resolution Status

Protocol Detection

Boolean variables that indicate which protocol was detected. Use these as the first filter term for best performance.

Identity and Metadata Variables

Cross-Reference Variables

Capture Source Variables

HTTP Variables

GraphQL requests have gql (or gqlv1/gqlv2) set to true and all HTTP variables available.

gRPC Variables

gRPC traffic is detected as a sub-protocol of HTTP/2. When grpc is true, all HTTP variables are also available.

DNS Variables

TLS Variables

TCP Variables

UDP Variables

SCTP Variables

ICMP Variables

WebSocket Variables

Redis Variables

Kafka Variables

AMQP Variables

LDAP Variables

RADIUS Variables

Diameter Variables

L4 Connection Tracking Variables

Use tcp_conn or udp_conn to filter by transport protocol.

conn && conn_state == "open" && conn_local_bytes > 1000000
tcp_conn && "HTTP" in conn_l7_detected

L4 Flow Tracking Variables

Flows extend connections with rate metrics (packets/bytes per second).

Use tcp_flow or udp_flow to filter by transport protocol.

flow && flow_local_pps > 1000
tcp_flow && flow_local_bps > 5000000

Filter Examples

Basic Network Filtering

# Filter by destination port
dst.port == 80

# Filter by IP address prefix
src.ip.startsWith("192.168.")

# Filter by multiple ports
dst.port == 80 || dst.port == 443 || dst.port == 8080

# Port range
dst.port >= 8000 && dst.port <= 9000

Kubernetes Filtering

# Traffic from a specific pod
src.pod.name == "web-server-123"

# Traffic to a specific namespace
dst.pod.namespace == "production"

# Inter-service communication
src.service.name == "api-gateway" && dst.service.name == "user-service"

# Traffic involving production namespace
"production" in namespaces

# Filter by local-peer pod labels (orientation depends on capture source and entry path)
local_labels["app"] == "payments"

# Filter by process name
local_process_name == "nginx"

HTTP Filtering

# GET requests
http && method == "GET"

# API endpoints
http && url.contains("/api")

# Client errors (4xx)
http && status_code >= 400 && status_code < 500

# Server errors (5xx)
http && status_code >= 500

# Specific header present
http && "authorization" in request.headers

# Header value match
http && request.headers["content-type"] == "application/json"

# URL pattern matching
http && url.matches(".*/api/v[0-9]+/.*")

# Large responses
http && response_body_size > 1000000

# Slow requests (over 5 seconds)
http && elapsed_time > 5000000

# GraphQL errors
gql && status_code >= 400

DNS Filtering

# DNS requests only
dns && dns_request

# Specific domain queries
dns && "google.com" in dns_questions

# Failed DNS lookups
dns && dns_response && status_code != 0

# A record queries
dns && "A" in dns_question_types

# DNS responses with answers
dns && dns_response && size(dns_answers) > 0

gRPC Filtering

# All gRPC traffic
grpc

# Filter by gRPC method name
grpc && grpc_method == "SayHello"

# Failed gRPC calls (non-OK status)
grpc && grpc_status != 0

# Specific gRPC status code (e.g. 5 = NOT_FOUND)
grpc && grpc_status == 5

# Combine with HTTP variables
grpc && method == "POST" && status_code == 200

DNS Resolution Filtering

Use src.dns and dst.dns to filter traffic by the resolved DNS name of a peer’s IP address. This works on any protocol, not just DNS traffic.

# Traffic to a specific external domain
dst.dns == "db.example.com"

# Traffic involving a domain (either direction)
src.dns.contains("example.com") || dst.dns.contains("example.com")

# Check if any peer resolved to a domain
"db.example.com" in dns_resolutions

# External traffic (resolved DNS, not internal)
dst.dns != "" && !dst.dns.endsWith(".internal")

Database and Messaging Filtering

# Redis GET commands
redis && redis_type == "GET"

# Redis key pattern
redis && redis_key.startsWith("session:")

# Kafka produce operations
kafka && kafka_api_key_name == "PRODUCE"

# Kafka topic filtering
kafka && kafka_request_summary.contains("orders")

# Large Kafka messages
kafka && kafka_size > 10000

# AMQP publish
amqp && amqp_method == "basic.publish"

# LDAP bind requests
ldap && ldap_type == "bind"

# RADIUS auth
radius && radius_code_name == "Access-Request"

Transport and Connection Filtering

# TCP errors
tcp && tcp_error_type != ""

# Open connections with high volume
conn && conn_state == "open" && conn_local_bytes > 1000000

# High packet-rate flows
flow && flow_local_pps > 1000

# High-bandwidth TCP flows
tcp_flow && flow_local_bps > 5000000

# Connections with detected L7 protocols
conn && "HTTP" in conn_l7_detected

Negation

# Everything that is NOT HTTP
!http

# HTTP responses that aren't 200
http && status_code != 200

# Exclude health checks
http && !path.contains("/health")

# Exclude system namespace
!(src.pod.namespace == "kube-system")

Time-Based Filtering

# After a specific time
timestamp > timestamp("2026-03-14T22:00:00Z")

# Time range
timestamp >= timestamp("2026-03-14T22:00:00Z") && timestamp <= timestamp("2026-03-14T23:00:00Z")

# Last 5 minutes
timestamp > now() - duration("5m")

Complex Filters

# HTTP API requests from internal network
src.ip.startsWith("192.168.") && http && method == "POST" && url.contains("/api")

# Error conditions across protocols
http && status_code >= 500 || (tcp && tcp_error_type != "")

# Production namespace with HTTP errors
src.pod.namespace == "production" && http && status_code >= 400

# Cross-namespace communication
src.service.namespace != dst.service.namespace

# Filter by capture source
capture_source == "ebpf_tls"

Type Safety

KFL is statically typed. Common gotchas:

• status_code is int, not string — use status_code == 200, not "200"
• elapsed_time is in microseconds — 5 seconds = 5000000
• timestamp requires the timestamp() function — not a raw string
• KFL string-map variables, including labels and annotations, return "" for missing keys. For other maps, guard potentially missing keys with key in map before accessing them.
• List membership uses value in list — not list.contains(value)

Default Values

When a variable is not present in an entry, KFL uses these defaults:

Performance Tips

1. Protocol flags first — http && ... is faster than ... && http
2. startsWith/endsWith over contains — prefix/suffix checks are faster
3. Specific ports before string ops — dst.port == 80 is cheaper than url.contains(...)
4. Keep filters simple — CEL short-circuits on &&, so put cheap checks first
5. Empty filters match all — an empty filter string matches all traffic

KFL vs Capture Filters

For those familiar with Wireshark: KFL is analogous to Wireshark’s display filters, while Capture Filters are analogous to Wireshark’s BPF filters.