processor_tda: Address comments

Signed-off-by: Hiroshi Hatake <[email protected]>

Author: cosmo0920

pipeline/processors.md

@@ -21,7 +21,7 @@ Fluent Bit offers the following processors:
 - [Sampling](./processors/sampling.md): Apply head or tail sampling to incoming traces.
 - [SQL](./processors/sql.md): Use SQL queries to extract log content.
 - [Filters as processors](./processors/filters.md): Use filters as processors.
-- [TDA](./processors/tda.md): Do Topological Data Analysis calculations.
+- [TDA](./processors/tda.md): Do Topological Data Analysis (TDA) calculations.
 
 ## Features
 

pipeline/processors/tda.md

@@ -1,9 +1,9 @@
 # TDA
 
-The `tda` processor applies **Topological Data Analysis (TDA)** – specifically, **persistent homology** – to Fluent Bit’s metrics stream and exports **Betti numbers** that summarize the shape of recent behavior in metric space.
-
-This processor is intended for detecting **phase transitions**, **regime changes**, and **intermittent instabilities** that are hard to see from individual counters, gauges, or standard statistical aggregates. It can, for example, differentiate between a single, one-off failure and an extended period of intermittent failures where the system never settles into a stable regime.
+The `tda` processor applies **Topological Data Analysis (TDA)**—specifically, **persistent homology**—to Fluent Bit's metrics stream and exports **Betti numbers** that summarize the shape of recent behavior in metric space.
 
+This processor is intended for detecting **phase transitions**, **regime changes**, and **intermittent instabilities** that are difficult to detect from individual counters, gauges, or standard statistical aggregates.
+It can, for example, differentiate between a single, one-off failure and an extended period of intermittent failures where the system never settles into a stable regime.
 Currently, `tda` works only in the **metrics pipeline** (`processors.metrics`).
 
 ---
@@ -48,7 +48,8 @@ On each metrics flush, `tda`:
    To stabilize very different magnitudes and bursty traffic, each rate is mapped to
    `norm = log1p(|rate|)`, and the sign of `rate` is reattached. This yields a vector that is roughly scale-invariant but still sensitive to relative changes in rates across groups.
 
-The resulting normalized vector is written into a **ring buffer window** (`tda_window`), implemented via a lightweight circular buffer (`lwrb`) that stores timestamped samples. The window maintains at most `window_size` samples; older samples are dropped when the buffer is full.
+The resulting normalized vector is written into a **ring buffer window** (`tda_window`), implemented through a lightweight circular buffer (`lwrb`) that stores timestamped samples.
+The window maintains at most `window_size` samples; older samples are dropped when the buffer is full.
 
 ### 2. Sliding window and delay embedding
 
@@ -65,7 +66,7 @@ $$
 
 where each `x_·` is the **D-dimensional normalized metrics vector** at that time. This yields embedded points in (\mathbb{R}^{mD}).
 
-Because we need all lags to be inside the window, the number of embedded points is:
+Because all lags must be inside the window, the number of embedded points is:
 
 $$
 n_{\text{embed}} = n_{\text{raw}} - (m - 1)\tau
@@ -77,8 +78,8 @@ This embedding follows the idea of **Takens’ theorem**, which states that, und
 
 Intuitively:
 
-* `embed_dim = 1`: you see only the current “snapshot” geometry.
-* `embed_dim > 1`: you expose **loops and recurrent trajectories** in the joint evolution of metrics, which later show up as **H₁ (Betti₁) features**.
+* `embed_dim = 1`: only the current "snapshot" geometry is visible.
+* `embed_dim > 1`: **loops and recurrent trajectories** in the joint evolution of metrics become visible, which later show up as **H₁ (Betti₁) features**.
 
 ### 3. Distance matrix construction
 
@@ -96,7 +97,7 @@ Persistent homology requires a **scale parameter** (Rips radius / distance thres
 
 1. **Automatic multi-quantile scan** (`threshold = 0`, default)
 
-   * The off-diagonal distances are collected, sorted, and several quantiles are evaluated, e.g. `q ∈ {0.10, 0.20, …, 0.90}`.
+   * The off-diagonal distances are collected, sorted, and several quantiles are evaluated, for example `q ∈ {0.10, 0.20, …, 0.90}`.
    * For each candidate quantile `q`, a threshold `r_q` is chosen and Betti numbers are computed using Ripser.
    * The plugin prefers the scale where **Betti₁** (loops) is maximized; if all Betti₁ are zero, it falls back to Betti₀ as a secondary indicator.
 
@@ -174,7 +175,9 @@ Some practical patterns:
    * The trajectory in phase space forms **loops**: metrics move away from the healthy region and then return, many times.
    * Betti₁ (and occasionally Betti₂) increases noticeably while this behavior persists, reflecting the emergence of non-trivial cycles in the metric dynamics.
 
-   In the sample output, as the HTTP output oscillates between success and various `Connection refused` / `broken connection` errors, `fluentbit_tda_betti1` and `fluentbit_tda_betti2` grow from small values to larger plateaus (e.g., Betti₁ around 10–13, Betti₂ around 1–2) while Betti₀ also increases. This is a direct signature of a **phase transition** from a stable regime to one with persistent, intermittent instability.
+   In the sample output, the HTTP output oscillates between success and various "Connection refused" and "broken connection" errors.
+   As this occurs, `fluentbit_tda_betti1` and `fluentbit_tda_betti2` grow from small values to larger plateaus (for example, Betti₁ around 10—13, Betti₂ around 1—2) while Betti₀ also increases.
+   This is a direct signature of a **phase transition** from a stable regime to one with persistent, intermittent instability.
 
 These interpretations are consistent with results from condensed matter physics and dynamical systems, where persistent homology has been used to detect phase transitions and changes in underlying order purely from data (References 1 and 2).