| <!--* |
| # Document freshness: For more information, see go/fresh-source. |
| freshness: { owner: 'tlbmc-dev' reviewed: '2026-06-04' } |
| *--> |
| |
| # tlBMC Collectors Module |
| |
| Collectors in tlBMC are background services responsible for actively discovering |
| hardware components, reading telemetry from physical or virtual devices, and |
| updating the central `Store`. These collectors run periodically or respond to |
| system state transitions to keep the inventory and sensor values up to date. |
| |
| The core implementation files are located in |
| `third_party/milotic/external/cc/tlbmc/collector/`. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Central Configuration |
| |
| Collectors are managed and activated at boot time through the central |
| `TlbmcConfig` (defined in |
| [`central_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/central_config/central_config.proto)). |
| If a collector module is marked `enabled: false`, its background loop will not |
| initialize, and it will not register routes or poll hardware. |
| |
| ### Summary of Collector Configurations |
| |
| | Collector | Configuration Field | Default | Description | |
| : Message : : : : |
| | :---------- | :--------------------------------- | :------ | :------------ | |
| | **FRU | `fru_collector_module` | `false` | Scans and | |
| : Collector** : : : populates : |
| : : : : inventory : |
| : : : : data : |
| : : : : (EEPROMs, : |
| : : : : cables, : |
| : : : : boards) and : |
| : : : : builds the : |
| : : : : parent-child : |
| : : : : chassis : |
| : : : : topology. : |
| | **Sensor | `sensor_collector_module` | `false` | Manages | |
| : Collector** : : : polling loops : |
| : : : : for physical : |
| : : : : (HWMon, PSU, : |
| : : : : ADC) and : |
| : : : : virtual : |
| : : : : sensors. : |
| | **Bulk | N/A (platform factory) | N/A | Manages high- | |
| : Sensor : : : frequency, : |
| : Collector** : : : batched : |
| : : : : telemetry and : |
| : : : : sensor set : |
| : : : : subscriptions : |
| | **Thermal | `thermal_control_sub_module` | `false` | Orchestrates | |
| : Collector** : (under `sensor_collector_module`) : : multi-zone : |
| : : : : thermal : |
| : : : : control : |
| : : : : loops, fan : |
| : : : : PID cooling, : |
| : : : : and Redfish : |
| : : : : thermal/ : |
| : : : : power : |
| : : : : subsystems. : |
| | **Metric | `metric_collector_module` | `true` | Gathers | |
| : Collector** : : : software : |
| : : : : health and : |
| : : : : performance : |
| : : : : telemetry : |
| : : : : (e.g., : |
| : : : : hitless : |
| : : : : metrics, : |
| : : : : PSI). : |
| | **GPIO | `gpio_collector_module` | `false` | Monitors | |
| : Collector** : : : discrete GPIO : |
| : : : : inputs and : |
| : : : : implements : |
| : : : : power control : |
| : : : : signals. : |
| | **Power | `power_fault_log_collector_module` | `false` | Subscribes to | |
| : Fault Log : : : power-good : |
| : Collector** : : : signals and : |
| : : : : records power : |
| : : : : faults. : |
| | **SEL | `sel_collector_module` | `false` | Gathers and | |
| : Collector** : : : records : |
| : : : : System Event : |
| : : : : Log (SEL) : |
| : : : : messages. : |
| | **PCIe | `pcie_collector_module` | `false` | Discovers | |
| : Collector** : : : PCIe slots : |
| : : : : and : |
| : : : : aggregates : |
| : : : : link : |
| : : : : telemetry. : |
| | **LED | `led_collector_module` | `false` | Manages | |
| : Collector** : : : physical LEDs : |
| : : : : (sysfs/GPIO) : |
| : : : : and applies : |
| : : : : LED behavior : |
| : : : : presets. : |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Supported Collectors and Core Tasks |
| |
| ### 1. [FRU Collector](/third_party/milotic/external/cc/tlbmc/g3doc/components/collectors/fru_collector.md) (`fru_collector.cc`) |
| |
| Responsible for physical inventory scanning: |
| |
| - Evaluates Entity Manager JSON probe rules. |
| - Interrogates FRU EEPROMs to extract part numbers, serial numbers, and |
| assets. |
| - Links components together in a topological tree (`TopologyConfigNode`). |
| |
| ### 2. [Sensor Collector](/third_party/milotic/external/cc/tlbmc/g3doc/components/collectors/sensor_collector.md) (`sensor_collector.cc`) |
| |
| Coordinates all telemetry gathering: |
| |
| - Instantiates sensor devices mapped from configurations. |
| - Spawns background worker loops to periodically refresh values. |
| - Performs threshold evaluations and triggers events (if |
| `enable_threshold_monitoring` is active). |
| |
| ### 3. [Bulk Sensor Collector](/third_party/milotic/external/cc/tlbmc/g3doc/components/collectors/bulk_sensor_collector.md) (`bulk_sensor_collector.h`) |
| |
| Coordinates high-frequency batched telemetry collection: |
| |
| - Groups sensors into `SensorSet`s by sampling interval and category. |
| - Offloads subscriptions to hardware drivers via dedicated |
| `MonitoringChangeExecutor` threads. |
| - Stores raw telemetry batches in circular buffers (`BulkStore`) and extracts |
| individual `SensorValue`s on demand via `BulkSensor`. |
| |
| ### 4. [Thermal Collector](/third_party/milotic/external/cc/tlbmc/g3doc/components/collectors/thermal_collector.md) (`thermal_collector.cc`) |
| |
| Coordinates thermal management loops and fan PID controllers: |
| |
| - Orchestrates multi-zone thermal loops via `ZoneManager` and PID/stepwise |
| controllers. |
| - Manages Redfish `ThermalSubsystem` (Fans) and `PowerSubsystem` |
| (PowerSupplies). |
| - Supports runtime tuning of PID control coefficients and manual fan override |
| modes. |
| |
| ### 5. [Metric Collector](/third_party/milotic/external/cc/tlbmc/g3doc/modules/metrics.md) (`metric_collector.cc`) |
| |
| Monitors tlBMC service health: |
| |
| - Polls memory consumption, CPU utilization, thread counts, and DBus messaging |
| latencies. |
| - Reads pressure stall information (PSI) from the kernel. |
| |
| ### 6. [GPIO Collector](/third_party/milotic/external/cc/tlbmc/g3doc/components/collectors/gpio_collector.md) (`gpio_collector.cc`) |
| |
| Polls and monitors hardware pins: |
| |
| - Integrates with the platform's GPIO pins using Linux kernel `gpiod` |
| interfaces. |
| - Implements host power-control submodules. |
| |
| ### 7. [Power Fault Log Collector](/third_party/milotic/external/cc/tlbmc/g3doc/components/collectors/power_fault_log_collector.md) (`power_fault_log_collector.cc`) |
| |
| Subscribes to power-good signals and records power faults: |
| |
| - Monitors fault log directories or GPIO power-good transitions. |
| - Records structured power fault event logs. |
| |
| ### 8. [SEL Collector](/third_party/milotic/external/cc/tlbmc/g3doc/components/collectors/sel_collector.md) (`sel_collector.cc`) |
| |
| Aggregates alerts: |
| |
| - Listens to internal threshold monitors. |
| - Writes structured System Event Logs (SEL) back to the BMC. |
| |
| ### 9. [PCIe Collector](/third_party/milotic/external/cc/tlbmc/g3doc/components/collectors/pcie_collector.md) (`pcie_collector.cc`) |
| |
| Discovers PCIe slots and aggregates link telemetry: |
| |
| - Evaluates slot stable IDs against physical Redfish locations. |
| - Monitors presence via GPIO pins and aggregates link telemetry. |
| |
| ### 10. [LED Collector](/third_party/milotic/external/cc/tlbmc/g3doc/components/collectors/led_collector.md) (`led_collector.cc`) |
| |
| Manages physical LEDs and applies preset behaviors: |
| |
| - Controls hardware LED outputs (sysfs, GPIO) and states (ON, OFF, BLINK). |
| - Applies named LED presets (groupings of LED behaviors) across managed |
| indicators. |
| |
| ## Protobuf Configuration Schemas |
| |
| The collectors run background tasks that map hardware state to local memory |
| buffers. They parse and write to the following protobuf schemas: |
| |
| - **`FruTable`** / **`Fru`** (defined in |
| [`fru.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/fru.proto)): |
| Stores physical inventory assets (EEPROM fields). |
| - **`Processor`** (defined in |
| [`processor.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/processor.proto)): |
| Maps CPU inventory attributes (cores, threads, architecture). |
| - **`Memory`** (defined in |
| [`memory.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/memory.proto)): |
| Maps DIMM memory module sizing and vendor info. |
| - **`ResourceStatus`** (defined in |
| [`status.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/status.proto)): |
| State management values (enabled, absent, error states). |
| - **`SensorTable`** / **`Sensor`** (defined in |
| [`sensor.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/sensor.proto)): |
| Schema representing sensor channels and dynamic measurements. |
| - **`SoftwareMetrics`** (defined in |
| [`software_metrics.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/software_metrics.proto)): |
| Schema representing daemon sockets and netfilter stats. |
| - **`PowerFaultLogEntry`** (defined in |
| [`power_fault_log_entry.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/power_fault_log_entry.proto)): |
| Defines the event parameters logged on power failures. |
| - **`SseEvent`** (defined in |
| [`sse_event.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/sse_event.proto)): |
| SSE frame layout for satellite controller alerts. |
| - **`ThermalConfig`** (defined in |
| [`thermal_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/thermal_config.proto)): |
| Defines multi-zone thermal PID coefficients and fan stepwise management |
| rules. |
| - **`LedConfig`** / **`LedPreset`** (defined in |
| [`led_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/led_config.proto)): |
| Defines LED hardware output interfaces (sysfs/GPIO), default behaviors, and |
| named preset mappings. |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Configuration Example (`tlbmc_config_bundle.textproto`) |
| |
| Shows how platform integrators enable the FRU, Sensor, and Gpio collectors on a |
| platform: |
| |
| ```protobuf |
| general_config { |
| platform_name: "default" |
| fru_collector_module { |
| enabled: true |
| own_chassis_in_redfish: true |
| } |
| sensor_collector_module { |
| enabled: true |
| enable_threshold_monitoring: true |
| } |
| gpio_collector_module { |
| enabled: true |
| power_control_sub_module { |
| enabled: true |
| power_control_type: POWER_CONTROL_TYPE_GPIO |
| } |
| } |
| sel_collector_module { |
| enabled: true |
| } |
| led_collector_module { |
| enabled: true |
| } |
| } |
| ``` |
| |
| -------------------------------------------------------------------------------- |
| |
| ## Code References |
| |
| ### Config & Inventory Protos |
| |
| - [`central_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/central_config/central_config.proto) |
| - [`fru.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/fru.proto) |
| - [`processor.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/processor.proto) |
| - [`memory.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/memory.proto) |
| - [`status.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/status.proto) |
| - [`sensor.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/sensor.proto) |
| - [`software_metrics.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/software_metrics.proto) |
| - [`power_fault_log_entry.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/power_fault_log_entry.proto) |
| - [`sse_event.proto`](http://google3/third_party/milotic/external/cc/tlbmc/resource/sse_event.proto) |
| - [`thermal_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/thermal_config.proto) |
| - [`led_config.proto`](http://google3/third_party/milotic/external/cc/tlbmc/configs/led_config.proto) |
| |
| ### Core Code |
| |
| - [`fru_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/fru_collector.h) |
| - [`sensor_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/sensor_collector.h) |
| - [`bulk_sensor_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/bulk_sensor_collector.h) |
| - [`bulk_sensor_collector_base.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/bulk_sensor_collector_base.h) |
| - [`metric_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/metric_collector.h) |
| - [`gpio_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/gpio_collector.h) |
| - [`power_fault_log_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/power_fault_log_collector.h) |
| - [`sel_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/sel_collector.h) |
| - [`pcie_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/pcie_collector.h) |
| - [`thermal_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/thermal_collector.h) |
| - [`led_collector.h`](http://google3/third_party/milotic/external/cc/tlbmc/collector/led_collector.h) |
