You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@skywalking.apache.org by "hanahmily (via GitHub)" <gi...@apache.org> on 2025/12/11 06:46:13 UTC
[PR] Add design documentation for KTM [skywalking-banyandb]
hanahmily opened a new pull request, #894:
URL: https://github.com/apache/skywalking-banyandb/pull/894
- [x] Update the [`CHANGES` log](https://github.com/apache/skywalking-banyandb/blob/main/CHANGES.md).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add design documentation for KTM [skywalking-banyandb]
Posted by "hanahmily (via GitHub)" <gi...@apache.org>.
hanahmily commented on PR #894:
URL: https://github.com/apache/skywalking-banyandb/pull/894#issuecomment-3648617531
> *
> * How does the KTM module identify BanyanDB nodes in the pod or VM?
Please include any relevant content.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add design documentation for KTM [skywalking-banyandb]
Posted by "wu-sheng (via GitHub)" <gi...@apache.org>.
wu-sheng commented on PR #894:
URL: https://github.com/apache/skywalking-banyandb/pull/894#issuecomment-3650781342
Could you fix the term as Copilot mentioned?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add design documentation for KTM [skywalking-banyandb]
Posted by "wu-sheng (via GitHub)" <gi...@apache.org>.
wu-sheng merged PR #894:
URL: https://github.com/apache/skywalking-banyandb/pull/894
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add design documentation for KTM [skywalking-banyandb]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #894:
URL: https://github.com/apache/skywalking-banyandb/pull/894#discussion_r2615917662
##########
docs/design/ktm.md:
##########
@@ -0,0 +1,193 @@
+
+# Kernel Telemetry Module (KTM)
+
+## Overview
+
+Kernel Telemetry Module (KTM) is an optional, modular kernel observability component embedded inside the BanyanDB First Occurrence Data Collection (FODC) sidecar. The first built-in module is an eBPF-based I/O monitor ("iomonitor") that focuses on page cache behavior, fadvise() effectiveness, and memory pressure signals and their impact on BanyanDB performance. KTM is not a standalone agent or network-facing service; it runs as a sub-component of the FODC sidecar ("black box") and exposes a Go-native interface to the FlightRecorder for ingesting metrics. Collection scoping is configurable and defaults to cgroup v2.
Review Comment:
Inconsistent terminology: "FlightRecorder" should be "Flight Recorder" when used in narrative text. The existing FODC documentation uses "Flight Recorder" (two words) as the proper noun for the component. The single-word "FlightRecorder" should only be used when referring to the Go type/struct name in code contexts.
##########
docs/design/ktm.md:
##########
@@ -0,0 +1,193 @@
+
+# Kernel Telemetry Module (KTM)
+
+## Overview
+
+Kernel Telemetry Module (KTM) is an optional, modular kernel observability component embedded inside the BanyanDB First Occurrence Data Collection (FODC) sidecar. The first built-in module is an eBPF-based I/O monitor ("iomonitor") that focuses on page cache behavior, fadvise() effectiveness, and memory pressure signals and their impact on BanyanDB performance. KTM is not a standalone agent or network-facing service; it runs as a sub-component of the FODC sidecar ("black box") and exposes a Go-native interface to the FlightRecorder for ingesting metrics. Collection scoping is configurable and defaults to cgroup v2.
+
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ User Applications │
+│ ┌──────────────┐ │
+│ │ BanyanDB │ │
+│ └──────┬───────┘ │
+└─────────┼───────────────────────────────────────────────┘
+ │ Shared Pod / Node
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ FODC Sidecar ("Black Box" Agent) │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ Watchdog / FlightRecorder / KTM (iomonitor) │ │
+│ │ - KTM eBPF Loader & Manager │ │
+│ │ - KTM Collector (Module Management) │ │
+│ │ - FlightRecorder (in-memory diagnostics store) │ │
Review Comment:
Inconsistent terminology: "FlightRecorder" should be "Flight Recorder" when used in narrative text to match the existing FODC documentation conventions.
##########
docs/design/ktm.md:
##########
@@ -0,0 +1,193 @@
+
+# Kernel Telemetry Module (KTM)
+
+## Overview
+
+Kernel Telemetry Module (KTM) is an optional, modular kernel observability component embedded inside the BanyanDB First Occurrence Data Collection (FODC) sidecar. The first built-in module is an eBPF-based I/O monitor ("iomonitor") that focuses on page cache behavior, fadvise() effectiveness, and memory pressure signals and their impact on BanyanDB performance. KTM is not a standalone agent or network-facing service; it runs as a sub-component of the FODC sidecar ("black box") and exposes a Go-native interface to the FlightRecorder for ingesting metrics. Collection scoping is configurable and defaults to cgroup v2.
+
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ User Applications │
+│ ┌──────────────┐ │
+│ │ BanyanDB │ │
+│ └──────┬───────┘ │
+└─────────┼───────────────────────────────────────────────┘
+ │ Shared Pod / Node
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ FODC Sidecar ("Black Box" Agent) │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ Watchdog / FlightRecorder / KTM (iomonitor) │ │
+│ │ - KTM eBPF Loader & Manager │ │
+│ │ - KTM Collector (Module Management) │ │
+│ │ - FlightRecorder (in-memory diagnostics store) │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ Linux Kernel │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ eBPF Programs │ │
+│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
+│ │ │ I/O │ │ Cache │ │ Memory │ │ │
+│ │ │ Monitor │ │ Monitor │ │ Reclaim │ │ │
+│ │ └──────────┘ └──────────┘ └──────────┘ │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+Notes:
+- KTM is modular; the initial module is `iomonitor`.
+
+
+## Modules
+
+### I/O Monitor (iomonitor)
+- Focus: page cache add/delete, fadvise() calls, I/O counters, and memory reclaim signals.
+- Attachment points: stable tracepoints where possible; fentry/fexit preferred on newer kernels.
+- Data path: kernel events -> BPF maps (monotonic counters) -> userspace collector -> exporters.
+- Scoping: Fixed to the single, co-located BanyanDB process within the same container/pod.
+
+
+## Metrics Model and Collection Strategy
+
+- Counters in BPF maps are monotonic and are not cleared by the userspace collector (NoCleanup).
+- Collection and push interval: 10 seconds by default.
+- KTM periodically pushes collected metrics into the FODC FlightRecorder through a Go-native interface at the configured interval (default 10s). The push interval is exported through the `collector.interval` configuration option. The FlightRecorder is responsible for any subsequent export, persistence, or diagnostics workflows.
+- Downstream systems (for example, FODC Discovery Proxy or higher-level exporters) should derive rates using `rate()`/`irate()` or equivalents; we avoid windowed counters and map resets to preserve counter semantics.
+- int64 overflow is not a practical concern for our use cases; we accept long-lived monotonic growth.
+
+Configuration surface (current):
+- `collector.interval`: Controls the periodic push interval for metrics to FlightRecorder. Defaults to 10s.
Review Comment:
Inconsistent terminology: "FlightRecorder" should be "Flight Recorder" when used in narrative text to match the existing FODC documentation conventions.
##########
docs/design/ktm.md:
##########
@@ -0,0 +1,193 @@
+
+# Kernel Telemetry Module (KTM)
+
+## Overview
+
+Kernel Telemetry Module (KTM) is an optional, modular kernel observability component embedded inside the BanyanDB First Occurrence Data Collection (FODC) sidecar. The first built-in module is an eBPF-based I/O monitor ("iomonitor") that focuses on page cache behavior, fadvise() effectiveness, and memory pressure signals and their impact on BanyanDB performance. KTM is not a standalone agent or network-facing service; it runs as a sub-component of the FODC sidecar ("black box") and exposes a Go-native interface to the FlightRecorder for ingesting metrics. Collection scoping is configurable and defaults to cgroup v2.
+
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ User Applications │
+│ ┌──────────────┐ │
+│ │ BanyanDB │ │
+│ └──────┬───────┘ │
+└─────────┼───────────────────────────────────────────────┘
+ │ Shared Pod / Node
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ FODC Sidecar ("Black Box" Agent) │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ Watchdog / FlightRecorder / KTM (iomonitor) │ │
+│ │ - KTM eBPF Loader & Manager │ │
+│ │ - KTM Collector (Module Management) │ │
+│ │ - FlightRecorder (in-memory diagnostics store) │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ Linux Kernel │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ eBPF Programs │ │
+│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
+│ │ │ I/O │ │ Cache │ │ Memory │ │ │
+│ │ │ Monitor │ │ Monitor │ │ Reclaim │ │ │
+│ │ └──────────┘ └──────────┘ └──────────┘ │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+Notes:
+- KTM is modular; the initial module is `iomonitor`.
+
+
+## Modules
+
+### I/O Monitor (iomonitor)
+- Focus: page cache add/delete, fadvise() calls, I/O counters, and memory reclaim signals.
+- Attachment points: stable tracepoints where possible; fentry/fexit preferred on newer kernels.
+- Data path: kernel events -> BPF maps (monotonic counters) -> userspace collector -> exporters.
+- Scoping: Fixed to the single, co-located BanyanDB process within the same container/pod.
+
+
+## Metrics Model and Collection Strategy
+
+- Counters in BPF maps are monotonic and are not cleared by the userspace collector (NoCleanup).
+- Collection and push interval: 10 seconds by default.
+- KTM periodically pushes collected metrics into the FODC FlightRecorder through a Go-native interface at the configured interval (default 10s). The push interval is exported through the `collector.interval` configuration option. The FlightRecorder is responsible for any subsequent export, persistence, or diagnostics workflows.
Review Comment:
Inconsistent terminology: "FlightRecorder" should be "Flight Recorder" when used in narrative text to match the existing FODC documentation conventions.
```suggestion
- KTM periodically pushes collected metrics into the FODC Flight Recorder through a Go-native interface at the configured interval (default 10s). The push interval is exported through the `collector.interval` configuration option. The Flight Recorder is responsible for any subsequent export, persistence, or diagnostics workflows.
```
##########
docs/design/ktm.md:
##########
@@ -0,0 +1,193 @@
+
+# Kernel Telemetry Module (KTM)
+
+## Overview
+
+Kernel Telemetry Module (KTM) is an optional, modular kernel observability component embedded inside the BanyanDB First Occurrence Data Collection (FODC) sidecar. The first built-in module is an eBPF-based I/O monitor ("iomonitor") that focuses on page cache behavior, fadvise() effectiveness, and memory pressure signals and their impact on BanyanDB performance. KTM is not a standalone agent or network-facing service; it runs as a sub-component of the FODC sidecar ("black box") and exposes a Go-native interface to the FlightRecorder for ingesting metrics. Collection scoping is configurable and defaults to cgroup v2.
+
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ User Applications │
+│ ┌──────────────┐ │
+│ │ BanyanDB │ │
+│ └──────┬───────┘ │
+└─────────┼───────────────────────────────────────────────┘
+ │ Shared Pod / Node
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ FODC Sidecar ("Black Box" Agent) │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ Watchdog / FlightRecorder / KTM (iomonitor) │ │
+│ │ - KTM eBPF Loader & Manager │ │
+│ │ - KTM Collector (Module Management) │ │
+│ │ - FlightRecorder (in-memory diagnostics store) │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ Linux Kernel │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ eBPF Programs │ │
+│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
+│ │ │ I/O │ │ Cache │ │ Memory │ │ │
+│ │ │ Monitor │ │ Monitor │ │ Reclaim │ │ │
+│ │ └──────────┘ └──────────┘ └──────────┘ │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+Notes:
+- KTM is modular; the initial module is `iomonitor`.
+
+
+## Modules
+
+### I/O Monitor (iomonitor)
+- Focus: page cache add/delete, fadvise() calls, I/O counters, and memory reclaim signals.
+- Attachment points: stable tracepoints where possible; fentry/fexit preferred on newer kernels.
+- Data path: kernel events -> BPF maps (monotonic counters) -> userspace collector -> exporters.
+- Scoping: Fixed to the single, co-located BanyanDB process within the same container/pod.
+
+
+## Metrics Model and Collection Strategy
+
+- Counters in BPF maps are monotonic and are not cleared by the userspace collector (NoCleanup).
+- Collection and push interval: 10 seconds by default.
+- KTM periodically pushes collected metrics into the FODC FlightRecorder through a Go-native interface at the configured interval (default 10s). The push interval is exported through the `collector.interval` configuration option. The FlightRecorder is responsible for any subsequent export, persistence, or diagnostics workflows.
+- Downstream systems (for example, FODC Discovery Proxy or higher-level exporters) should derive rates using `rate()`/`irate()` or equivalents; we avoid windowed counters and map resets to preserve counter semantics.
+- int64 overflow is not a practical concern for our use cases; we accept long-lived monotonic growth.
+
+Configuration surface (current):
+- `collector.interval`: Controls the periodic push interval for metrics to FlightRecorder. Defaults to 10s.
+- `collector.enable_cgroup_filter`, `collector.enable_mntns_filter`: default on when in sidecar mode; can be toggled.
+- `collector.target_pid`/`collector.target_comm`: optional helpers for discovering scoping targets.
+- `collector.target_comm_regex`: process matcher regular expression used during target discovery (matches `/proc/<pid>/comm` and/or executable basename). Defaults to `banyand`.
+- Cleanup strategy is effectively `no_cleanup` by design intent; clear-after-read logic is deprecated for production metrics.
+- Configuration is applied via the FODC sidecar; KTM does not define its own standalone process-level configuration surface.
+
+
+## Scoping and Filtering
+
+- Scoping is not optional; KTM is designed exclusively to monitor the single BanyanDB process it is co-located with in a sidecar deployment.
+- The target process is identified at startup, and eBPF programs are instructed to filter events to only that process.
+- Primary filtering mechanism: cgroup v2. This ensures all events originate from the correct container. PID and mount namespace filters are used as supplementary checks.
+- The design intentionally avoids multi-process or node-level (DaemonSet) monitoring to keep the implementation simple and overhead minimal.
+
+### Target Process Discovery (Pod / VM)
+
+KTM needs to resolve the single “target” BanyanDB process before enabling filters and attaching eBPF programs. In both Kubernetes pods and VM/bare-metal deployments, KTM uses a **process matcher** driven by a configurable regular expression (`collector.target_comm_regex`, default `banyand`).
+
+#### Kubernetes Pod (sidecar)
+
+Preconditions:
+- The pod should be configured with `shareProcessNamespace: true` so the monitor sidecar can see the target container’s `/proc` entries.
+- The monitor container should have cgroup v2 mounted (typically at `/sys/fs/cgroup`).
+
+Discovery flow (high level):
+- Scan `/proc` for candidate processes.
+- For each PID, read `/proc/<pid>/comm` (and/or the executable basename) and match it against `collector.target_comm_regex`.
+- Once matched, read `/proc/<pid>/cgroup` to obtain the target’s cgroup path/identity, then enable cgroup filtering so only events from that container/process are counted.
+
+#### VM / bare metal
+
+Discovery flow (high level):
+- Scan `/proc` for candidate processes.
+- Match `/proc/<pid>/comm` (and/or executable basename) against `collector.target_comm_regex` (default `banyand`).
+- Use PID (and optionally cgroup/mount namespace filters if available) to scope kernel events to the selected process.
+
+### Scoping Semantics
+
+- The BPF maps use a single-slot structure (e.g., a BPF array map with a single entry) to store global monotonic counters for the target process.
+- This approach eliminates the need for per-pid hash maps, key eviction logic, and complexities related to tracking multiple processes.
+- All kernel events are filtered by the target process's identity (via its cgroup ID and PID) before any counters are updated in the BPF map.
+
+Example (YAML):
+```yaml
+collector:
+ interval: 10s
+ modules:
+ - iomonitor
+ enable_cgroup_filter: true
+ enable_mntns_filter: true
+```
+
+
+## API Surface
+
+KTM does not expose a dedicated HTTP or gRPC API. Instead, it provides an internal Go-native interface that is consumed by the FODC sidecar:
+
+- Go-native interfaces (implemented):
+ - Register and manage KTM modules (such as `iomonitor`).
+ - Configure collectors and scoping behavior.
+ - Periodically read monotonic counters from BPF maps and push the results into the FlightRecorder at the configured interval (default 10s).
Review Comment:
Inconsistent terminology: "FlightRecorder" should be "Flight Recorder" when used in narrative text to match the existing FODC documentation conventions.
##########
docs/design/ktm.md:
##########
@@ -0,0 +1,193 @@
+
+# Kernel Telemetry Module (KTM)
+
+## Overview
+
+Kernel Telemetry Module (KTM) is an optional, modular kernel observability component embedded inside the BanyanDB First Occurrence Data Collection (FODC) sidecar. The first built-in module is an eBPF-based I/O monitor ("iomonitor") that focuses on page cache behavior, fadvise() effectiveness, and memory pressure signals and their impact on BanyanDB performance. KTM is not a standalone agent or network-facing service; it runs as a sub-component of the FODC sidecar ("black box") and exposes a Go-native interface to the FlightRecorder for ingesting metrics. Collection scoping is configurable and defaults to cgroup v2.
+
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ User Applications │
+│ ┌──────────────┐ │
+│ │ BanyanDB │ │
+│ └──────┬───────┘ │
+└─────────┼───────────────────────────────────────────────┘
+ │ Shared Pod / Node
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ FODC Sidecar ("Black Box" Agent) │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ Watchdog / FlightRecorder / KTM (iomonitor) │ │
+│ │ - KTM eBPF Loader & Manager │ │
+│ │ - KTM Collector (Module Management) │ │
+│ │ - FlightRecorder (in-memory diagnostics store) │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+ │
+ ▼
+┌─────────────────────────────────────────────────────────┐
+│ Linux Kernel │
+│ ┌────────────────────────────────────────────────────┐ │
+│ │ eBPF Programs │ │
+│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │
+│ │ │ I/O │ │ Cache │ │ Memory │ │ │
+│ │ │ Monitor │ │ Monitor │ │ Reclaim │ │ │
+│ │ └──────────┘ └──────────┘ └──────────┘ │ │
+│ └────────────────────────────────────────────────────┘ │
+└─────────────────────────────────────────────────────────┘
+```
+
+Notes:
+- KTM is modular; the initial module is `iomonitor`.
+
+
+## Modules
+
+### I/O Monitor (iomonitor)
+- Focus: page cache add/delete, fadvise() calls, I/O counters, and memory reclaim signals.
+- Attachment points: stable tracepoints where possible; fentry/fexit preferred on newer kernels.
+- Data path: kernel events -> BPF maps (monotonic counters) -> userspace collector -> exporters.
+- Scoping: Fixed to the single, co-located BanyanDB process within the same container/pod.
+
+
+## Metrics Model and Collection Strategy
+
+- Counters in BPF maps are monotonic and are not cleared by the userspace collector (NoCleanup).
+- Collection and push interval: 10 seconds by default.
+- KTM periodically pushes collected metrics into the FODC FlightRecorder through a Go-native interface at the configured interval (default 10s). The push interval is exported through the `collector.interval` configuration option. The FlightRecorder is responsible for any subsequent export, persistence, or diagnostics workflows.
+- Downstream systems (for example, FODC Discovery Proxy or higher-level exporters) should derive rates using `rate()`/`irate()` or equivalents; we avoid windowed counters and map resets to preserve counter semantics.
+- int64 overflow is not a practical concern for our use cases; we accept long-lived monotonic growth.
+
+Configuration surface (current):
+- `collector.interval`: Controls the periodic push interval for metrics to FlightRecorder. Defaults to 10s.
+- `collector.enable_cgroup_filter`, `collector.enable_mntns_filter`: default on when in sidecar mode; can be toggled.
+- `collector.target_pid`/`collector.target_comm`: optional helpers for discovering scoping targets.
+- `collector.target_comm_regex`: process matcher regular expression used during target discovery (matches `/proc/<pid>/comm` and/or executable basename). Defaults to `banyand`.
+- Cleanup strategy is effectively `no_cleanup` by design intent; clear-after-read logic is deprecated for production metrics.
+- Configuration is applied via the FODC sidecar; KTM does not define its own standalone process-level configuration surface.
+
+
+## Scoping and Filtering
+
+- Scoping is not optional; KTM is designed exclusively to monitor the single BanyanDB process it is co-located with in a sidecar deployment.
+- The target process is identified at startup, and eBPF programs are instructed to filter events to only that process.
+- Primary filtering mechanism: cgroup v2. This ensures all events originate from the correct container. PID and mount namespace filters are used as supplementary checks.
+- The design intentionally avoids multi-process or node-level (DaemonSet) monitoring to keep the implementation simple and overhead minimal.
+
+### Target Process Discovery (Pod / VM)
+
+KTM needs to resolve the single “target” BanyanDB process before enabling filters and attaching eBPF programs. In both Kubernetes pods and VM/bare-metal deployments, KTM uses a **process matcher** driven by a configurable regular expression (`collector.target_comm_regex`, default `banyand`).
+
+#### Kubernetes Pod (sidecar)
+
+Preconditions:
+- The pod should be configured with `shareProcessNamespace: true` so the monitor sidecar can see the target container’s `/proc` entries.
+- The monitor container should have cgroup v2 mounted (typically at `/sys/fs/cgroup`).
+
+Discovery flow (high level):
+- Scan `/proc` for candidate processes.
+- For each PID, read `/proc/<pid>/comm` (and/or the executable basename) and match it against `collector.target_comm_regex`.
+- Once matched, read `/proc/<pid>/cgroup` to obtain the target’s cgroup path/identity, then enable cgroup filtering so only events from that container/process are counted.
+
+#### VM / bare metal
+
+Discovery flow (high level):
+- Scan `/proc` for candidate processes.
+- Match `/proc/<pid>/comm` (and/or executable basename) against `collector.target_comm_regex` (default `banyand`).
+- Use PID (and optionally cgroup/mount namespace filters if available) to scope kernel events to the selected process.
+
+### Scoping Semantics
+
+- The BPF maps use a single-slot structure (e.g., a BPF array map with a single entry) to store global monotonic counters for the target process.
+- This approach eliminates the need for per-pid hash maps, key eviction logic, and complexities related to tracking multiple processes.
+- All kernel events are filtered by the target process's identity (via its cgroup ID and PID) before any counters are updated in the BPF map.
+
+Example (YAML):
+```yaml
+collector:
+ interval: 10s
+ modules:
+ - iomonitor
+ enable_cgroup_filter: true
+ enable_mntns_filter: true
+```
+
+
+## API Surface
+
+KTM does not expose a dedicated HTTP or gRPC API. Instead, it provides an internal Go-native interface that is consumed by the FODC sidecar:
+
+- Go-native interfaces (implemented):
+ - Register and manage KTM modules (such as `iomonitor`).
+ - Configure collectors and scoping behavior.
+ - Periodically read monotonic counters from BPF maps and push the results into the FlightRecorder at the configured interval (default 10s).
+
+Any external APIs (HTTP or gRPC) that expose KTM-derived metrics are part of the broader FODC system (for example, Discovery Proxy or other FODC components) and are documented separately. KTM itself is not responsible for serving `/metrics` or any other network endpoints.
+
+
+## Exporters
+
+KTM itself has no direct network exporters. All metrics collected by KTM are periodically pushed into the FlightRecorder inside the FODC sidecar at the configured interval (default 10s). External consumers (such as FODC Discovery Proxy, Prometheus integrations, or BanyanDB push/pull paths) read from the FlightRecorder or other FODC-facing APIs and are specified in the FODC design documents rather than this KTM-focused document.
Review Comment:
Inconsistent terminology: "FlightRecorder" should be "Flight Recorder" when used in narrative text to match the existing FODC documentation conventions.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add design documentation for KTM [skywalking-banyandb]
Posted by "wu-sheng (via GitHub)" <gi...@apache.org>.
wu-sheng commented on PR #894:
URL: https://github.com/apache/skywalking-banyandb/pull/894#issuecomment-3641078684
Two things should be clarified
1. Does KTM push collected metrics to flighters?
2. How does the KTM module identify BanyanDB nodes in the pod or VM?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Add design documentation for KTM [skywalking-banyandb]
Posted by "codecov-commenter (via GitHub)" <gi...@apache.org>.
codecov-commenter commented on PR #894:
URL: https://github.com/apache/skywalking-banyandb/pull/894#issuecomment-3640515087
## [Codecov](https://app.codecov.io/gh/apache/skywalking-banyandb/pull/894?dropdown=coverage&src=pr&el=h1&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) Report
:white_check_mark: All modified and coverable lines are covered by tests.
:white_check_mark: Project coverage is 29.04%. Comparing base ([`3530dd9`](https://app.codecov.io/gh/apache/skywalking-banyandb/commit/3530dd9b5cefaa4fef60eec91ecbfbdfcaf243c5?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)) to head ([`e13e164`](https://app.codecov.io/gh/apache/skywalking-banyandb/commit/e13e1649d189eaf61d06aaa4f015f672e83982bc?dropdown=coverage&el=desc&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache)).
:warning: Report is 66 commits behind head on main.
> :exclamation: There is a different number of reports uploaded between BASE (3530dd9) and HEAD (e13e164). Click for more details.
>
> <details><summary>HEAD has 1 upload less than BASE</summary>
>
>| Flag | BASE (3530dd9) | HEAD (e13e164) |
>|------|------|------|
>||1|0|
></details>
<details><summary>Additional details and impacted files</summary>
```diff
@@ Coverage Diff @@
## main #894 +/- ##
===========================================
- Coverage 45.97% 29.04% -16.94%
===========================================
Files 328 114 -214
Lines 55505 11930 -43575
===========================================
- Hits 25520 3465 -22055
+ Misses 27909 8132 -19777
+ Partials 2076 333 -1743
```
| [Flag](https://app.codecov.io/gh/apache/skywalking-banyandb/pull/894/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | Coverage Δ | |
|---|---|---|
| [pkg](https://app.codecov.io/gh/apache/skywalking-banyandb/pull/894/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache) | `29.04% <ø> (?)` | |
Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache#carryforward-flags-in-the-pull-request-comment) to find out more.
</details>
[:umbrella: View full report in Codecov by Sentry](https://app.codecov.io/gh/apache/skywalking-banyandb/pull/894?dropdown=coverage&src=pr&el=continue&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
:loudspeaker: Have feedback on the report? [Share it here](https://about.codecov.io/codecov-pr-comment-feedback/?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=apache).
<details><summary> :rocket: New features to boost your workflow: </summary>
- :snowflake: [Test Analytics](https://docs.codecov.com/docs/test-analytics): Detect flaky tests, report on failures, and find test suite problems.
- :package: [JS Bundle Analysis](https://docs.codecov.com/docs/javascript-bundle-analysis): Save yourself from yourself by tracking and limiting bundle sizes in JS merges.
</details>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@skywalking.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org