Observability

Statistics🔗

By default, Tempesta Manager daemon (tempesta_mgr in process list) exposes an HTTP /metrics endpoint on localhost:9090 that return available statistics in text-based Prometheus exposition format.

The listen port and address for the statistics endpoint can be configured as the daemon command-line arguments in the xfw.conf file:

{
    "daemon_args": "--listen 127.0.0.1 --http-port 9090",
    ...
}

All statistics entries, both byte and packet counters, are of counter type. Therefore, they are prefixed with the corresponding TYPE and HELP metadata and look as follows:

# HELP xfw_passed_egress_bytes Total Passed egress bytes.
# TYPE xfw_passed_egress_bytes counter
xfw_passed_egress_bytes 0

All counters are prefixed with xfw_. Byte-related metrics are suffixed with _bytes, and packet-related metrics are suffixed with _packets.

The simplest way to retrieve the statistics is by using curl:

$ curl http://127.0.0.1:9090/metrics
# HELP xfw_syn_cookies_packets Total SYN cookies packets.                                                                                                       
# TYPE xfw_syn_cookies_packets counter                                    
xfw_syn_cookies_packets 0                  
# HELP xfw_syn_cookies_bytes Total SYN cookies bytes.                                                                                                           
# TYPE xfw_syn_cookies_bytes counter                                                                                                                            
xfw_syn_cookies_bytes 0                          
...

Events Logging🔗

Tempesta Escudo uses the open-source tfw_logger daemon with an additional plug-in for logging Tempesta xFW security events into a ClickHouse database. Refer to the Tempesta FW Access Log Analytics page for more information about the tfw_logger daemon.

Tempesta xFW event logging is configured using the xfw_events section in the tfw_logger configuration file. A configuration example can be found at /opt/tempesta/examples/xfw_logger.json.

Events log schema🔗

The Tempesta xFW plug-in for tfw_logger creates the following ClickHouse table:

CREATE TABLE IF NOT EXISTS xfw_events (
    timestamp DateTime64(3, 'UTC'),
    addr IPv6,
    reason UInt64,
    packets UInt64,
    bytes UInt64,
    dropped_events UInt64
) ENGINE = MergeTree()
ORDER BY timestamp;

Field descriptions🔗

Field	Type	Description
`timestamp`	DateTime64(3)	Event timestamp with millisecond precision (UTC)
`addr`	IPv6	Client IP address (IPv4 addresses are mapped to IPv6)
`reason`	UInt64	Bit field representing blocking reasons
`packets`	UInt64	Number of packets aggregated into the blocking event
`bytes`	UInt64	Number of bytes aggregated into the blocking event
`dropped_events`	UInt64	Number of dropped events

A single IP address may generate multiple packets that Tempesta xFW blocks for the same reason. Such packets, along with their total size, may be aggregated into a single event. The dropped events count is useful to track the number of events that did not make it into the statistics.

Example of the event log table:

:) SELECT timestamp, addr, bitPositionsToArray(reason), packets, bytes
   FROM xfw_events ORDER BY timestamp DESC LIMIT 10;

┌───────────────timestamp─┬─addr─────────────────┬─bits(reason)─┬─packets─┬─bytes─┐
│ 2026-01-15 21:32:13.979 │ ::ffff:192.168.100.1 │ [8]          │       1 │    70 │
│ 2026-01-13 15:26:22.618 │ ::ffff:192.168.100.1 │ [8]          │       1 │    54 │
│ 2026-01-13 15:26:21.608 │ ::ffff:192.168.100.1 │ [8]          │       1 │    54 │
│ 2026-01-13 15:26:19.596 │ ::ffff:192.168.100.1 │ [8]          │       1 │    54 │
│ 2026-01-13 15:26:18.589 │ ::ffff:192.168.100.1 │ [8]          │       1 │    54 │
│ 2026-01-13 14:00:55.076 │ ::ffff:192.168.100.1 │ [8]          │       1 │    54 │
│ 2026-01-13 14:00:54.061 │ ::ffff:192.168.100.1 │ [2]          │       5 │   270 │
│ 2026-01-13 13:44:05.385 │ ::ffff:192.168.100.1 │ [2]          │       6 │   324 │
│ 2026-01-13 13:43:59.344 │ ::ffff:192.168.100.1 │ [2]          │       2 │   108 │
│ 2026-01-13 13:43:58.337 │ ::ffff:192.168.100.1 │ [2,3]        │       5 │   270 │
└─────────────────────────┴──────────────────────┴──────────────┴─────────┴───────┘

Bits constituting the reason field:

Bit	Reason
0	Internal error: metadata creation failed
1	Blocked by the `icmp: block` rule
2	Blocked by the `tcp_flags syn: ratelimit` rule
3	Blocked by the `tcp_flags rst: ratelimit` rule
4	Blocked by the `icmp: ratelimit` rule
5	Blocked by the `defaults/icmp: block` rule
6	Blocked by the `defaults/icmp: ratelimit` rule
7	Blocked by the `dst: block` rule
8	Rate limited by the `dst: ratelimit` rule
9	Whitelisted by the `src_port: allow` rule
10	Blocked by the `src_port: block` rule
11	Rate limited by the `src_port: ratelimit` rule
12	Blocked by the `defaults/src_port: block` rule
13	Rate limited by the `defaults/src_port: ratelimit` rule
14	Whitelisted by the `src_ip: allow` rule
15	Blocked by the `src_ip: block` rule
16	Rate limited by the `src_ip: ratelimit` rule
17	Blocked by the `defaults/src_ip: block` rule
18	Rate limited by the `defaults/src_ip: ratelimit` rule
19	Blocked by TCP anomaly: invalid flags
20	Blocked by TCP anomaly: invalid SYN sequence number
21	Blocked by TCP anomaly: SYN without TCP options
22	Blocked by TCP anomaly: SYN packet with payload
23	Blocked by TCP anomaly: zero source or destination port
24	Blocked by UDP anomaly: zero source or destination port
25	Blocked during parsing: unknown EtherType
26	Blocked during parsing: malformed Ethernet header
27	Blocked during parsing: malformed IPv4 header
28	Blocked during parsing: fragmented IPv4 packet
29	Blocked during parsing: malformed IPv6 header
30	Blocked during parsing: fragmented IPv6 packet
31	Blocked during parsing: malformed TCP header
32	Blocked during parsing: malformed UDP header
33	Blocked during parsing: malformed ICMP header
34	Allowed during parsing: ARP packet
35	Blocked during parsing: unsupported L4 protocol
36	Blocked by `tcp_auth_filter`: unknown connection
37	Blocked by `tcp_auth_filter`: expired connection
38	Blocked by the `tcp_syncookies` rule: invalid SYN cookie
39	SYN cookie generated and sent to the client
40	Allowed: xFW rules are not loaded
41	Allowed during parsing: unknown EtherType
42	Allowed during parsing: malformed Ethernet header
43	Allowed during parsing: unsupported L4 protocol
44	Allowed during parsing: malformed IPv4 header
45	Allowed during parsing: malformed IPv6 header
46	Allowed during parsing: malformed TCP header
47	Allowed during parsing: malformed UDP header
48	Allowed: xFW rules are not loaded
49	Blocked during parsing: malformed DNS header
50	Blocked by DNS anomaly: non-zero RCODE in DNS query
51	Blocked during parsing: malformed DNS question
52	Blocked by DNS anomaly: more than one question in DNS packet
53	Blocked by DNS anomaly: answers or authority sections present in DNS query
54	Blocked by DNS anomaly: invalid IXFR query
55	Blocked by DNS anomaly: more than two additional sections in DNS query
56	Blocked by DNS anomaly: response received without a prior query
57	Blocked by DNS anomaly: DNS UDP response packet is too large
58	Blocked by DNS anomaly: DNS response contains too many answers
59	Blocked during parsing: malformed DNS resource record
60	Blocked by DNS anomaly: invalid TTL in DNS answer