tlbmc/g3doc/onboarding_npis/metric_collector_module.md

# Onboarding NPIs to Metric Collector Module

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

This document describes how to enable and configure the tlBMC Metric Collector
Module for an NPI. This module collects software-defined metrics such as
socket statistics and netfilter connection statistics.

[TOC]

## Prerequisites

The tlBMC Metric Collector Module must be enabled for your platform in
`tlbmc_config_bundle.textproto`. If it is not enabled, tlBMC will not collect
metrics.
See `tlbmc_config_bundle.textproto` in tlbmc source.

To enable the module, add `metric_collector_module { enabled: true }` to your
platform's configuration in `platform_to_config` map. For example:

```textproto
platform_to_config {
  key: "your_platform_name"
  value {
    metric_collector_module {
      enabled: true
    }
  }
}
```

## Metric Configuration

The Metric Collector Module requires a configuration file named
`software_metrics_config.textproto` to specify which metrics to collect. This
file should be placed in your platform's configuration directory, typically
[here](https://gbmc-private.googlesource.com/meta-google-private/+/refs/heads/master/recipes-google/tlbmc/files/software_metrics_config.textproto).

The `software_metrics_config.textproto` file should contain a
`SoftwareMetricsConfig` message, as defined in
`software_metrics_config.proto`.

The `SoftwareMetricsConfig` message allows you to specify ports for socket
statistics and netfilter statistics:

*   `socket_stat_ports`: A list of TCP ports for which to collect socket
    statistics (e.g., number of connections in various TCP states).
*   `netfilter_ports`: A list of TCP ports for which to collect netfilter
    connection tracking statistics.

### Example Configuration

Here is an example of `software_metrics_config.textproto` that configures
collection for SSH (port 22) and HTTPS (port 443):

```textproto
# proto-file: third_party/milotic/external/cc/tlbmc/configs/software_metrics_config.proto
# proto-message: SoftwareMetricsConfig

socket_stat_ports: 22
socket_stat_ports: 443
netfilter_ports: 22
netfilter_ports: 443
```

## Collected Metrics

When enabled and configured, the module collects metrics at a default interval
of 30 seconds. The collected metrics can be accessed via tlBMC's Redfish
interface at
`/redfish/v1/Managers/bmc/ManagerDiagnosticData/Oem/Google/BmcSocketMetrics/`,
and
`/redfish/v1/Managers/bmc/ManagerDiagnosticData/Oem/Google/BmcNfMetrics/`.

### Example Output

Example output of
`/redfish/v1/Managers/bmc/ManagerDiagnosticData/Oem/Google/BmcSocketMetrics/`
```json
{
  "Port": {
    "443": {
      "CLOSED": 0,
      "CLOSE_WAIT": 0,
      "CLOSING": 0,
      "ESTABLISHED": 1,
      "FIN_WAIT_ONE": 0,
      "FIN_WAIT_TWO": 0,
      "LAST_ACK": 0,
      "LISTENING": 0,
      "SYN_RECEIVED": 0,
      "SYN_SENT": 0,
      "TIME_WAIT": 0
    }
  },
  "Timestamp": 1700000000
}
```

Example output of
`/redfish/v1/Managers/bmc/ManagerDiagnosticData/Oem/Google/BmcNfMetrics/`
```json
{
  "Port": {
    "443": {
      "Connections": 12345
    }
  },
  "Timestamp": 1700000000
}
```