> ## Documentation Index
> Fetch the complete documentation index at: https://filetrace.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://filetrace.mintlify.site/integrations/prometheus.md) | Metrics, on `http://127.0.0.1:9464/metrics` | `[prometheus] enabled = true` | Listens on `127.0.0.1:9464` |
| [OTLP over gRPC](https://filetrace.mintlify.site/integrations/opentelemetry.md) | Events as log records, and the same metrics | `[otlp] enabled = true` | Sends to `127.0.0.1:4317` |
| [gRPC API](https://filetrace.mintlify.site/integrations/grpc-api.md) | 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:

```toml theme={null}
[prometheus]
enabled = true

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

[grpc]
enabled = true
```

```bash theme={null}
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](https://filetrace.mintlify.site/guides/run-as-a-service.md). `filetrace config show` prints every setting of the three sections with the value in effect; the [configuration reference](https://filetrace.mintlify.site/reference/configuration.md) lists them all.

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

> [!NOTE]
>
> 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](https://filetrace.mintlify.site/reference/exit-codes.md).

## 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](https://filetrace.mintlify.site/integrations/telemetry-reference.md) 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](https://filetrace.mintlify.site/reference/security.md) 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

> [card] [Prometheus](https://filetrace.mintlify.site/integrations/prometheus.md)
>
> Enable the metrics page, scrape it, and query it with PromQL.

> [card] [OpenTelemetry (OTLP)](https://filetrace.mintlify.site/integrations/opentelemetry.md)
>
> Send events and metrics to an OpenTelemetry Collector.

> [card] [gRPC API guide](https://filetrace.mintlify.site/integrations/grpc-api.md)
>
> List and stream transfers with grpcurl, buf curl or a generated client.

> [card] [gRPC API reference](https://filetrace.mintlify.site/integrations/grpc-reference.md)
>
> Every RPC, message, field and enum of the service.

> [card] [Metrics and attributes](https://filetrace.mintlify.site/integrations/telemetry-reference.md)
>
> Every metric, label, resource attribute and log record attribute.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.