> ## 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.

# 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](https://filetrace.mintlify.site/integrations/prometheus.md) and in the [OTLP export](https://filetrace.mintlify.site/integrations/opentelemetry.md).

## 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](#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](https://filetrace.mintlify.site/guides/performance.md) 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](https://filetrace.mintlify.site/reference/event-types.md).

## 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](#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.


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