tlbmc/g3doc/modules/metrics.md

<!--*
# Document freshness: For more information, see go/fresh-source.
freshness: { owner: 'tlbmc-dev' reviewed: '2026-08-17' }
*-->

# tlBMC Metrics Module

The Metrics Module in tlBMC is responsible for collecting dynamic system-level
and daemon-specific telemetry (CPU/Memory utilization, socket counts, firewall
stats, and systemd service stall states) and exporting them to Redfish or other
monitoring interfaces.

The core implementation resides in the
`third_party/milotic/external/cc/tlbmc/metrics/` directory.

--------------------------------------------------------------------------------

## Central Configuration

The metrics collection loop is configured via `TlbmcConfig` (defined in
[`central_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/central_config/central_config.proto)).

### 1. Metric Collector Module (`MetricCollectorModule`)

Controls the metrics service loops.

| Field                          | Type   | Default | Description              |
| :----------------------------- | :----- | :------ | :----------------------- |
| `enabled`                      | `bool` | `true`  | Enables the metrics      |
:                                :        :         : background tasks.        :
| `collect_true_hitless_metrics` | `bool` | `true`  | Enables parsing and      |
:                                :        :         : exposing true hitless    :
:                                :        :         : update metrics.          :
| `enable_psi_metrics`           | `bool` | `false` | Enables reading          |
:                                :        :         : CPU/Memory Pressure      :
:                                :        :         : Stall Information (PSI). :
| `enable_bios_key_metrics`      | `bool` | `false` | Controls the BIOS Key    |
:                                :        :         : metrics collector        :
:                                :        :         : module.                  :

### 2. Software Metrics Configuration (`SoftwareMetricsConfig`)

Exposes detailed options for TCP socket and firewall rule monitoring (defined in
[`software_metrics_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/software_metrics_config.proto)).

| Field                                      | Type      | Description     |
| :----------------------------------------- | :-------- | :-------------- |
| `socket_stat_ports`                        | `repeated | TCP port        |
:                                            : int32`    : numbers to      :
:                                            :           : monitor socket  :
:                                            :           : states (e.g.    :
:                                            :           : `LISTEN`,       :
:                                            :           : `ESTABLISHED`). :
| `netfilter_ports`                          | `repeated | Port numbers to |
:                                            : int32`    : parse netfilter :
:                                            :           : SYN-ACK counts. :
| `true_hitless_metrics_refresh_interval_ms` | `int32`   | Polling         |
:                                            :           : interval for    :
:                                            :           : hitless         :
:                                            :           : updates.        :
| `true_hitless_metrics_path`                | `string`  | File path       |
:                                            :           : containing true :
:                                            :           : hitless state   :
:                                            :           : JSON (parsed by :
:                                            :           : parser).        :

--------------------------------------------------------------------------------

## Metric Categories

### 1. BMC Static Metrics (`bmc_static_metrics.cc`)

Information gathered at boot and exposed as static attributes:

-   **Firmware Version**: Read from `VERSION_ID` in `/etc/os-release`.
-   **Flash ID**: Extracted from mount directory names under
    `/run/media/rofs-<flash-id>`.
-   **Machine UUID**: Read using standard machine app IDs.

### 2. Socket Statistics (`software_metrics.cc`)

Exposes TCP socket states (LISTEN, ESTABLISHED, SYN-SENT, SYN-RECV, FIN-WAIT,
etc.) for designated ports.

-   **Mechanism**: Executes `ss -t -a -n` and parses state counts.

### 3. Netfilter Connection Counts (`software_metrics.cc`)

Extracts packet and byte counters from `nftables` chains.

-   **Mechanism**: Executes `nft -j list ruleset` and searches for counter rules
    matching the comment `tcp-server-<port>-synack` for the configured netfilter
    ports.

### 4. Pressure Stall Information (PSI)

Enables tracking of operating system resource saturation:

-   **System-wide PSI**: Reads `/sys/fs/cgroup/cpu.pressure`,
    `/sys/fs/cgroup/memory.pressure`, and `/sys/fs/cgroup/io.pressure`.
-   **Per-Service PSI**: Reads individual systemd service slice stats under
    `/sys/fs/cgroup/system.slice/{service_name}/cpu.pressure` (and memory/io
    pressure).

## Protobuf Configuration Schemas

The metrics collector service registers periodic tasks to check OS limits and
updates the store using the following protobuf models:

-   **`SoftwareMetricsConfig`** (defined in
    [`software_metrics_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/software_metrics_config.proto)):
    Configures TCP socket monitoring ports, firewall log check ports, and
    hitless update refresh schedules.
-   **`SoftwareMetrics`** (defined in
    [`software_metrics.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/software_metrics.proto)):
    Schema representing system socket counts, netfilter stats, and CPU/Memory
    pressure stalls.
-   **`TrueHitlessMetrics`** (defined in
    [`true_hitless_metrics.proto`](http://google3/third_party/milotic/external/cc/true_hitless/true_hitless_metrics.proto)):
    Schema representing active hitless update statuses.

--------------------------------------------------------------------------------

## Configuration Example (`tlbmc_config_bundle.textproto`)

Shows how platform integrators customize the metrics collection loops to monitor
specific ports:

```protobuf
general_config {
  metric_collector_module {
    enabled: true
    collect_true_hitless_metrics: true
    enable_psi_metrics: true
  }
}

platform_to_config {
  key: "platform_name"
  value {
    metric_collector_module {
      enabled: true
    }
    # Platform-specific software metrics overrides
    # e.g., monitoring SSH (22) and Redfish (443) socket states
    # and tracking hitless metrics path
    # (These fields are mapped inside software_metrics_config)
  }
}
```

--------------------------------------------------------------------------------

## Code References

### Config & Telemetry Protos

-   [`central_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/central_config/central_config.proto)
-   [`software_metrics_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/software_metrics_config.proto)
-   [`software_metrics.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/software_metrics.proto)
-   [`true_hitless_metrics.proto`](http://google3/third_party/milotic/external/cc/true_hitless/true_hitless_metrics.proto)

### Core Code

-   [`bmc_static_metrics.h`](http://google3/third_party/milotic/external/cc/tlbmc/metrics/bmc_static_metrics.h)
-   [`software_metrics.h`](http://google3/third_party/milotic/external/cc/tlbmc/metrics/software_metrics.h)
-   [`software_metrics.cc`](http://google3/third_party/milotic/external/cc/tlbmc/metrics/software_metrics.cc)