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.

Labels and Annotations

Always use map_get() for labels and annotations — direct access like local_labels["app"] errors if the key doesn’t exist:

map_get(local_labels, "app", "") == "checkout"
map_get(remote_labels, "version", "") == "canary"
"tier" in local_labels

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 pod labels (safe access)
map_get(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
• Map access on missing keys errors — use key in map or map_get() first
• 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. Use map_get for labels — avoids errors on missing keys
5. Keep filters simple — CEL short-circuits on &&, so put cheap checks first
6. 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.