Telemetry interfaces of the Filetrace agent

The three ways other tools get the agent’s data: a Prometheus page, OTLP over gRPC and a gRPC API; what each carries, how to enable it, naming and security.

Filetrace hands what its agent observes to other tools through three interfaces: a metrics page that Prometheus scrapes, an OTLP exporter that pushes events and metrics to an OpenTelemetry collector, and a gRPC API that lists and streams file transfers. This page describes what each interface carries, the setting that turns it on, how the exported data is named, and how the interfaces are secured.

​

The three interfaces

Interface	Carries	Turned on by	Default address
Prometheus page	Metrics, on http://127.0.0.1:9464/metrics	[prometheus] enabled = true	Listens on 127.0.0.1:9464
OTLP over gRPC	Events as log records, and the same metrics	[otlp] enabled = true	Sends to 127.0.0.1:4317
gRPC API	Status, transfers on request, transfers as they happen	[grpc] enabled = true	Listens on unix:/run/filetrace/api.sock

The metrics page and the gRPC API wait for clients to connect to the agent. The OTLP exporter works the other way: the agent connects to a collector and pushes to it.

​

Parts of the agent

The metrics page, the OTLP exporter and the gRPC API are parts of filetrace-agent, not separate programs, and all three are off until the configuration file turns them on. The agent reads /etc/filetrace/config.toml once, when it starts, so restart it after a change:

[prometheus]
enabled = true

[otlp]
enabled = true
endpoint = "127.0.0.1:4317"

[grpc]
enabled = true

filetrace config validate
sudo systemctl restart filetrace-agent

On systems without systemd, restart the service with the init system’s own command, as described in Run the agent as a service. filetrace config show prints every setting of the three sections with the value in effect; the configuration reference lists them all.

All three interfaces read the same state that the filetrace commands read. A transfer that filetrace files lists is the transfer that ListTransfers returns, and OTLP log records are made from the events that filetrace events prints. Turning an interface on adds nothing to what the probes do: it only reads what the agent already keeps.

Without a running agent, filetrace watch and filetrace events --follow collect in the foreground for as long as they run. Such a collector exports nothing, whatever the configuration file says.

The agent checks the addresses of the three sections when it starts; filetrace config validate checks only that an address is a string. If an address is not in an accepted form, or the agent cannot listen on it, the agent does not start and prints the reason. See exit codes.

​

Naming

The three interfaces name things the same way. Fields that OpenTelemetry’s semantic conventions cover use those names, such as process.pid, file.path and network.peer.address; the rest is under filetrace., such as filetrace.transfer.method and filetrace.socket.id.

A Prometheus name is what an OpenTelemetry Collector makes of the same metric: dots become underscores, then the unit is appended, then _total for a counter. An attribute becomes a label the same way. A PromQL query therefore works whether Prometheus scrapes the agent or receives the metrics through a collector.

OpenTelemetry	Prometheus
filetrace.network.io (bytes, counter)	filetrace_network_io_bytes_total
filetrace.transfers.active (gauge)	filetrace_transfers_active
process.executable.name (attribute)	process_executable_name (label)

The gRPC API carries the same values in protobuf messages: a transfer’s method is METHOD_SENDFILE there and sendfile in metrics and log records. The metrics and attributes reference lists every name.

​

Transport security

None of the interfaces uses TLS, and none resolves host names. An address is numeric (IPv4, or IPv6 in brackets such as [::1]:9464), or a unix: socket path where the interface accepts one; localhost stands for 127.0.0.1.

Interface	Accepts	Who can read or connect
Prometheus page	An address and port	Anyone who can reach the address; the page has no authentication
OTLP exporter	An address and port, or a unix: socket	The agent connects out to the collector
gRPC API	A unix: socket, or an address and port	On a unix: socket, root and the agent’s user; on an address and port, anyone who can connect, which the agent logs as a warning when it starts

The defaults keep all three on the machine: the metrics page listens on the loopback address, the exporter sends to a collector on the loopback address, and the API listens on a Unix socket. The intended setup for OTLP is an OpenTelemetry Collector or Grafana Alloy on the same host, which forwards to Loki, Elasticsearch, Splunk, Datadog or a SIEM with credentials and encryption of its own. Security covers the exposure of each interface.

​

Memory and restarts

Exported counters start at zero when the agent starts and never go backwards while it runs. They are kept apart from the agent’s tables, so a counter does not drop when a table forgets its least recently used entry. The counters, and the batches of log records waiting for a collector, live in memory and do not survive a restart of the agent.

​

Not included

• OpenTelemetry traces. The exporter sends log records and metrics only.
• OTLP over HTTP. The exporter speaks OTLP over gRPC only.
• TLS on any interface, and server reflection on the gRPC API.

​

Next steps

Prometheus

Enable the metrics page, scrape it, and query it with PromQL.

OpenTelemetry (OTLP)

Send events and metrics to an OpenTelemetry Collector.

gRPC API guide

List and stream transfers with grpcurl, buf curl or a generated client.

gRPC API reference

Every RPC, message, field and enum of the service.

Metrics and attributes

Every metric, label, resource attribute and log record attribute.