Filetrace metrics and telemetry attributes reference

Every exported metric with its OpenTelemetry and Prometheus names, type, unit and attributes, plus resource attributes, log record attributes and loss kinds.

This page lists every name the Filetrace agent exports: each metric with its OpenTelemetry name, Prometheus name, type, unit, attributes and description; the resource attributes; every attribute of the OTLP log records with the event types that carry it; and the values of filetrace.loss.kind. It also gives the rule that turns an OpenTelemetry name into a Prometheus name. The same names appear on the Prometheus page and in the OTLP export.

​

Naming

Fields that OpenTelemetry’s semantic conventions cover use those names, such as process.pid, file.path and network.peer.address. Everything else is under filetrace..

A Prometheus name is made from the OpenTelemetry name the way an OpenTelemetry Collector makes it, so a query works whichever way the metrics arrive:

1. Every character other than a letter, a digit or an underscore becomes an underscore: filetrace.network.io becomes filetrace_network_io.
2. The unit is appended: _bytes for By and _seconds for s. A unit in braces, such as {transfer}, adds nothing.
3. A counter gets _total.

An attribute becomes a label by the first rule: process.executable.name becomes process_executable_name.

OpenTelemetry name	Unit	Type	Prometheus name
filetrace.network.io	By	Counter	filetrace_network_io_bytes_total
filetrace.transfers.active	{transfer}	Gauge	filetrace_transfers_active
process.cpu.time	s	Counter	process_cpu_time_seconds_total

​

Resource attributes

Every OTLP request carries these resource attributes. On the Prometheus page they are the labels of target_info, a gauge whose value is always 1.

Attribute	Prometheus label	Value
service.name	service_name	filetrace
service.version	service_version	The agent’s version
host.name	host_name	The host name of the machine
os.type	os_type	linux

OTLP requests also name the instrumentation scope filetrace, with the agent’s version as the scope version.

​

Metrics

OpenTelemetry name	Prometheus name	Type	Unit
filetrace.network.io	filetrace_network_io_bytes_total	Counter	By
filetrace.file.sent	filetrace_file_sent_bytes_total	Counter	By
filetrace.transfers.started	filetrace_transfers_started_total	Counter	{transfer}
filetrace.transfers.active	filetrace_transfers_active	Gauge	{transfer}
filetrace.connections.active	filetrace_connections_active	Gauge	{connection}
filetrace.processes.active	filetrace_processes_active	Gauge	{process}
filetrace.events.processed	filetrace_events_processed_total	Counter	{event}
filetrace.events.dropped	filetrace_events_dropped_total	Counter	{event}
process.cpu.time	process_cpu_time_seconds_total	Counter	s
process.memory.usage	process_memory_usage_bytes	Gauge	By

OpenTelemetry name	Attributes	Description
filetrace.network.io	process.executable.name, network.transport, network.io.direction	Bytes that local sockets accepted from processes and delivered to them.
filetrace.file.sent	process.executable.name, filetrace.transfer.method, filetrace.transfer.confidence	File bytes sent over the network.
filetrace.transfers.started	process.executable.name, filetrace.transfer.method, filetrace.transfer.confidence	File transfers observed.
filetrace.transfers.active	filetrace.transfer.confidence	File transfers in progress.
filetrace.connections.active		Sockets that are open or have recent traffic.
filetrace.processes.active		Processes with network traffic in the last few seconds.
filetrace.events.processed		Events the agent took from the kernel.
filetrace.events.dropped	filetrace.loss.kind	Events lost before the agent could record them.
process.cpu.time		Processor time the agent has consumed.
process.memory.usage		Resident memory of the agent.

process.cpu.time and process.memory.usage describe the agent itself. Every value is an integer except process.cpu.time, which is a floating-point number of seconds.

In OTLP, a counter is a monotonic sum with cumulative temporality whose start time is when the agent started, and the other metrics are gauges. On the Prometheus page the types are counter and gauge. Counters start at zero with the agent and never go backwards while it runs.

​

Metric attributes

Metric attributes are strings.

Attribute	Prometheus label	Values
process.executable.name	process_executable_name	The kernel’s name for the process, at most 15 bytes
network.transport	network_transport	The transport protocol, such as tcp or udp
network.io.direction	network_io_direction	transmit or receive
filetrace.transfer.method	filetrace_transfer_method	sendfile or read-write
filetrace.transfer.confidence	filetrace_transfer_confidence	exact or inferred; filetrace.transfers.active also has a strong point, which stays at 0
filetrace.loss.kind	filetrace_loss_kind	event_queue, counter_table or socket_identity; see Loss kinds
otel.metric.overflow	otel_metric_overflow	true, alone on the series that sums the label sets beyond [limits] metric_series

[limits] metric_series (default 2048) bounds the label sets of filetrace.network.io, filetrace.file.sent and filetrace.transfers.started together. A label set beyond the limit is added to one overflow series per metric, as OpenTelemetry SDKs do. No metric has a file path or an address as an attribute.

​

Loss kinds

filetrace.loss.kind says where events were lost. It is an attribute of the filetrace.events.dropped metric, which has a point for each kind, and of event_loss log records.

Value	Meaning	Field of filetrace stats --json
event_queue	The kernel-to-agent event queue overflowed. Its size is [agent] ring_buffer_size.	dropped_queue_overflow
counter_table	The in-kernel counter table was full. Its size is [limits] kernel_counters.	dropped_counter_table_full
socket_identity	A transfer’s socket had no usable identity.	dropped_socket_unidentified

Overhead and sizing explains how to size the queue and the tables.

​

Log records

Events leave as OTLP log records with:

Field	Value
Event name	filetrace.<type>, such as filetrace.file_transfer
Body	The event type as a string
Severity	INFO (severity number 9); WARN (13) for event_loss
Timestamp	When the event happened
Observed timestamp	When the batch that holds the record was prepared

The event types are process_exec, process_fork, process_exit, socket_connect, socket_listen, socket_established, socket_close, file_seen, network_send, network_receive, file_transfer and event_loss; see event types.

​

Log record attributes

An attribute whose value is not known is left out of the record.

Attribute	Type	Event types	Description
filetrace.event.type	string	All	The event type, such as file_transfer
process.pid	int	Process, socket, network, file_transfer	Process ID
process.parent_pid	int	Process, socket, network, file_transfer	Parent process ID
process.executable.name	string	Process, socket, network, file_transfer	The kernel’s name for the process
process.user.id	int	Process, socket, network, file_transfer	User ID of the process; present with process.executable.name
process.executable.path	string	Process	Path of the executable
process.exit.code	int	process_exit	Exit status of a process that exited
filetrace.process.exit_signal	int	process_exit	Number of the signal that ended the process, in place of process.exit.code
file.path	string	file_seen, file_transfer	Path of the file; left out with [otlp] file_paths = false
file.inode	string	file_seen, file_transfer	Inode number, in decimal
filetrace.file.device	int	file_seen, file_transfer	Device number of the file system that holds the file
file.size	int	file_seen, file_transfer	Size of the file when it was first seen
filetrace.file.deleted	bool	file_seen, file_transfer	true when the file has no remaining links; absent otherwise
filetrace.socket.id	int	Socket, network, file_transfer	Socket ID, as in the SOCKET column
network.transport	string	Socket, network, file_transfer	tcp, udp or another protocol name
network.type	string	Socket, network, file_transfer	ipv4 or ipv6
network.local.address	string	Socket, network, file_transfer	Local IP address
network.local.port	int	Socket, network, file_transfer	Local port
network.peer.address	string	Socket, network, file_transfer	Remote IP address
network.peer.port	int	Socket, network, file_transfer	Remote port
network.io.direction	string	network_send, network_receive	transmit or receive
filetrace.network.bytes	int	network_send, network_receive	Bytes the socket accepted (network_send) or delivered (network_receive) during the period the record covers
filetrace.transfer.method	string	file_transfer	sendfile or read-write
filetrace.transfer.bytes	int	file_transfer	File bytes the socket accepted during the period the record covers
filetrace.transfer.bytes_read	int	file_transfer	Bytes read from the file during the period the record covers; only for read-write
filetrace.transfer.confidence	string	file_transfer	exact or inferred, the level of the whole association so far; absent while it is below the reporting thresholds
filetrace.loss.events	int	event_loss	Number of events lost
filetrace.loss.kind	string	event_loss	Where they were lost; see Loss kinds

In the table, “Process” stands for process_exec, process_fork and process_exit; “Socket” for socket_connect, socket_listen, socket_established and socket_close; “Network” for network_send and network_receive. Socket events carry the process attributes only when the socket has a known owner. file_seen carries no process or socket attributes, and event_loss carries only the loss attributes and filetrace.event.type.

A string that is not valid UTF-8, such as a path or a process name, is sent with ? in place of the offending bytes.