MAL: add safeDiv(divisor) on SampleFamily that yields 0 when the divisor is 0. (#13846)

Author: wankai123

docs/en/changes/changes.md

@@ -39,6 +39,8 @@
 * Fix: remove `VirtualServiceAnalysisListener`'s dependency on `GenAIAnalyzerModule` if it is disabled.
 * MAL: register `TimeUnit` in `MALCodegenHelper.ENUM_FQCN` so rule YAML can write `.histogram("le", TimeUnit.MILLISECONDS)` for SDKs that emit histogram bucket bounds in ms (default `SECONDS` unit applies a ×1000 rescale that would otherwise inflate stored `le` labels 1000×).
 * Fix: potential unexpected current directory inclusion in Docker OAP classpath.
+* MAL: add `safeDiv(divisor)` on `SampleFamily` that yields `0` when the divisor is `0` instead of `Infinity`/`NaN`. Replace `/` with `safeDiv(...)` in Envoy AI Gateway latency-average rules so `sum / count * 1000` no longer produces dropped or out-of-range samples when a counter is zero in a window.
+* Fix: `envoy-ai-gateway` metrics rules, make the metrics value return `0` when the divisor is `0`.
 
 #### UI
 * Add mobile menu icon and i18n labels for the iOS layer.

docs/en/concepts-and-designs/mal.md

@@ -152,6 +152,22 @@ have no match and will not show up in the result:
 {region="asia-north",az="az-1"} 0.3333  // 11 / 33
 ```
 
+#### Safe division
+
+The binary `/` operator produces `Infinity` when the right-hand value is `0`, and `NaN` when both
+sides are `0` (NaN samples are silently dropped during evaluation). Either result is rarely useful
+for downstream metrics. The `safeDiv` method on a sample family substitutes `0` for the result whenever
+the divisor is `0`. In other cases it follows normal division semantics, except that dividing by an
+empty sample family yields an empty result instead of `Infinity`/`NaN`-style output:
+
+```
+gen_ai_server_request_duration_sum.sum(['service_name']).increase('PT1M')
+    .safeDiv(gen_ai_server_request_duration_count.sum(['service_name']).increase('PT1M')) * 1000
+```
+
+`safeDiv` accepts either a sample family or a scalar number argument. Use it when the denominator
+is a counter that may legitimately be zero in a given window (e.g. request count, error count).
+
 ### Aggregation Operation
 
 Sample family supports the following aggregation operations that can be used to aggregate the samples of a single sample family,

oap-server/analyzer/meter-analyzer/src/main/java/org/apache/skywalking/oap/meter/analyzer/v2/dsl/SampleFamily.java

@@ -229,6 +229,31 @@ public SampleFamily div(SampleFamily another) {
         return newValue(another, (a, b) -> a / b);
     }
 
+    /**
+     * Safe variant of {@link #div(Number)}: when the divisor is zero, the
+     * resulting samples are valued {@code 0.0} instead of {@code NaN}/{@code Infinity}.
+     */
+    public SampleFamily safeDiv(Number number) {
+        final double divisor = number.doubleValue();
+        if (divisor == 0.0) {
+            return newValue(v -> 0.0);
+        }
+        return newValue(v -> v / divisor);
+    }
+
+    /**
+     * Safe variant of {@link #div(SampleFamily)}: for each label-matched pair,
+     * yields {@code 0.0} when the right-hand value is zero. When the divisor
+     * family is {@link #EMPTY}, the result is also {@link #EMPTY} (no samples
+     * to evaluate against), instead of producing {@code NaN}/{@code Infinity}.
+     */
+    public SampleFamily safeDiv(SampleFamily another) {
+        if (this == EMPTY || another == EMPTY) {
+            return SampleFamily.EMPTY;
+        }
+        return newValue(another, (a, b) -> b == 0.0 ? 0.0 : a / b);
+    }
+
     /* Aggregation operators */
     public SampleFamily sum(List<String> by) {
         return aggregate(by, Double::sum);

oap-server/analyzer/meter-analyzer/src/test/java/org/apache/skywalking/oap/meter/analyzer/v2/compiler/MALClassGeneratorTest.java

@@ -17,11 +17,16 @@
 
 package org.apache.skywalking.oap.meter.analyzer.v2.compiler;
 
+import com.google.common.collect.ImmutableMap;
 import javassist.ClassPool;
 import org.apache.skywalking.oap.meter.analyzer.v2.dsl.MalExpression;
+import org.apache.skywalking.oap.meter.analyzer.v2.dsl.Sample;
+import org.apache.skywalking.oap.meter.analyzer.v2.dsl.SampleFamily;
+import org.apache.skywalking.oap.meter.analyzer.v2.dsl.SampleFamilyBuilder;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 
+import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertNotNull;
 import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -148,6 +153,56 @@ void compileMethodCallMultiply() throws Exception {
         assertNotNull(expr.run(java.util.Map.of()));
     }
 
+    @Test
+    void compileSafeDivBetweenFamiliesYieldsZeroWhenDenominatorIsZero() throws Exception {
+        final MalExpression expr = generator.compile(
+            "test_safe_div",
+            "metric_sum.safeDiv(metric_count) * 1000");
+        assertNotNull(expr);
+
+        final SampleFamily sum = SampleFamilyBuilder.newBuilder(
+            Sample.builder().labels(ImmutableMap.of("svc", "s1")).value(50.0).build()).build();
+        final SampleFamily count = SampleFamilyBuilder.newBuilder(
+            Sample.builder().labels(ImmutableMap.of("svc", "s1")).value(0.0).build()).build();
+
+        final SampleFamily result = expr.run(java.util.Map.of(
+            "metric_sum", sum, "metric_count", count));
+        assertNotNull(result);
+        assertEquals(1, result.samples.length);
+        assertEquals(0.0, result.samples[0].getValue(), 0.001);
+    }
+
+    @Test
+    void compileSafeDivBetweenFamiliesNonZeroDenominator() throws Exception {
+        final MalExpression expr = generator.compile(
+            "test_safe_div_ok",
+            "metric_sum.safeDiv(metric_count) * 1000");
+        assertNotNull(expr);
+
+        final SampleFamily sum = SampleFamilyBuilder.newBuilder(
+            Sample.builder().labels(ImmutableMap.of("svc", "s1")).value(2.0).build()).build();
+        final SampleFamily count = SampleFamilyBuilder.newBuilder(
+            Sample.builder().labels(ImmutableMap.of("svc", "s1")).value(4.0).build()).build();
+
+        final SampleFamily result = expr.run(java.util.Map.of(
+            "metric_sum", sum, "metric_count", count));
+        assertEquals(500.0, result.samples[0].getValue(), 0.001);
+    }
+
+    @Test
+    void compileSafeDivByZeroNumberLiteral() throws Exception {
+        final MalExpression expr = generator.compile(
+            "test_safe_div_zero_lit",
+            "metric.safeDiv(0)");
+        assertNotNull(expr);
+
+        final SampleFamily input = SampleFamilyBuilder.newBuilder(
+            Sample.builder().labels(ImmutableMap.of("k", "v")).value(123.0).build()).build();
+
+        final SampleFamily result = expr.run(java.util.Map.of("metric", input));
+        assertEquals(0.0, result.samples[0].getValue(), 0.001);
+    }
+
     // ==================== Error handling tests ====================
 
     @Test

oap-server/analyzer/meter-analyzer/src/test/java/org/apache/skywalking/oap/meter/analyzer/v2/dsl/DSLV2Test.java

@@ -89,4 +89,88 @@ void filterExpressionWithMalFilter() {
         assertEquals(1, filtered.samples.length);
         assertEquals(10.0, filtered.samples[0].getValue());
     }
+
+    @Test
+    void safeDivByZeroNumberYieldsZero() {
+        final SampleFamily sf = SampleFamilyBuilder.newBuilder(
+            Sample.builder().name("m").labels(ImmutableMap.of("k", "v")).value(100.0).build()).build();
+
+        final SampleFamily result = sf.safeDiv(0);
+
+        assertNotNull(result);
+        assertTrue(result != SampleFamily.EMPTY);
+        assertEquals(1, result.samples.length);
+        assertEquals(0.0, result.samples[0].getValue());
+    }
+
+    @Test
+    void safeDivByNonZeroNumberDividesNormally() {
+        final SampleFamily sf = SampleFamilyBuilder.newBuilder(
+            Sample.builder().name("m").labels(ImmutableMap.of("k", "v")).value(100.0).build()).build();
+
+        final SampleFamily result = sf.safeDiv(4);
+
+        assertEquals(25.0, result.samples[0].getValue());
+    }
+
+    @Test
+    void safeDivByFamilyYieldsZeroWhenDenominatorIsZero() {
+        final SampleFamily numerator = SampleFamilyBuilder.newBuilder(
+            Sample.builder().name("sum").labels(ImmutableMap.of("svc", "s1")).value(50.0).build()).build();
+        final SampleFamily denominator = SampleFamilyBuilder.newBuilder(
+            Sample.builder().name("count").labels(ImmutableMap.of("svc", "s1")).value(0.0).build()).build();
+
+        final SampleFamily result = numerator.safeDiv(denominator);
+
+        assertNotNull(result);
+        assertTrue(result != SampleFamily.EMPTY);
+        assertEquals(1, result.samples.length);
+        assertEquals(0.0, result.samples[0].getValue());
+    }
+
+    @Test
+    void safeDivByFamilyMixesZeroAndNonZeroDenominators() {
+        final SampleFamily numerator = SampleFamilyBuilder.newBuilder(
+            Sample.builder().name("sum").labels(ImmutableMap.of("svc", "s1")).value(60.0).build(),
+            Sample.builder().name("sum").labels(ImmutableMap.of("svc", "s2")).value(20.0).build()).build();
+        final SampleFamily denominator = SampleFamilyBuilder.newBuilder(
+            Sample.builder().name("count").labels(ImmutableMap.of("svc", "s1")).value(0.0).build(),
+            Sample.builder().name("count").labels(ImmutableMap.of("svc", "s2")).value(4.0).build()).build();
+
+        final SampleFamily result = numerator.safeDiv(denominator);
+
+        assertEquals(2, result.samples.length);
+        final double v1 = sampleValueByLabel(result, "svc", "s1");
+        final double v2 = sampleValueByLabel(result, "svc", "s2");
+        assertEquals(0.0, v1);
+        assertEquals(5.0, v2);
+    }
+
+    @Test
+    void safeDivByEmptyFamilyReturnsEmpty() {
+        final SampleFamily numerator = SampleFamilyBuilder.newBuilder(
+            Sample.builder().name("sum").labels(ImmutableMap.of("svc", "s1")).value(60.0).build()).build();
+
+        final SampleFamily result = numerator.safeDiv(SampleFamily.EMPTY);
+
+        assertEquals(SampleFamily.EMPTY, result);
+    }
+
+    @Test
+    void safeDivOnEmptyFamilyReturnsEmpty() {
+        final SampleFamily denominator = SampleFamilyBuilder.newBuilder(
+            Sample.builder().name("count").labels(ImmutableMap.of("svc", "s1")).value(2.0).build()).build();
+
+        assertEquals(SampleFamily.EMPTY, SampleFamily.EMPTY.safeDiv(denominator));
+        assertEquals(SampleFamily.EMPTY, SampleFamily.EMPTY.safeDiv(2));
+    }
+
+    private static double sampleValueByLabel(final SampleFamily sf, final String labelKey, final String labelValue) {
+        for (final Sample s : sf.samples) {
+            if (labelValue.equals(s.getLabels().get(labelKey))) {
+                return s.getValue();
+            }
+        }
+        throw new IllegalStateException("No sample with " + labelKey + "=" + labelValue);
+    }
 }

oap-server/server-starter/src/main/resources/otel-rules/envoy-ai-gateway/gateway-instance.yaml

@@ -31,7 +31,7 @@ metricsRules:
 
   # Request latency average (ms)
   - name: request_latency_avg
-    exp: gen_ai_server_request_duration_sum.sum(['service_name', 'service_instance_id']).increase('PT1M') / gen_ai_server_request_duration_count.sum(['service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: gen_ai_server_request_duration_sum.sum(['service_name', 'service_instance_id']).increase('PT1M').safeDiv(gen_ai_server_request_duration_count.sum(['service_name', 'service_instance_id']).increase('PT1M')) * 1000
 
   # Request latency percentile (ms)
   - name: request_latency_percentile
@@ -47,15 +47,15 @@ metricsRules:
 
   # TTFT average (ms)
   - name: ttft_avg
-    exp: gen_ai_server_time_to_first_token_sum.sum(['service_name', 'service_instance_id']).increase('PT1M') / gen_ai_server_time_to_first_token_count.sum(['service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: gen_ai_server_time_to_first_token_sum.sum(['service_name', 'service_instance_id']).increase('PT1M').safeDiv(gen_ai_server_time_to_first_token_count.sum(['service_name', 'service_instance_id']).increase('PT1M')) * 1000
 
   # TTFT percentile (ms)
   - name: ttft_percentile
     exp: gen_ai_server_time_to_first_token.sum(['le', 'service_name', 'service_instance_id']).increase('PT1M').histogram().histogram_percentile([50,75,90,95,99]) * 1000
 
   # TPOT average (ms)
   - name: tpot_avg
-    exp: gen_ai_server_time_per_output_token_sum.sum(['service_name', 'service_instance_id']).increase('PT1M') / gen_ai_server_time_per_output_token_count.sum(['service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: gen_ai_server_time_per_output_token_sum.sum(['service_name', 'service_instance_id']).increase('PT1M').safeDiv(gen_ai_server_time_per_output_token_count.sum(['service_name', 'service_instance_id']).increase('PT1M')) * 1000
 
   # TPOT percentile (ms)
   - name: tpot_percentile
@@ -73,7 +73,7 @@ metricsRules:
 
   # Provider latency average (ms)
   - name: provider_latency_avg
-    exp: gen_ai_server_request_duration_sum.sum(['gen_ai_provider_name', 'service_name', 'service_instance_id']).increase('PT1M') / gen_ai_server_request_duration_count.sum(['gen_ai_provider_name', 'service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: gen_ai_server_request_duration_sum.sum(['gen_ai_provider_name', 'service_name', 'service_instance_id']).increase('PT1M').safeDiv(gen_ai_server_request_duration_count.sum(['gen_ai_provider_name', 'service_name', 'service_instance_id']).increase('PT1M')) * 1000
 
   # ===================== Per-model breakdown =====================
 
@@ -87,12 +87,12 @@ metricsRules:
 
   # Model latency average (ms)
   - name: model_latency_avg
-    exp: gen_ai_server_request_duration_sum.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M') / gen_ai_server_request_duration_count.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: gen_ai_server_request_duration_sum.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M').safeDiv(gen_ai_server_request_duration_count.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M')) * 1000
 
   # Model TTFT average (ms)
   - name: model_ttft_avg
-    exp: gen_ai_server_time_to_first_token_sum.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M') / gen_ai_server_time_to_first_token_count.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: gen_ai_server_time_to_first_token_sum.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M').safeDiv(gen_ai_server_time_to_first_token_count.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M')) * 1000
 
   # Model TPOT average (ms)
   - name: model_tpot_avg
-    exp: gen_ai_server_time_per_output_token_sum.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M') / gen_ai_server_time_per_output_token_count.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: gen_ai_server_time_per_output_token_sum.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M').safeDiv(gen_ai_server_time_per_output_token_count.sum(['gen_ai_response_model', 'service_name', 'service_instance_id']).increase('PT1M')) * 1000

oap-server/server-starter/src/main/resources/otel-rules/envoy-ai-gateway/gateway-mcp-instance.yaml

@@ -31,7 +31,7 @@ metricsRules:
 
   # MCP request latency average (ms)
   - name: request_latency_avg
-    exp: mcp_request_duration_sum.sum(['service_name', 'service_instance_id']).increase('PT1M') / mcp_request_duration_count.sum(['service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: mcp_request_duration_sum.sum(['service_name', 'service_instance_id']).increase('PT1M').safeDiv(mcp_request_duration_count.sum(['service_name', 'service_instance_id']).increase('PT1M')) * 1000
 
   # MCP request latency percentile (ms)
   - name: request_latency_percentile
@@ -47,7 +47,7 @@ metricsRules:
 
   # MCP initialization latency average (ms)
   - name: initialization_latency_avg
-    exp: mcp_initialization_duration_sum.sum(['service_name', 'service_instance_id']).increase('PT1M') / mcp_initialization_duration_count.sum(['service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: mcp_initialization_duration_sum.sum(['service_name', 'service_instance_id']).increase('PT1M').safeDiv(mcp_initialization_duration_count.sum(['service_name', 'service_instance_id']).increase('PT1M')) * 1000
 
   # MCP initialization latency percentile (ms)
   - name: initialization_latency_percentile
@@ -65,7 +65,7 @@ metricsRules:
 
   # Backend request latency average (ms)
   - name: backend_request_latency_avg
-    exp: mcp_request_duration_sum.sum(['mcp_backend', 'service_name', 'service_instance_id']).increase('PT1M') / mcp_request_duration_count.sum(['mcp_backend', 'service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: mcp_request_duration_sum.sum(['mcp_backend', 'service_name', 'service_instance_id']).increase('PT1M').safeDiv(mcp_request_duration_count.sum(['mcp_backend', 'service_name', 'service_instance_id']).increase('PT1M')) * 1000
 
   # Backend method CPM
   - name: backend_method_cpm
@@ -77,4 +77,4 @@ metricsRules:
 
   # Backend initialization latency average (ms)
   - name: backend_initialization_latency_avg
-    exp: mcp_initialization_duration_sum.sum(['mcp_backend', 'service_name', 'service_instance_id']).increase('PT1M') / mcp_initialization_duration_count.sum(['mcp_backend', 'service_name', 'service_instance_id']).increase('PT1M') * 1000
+    exp: mcp_initialization_duration_sum.sum(['mcp_backend', 'service_name', 'service_instance_id']).increase('PT1M').safeDiv(mcp_initialization_duration_count.sum(['mcp_backend', 'service_name', 'service_instance_id']).increase('PT1M')) * 1000

oap-server/server-starter/src/main/resources/otel-rules/envoy-ai-gateway/gateway-mcp-service.yaml

@@ -36,7 +36,7 @@ metricsRules:
 
   # MCP request latency average (ms)
   - name: request_latency_avg
-    exp: mcp_request_duration_sum.sum(['service_name']).increase('PT1M') / mcp_request_duration_count.sum(['service_name']).increase('PT1M') * 1000
+    exp: mcp_request_duration_sum.sum(['service_name']).increase('PT1M').safeDiv(mcp_request_duration_count.sum(['service_name']).increase('PT1M')) * 1000
 
   # MCP request latency percentile (ms)
   - name: request_latency_percentile
@@ -52,7 +52,7 @@ metricsRules:
 
   # MCP initialization latency average (ms)
   - name: initialization_latency_avg
-    exp: mcp_initialization_duration_sum.sum(['service_name']).increase('PT1M') / mcp_initialization_duration_count.sum(['service_name']).increase('PT1M') * 1000
+    exp: mcp_initialization_duration_sum.sum(['service_name']).increase('PT1M').safeDiv(mcp_initialization_duration_count.sum(['service_name']).increase('PT1M')) * 1000
 
   # MCP initialization latency percentile (ms)
   - name: initialization_latency_percentile
@@ -70,7 +70,7 @@ metricsRules:
 
   # Backend request latency average (ms) — labeled by mcp_backend
   - name: backend_request_latency_avg
-    exp: mcp_request_duration_sum.sum(['mcp_backend', 'service_name']).increase('PT1M') / mcp_request_duration_count.sum(['mcp_backend', 'service_name']).increase('PT1M') * 1000
+    exp: mcp_request_duration_sum.sum(['mcp_backend', 'service_name']).increase('PT1M').safeDiv(mcp_request_duration_count.sum(['mcp_backend', 'service_name']).increase('PT1M')) * 1000
 
   # Backend method CPM — labeled by mcp_backend and mcp_method_name
   - name: backend_method_cpm
@@ -82,4 +82,4 @@ metricsRules:
 
   # Backend initialization latency average (ms) — labeled by mcp_backend
   - name: backend_initialization_latency_avg
-    exp: mcp_initialization_duration_sum.sum(['mcp_backend', 'service_name']).increase('PT1M') / mcp_initialization_duration_count.sum(['mcp_backend', 'service_name']).increase('PT1M') * 1000
+    exp: mcp_initialization_duration_sum.sum(['mcp_backend', 'service_name']).increase('PT1M').safeDiv(mcp_initialization_duration_count.sum(['mcp_backend', 'service_name']).increase('PT1M')) * 1000