[wu-sheng]

Fix the doc inaccuracies and test gaps left after #14208

These are the follow-ups #14208 left out of scope, plus two gaps in its own docs.

Docs

• tal.md: blocks or rules that share a metric must also agree on its labelLimit (TALMetricDeclaration.equals compares it); an omitted one counts as 50.
• tal-otlp.md: the meta table now states what the receiver does: serviceInstance falls back to service.instance, a start or end time left at 0 is replaced by the other one (or by the arrival time when both are 0), and latency is clamped to 0..Integer.MAX_VALUE.
• trace-sampling.md: the setting is named default.rate throughout, the duration.rate and default.rare typos are fixed, and the example rates are 3500 / 5500 (35% / 55% at the 1/10000 precision) instead of 35 / 55.
• virtual-genai.md, trace-analyzer.md: AI evaluation of natively stored OTLP spans needs service.layer=OTLP_GENERAL, the layer otlp-ai-evaluation is declared for. The Virtual GenAI metrics and the Zipkin-path evaluation don't need it. trace-analyzer.md's instance row names the service.instance fallback. The changelog's otlp-ai-evaluation line no longer says every OpenTelemetry rule needs OTLP_GENERAL.
• new-monitoring-feature skill: iOS does get service_cpm and the other core OAL metrics, from IOSHTTPSpanListener. Browser has its own OAL metrics (browser_app_*), and the anti-pattern note now points at the mini-program pattern.

Code

• AliasRegistrar.hostOf, used by the gateway check, checks the port in place instead of through a substring and a character stream. The result is the same for every input: an old-vs-new run over 2,327,680 addresses (every UTF-16 character as the port, plus 2 million random strings) found no difference. A new AliasRegistrarTest case pins the forms, including the empty port and non-ASCII digits.

Tests for documented behaviour of the OTLP AI evaluation that had no dedicated test:

• OtlpAIEvaluationAnalysisTest runs the shipped otlp-ai-evaluation rule through TraceAnalyzerServiceImpl:
  • another rule's drop vote does not stop the sample;
  • a span sent again is sampled once while the dedup window remembers it, and twice with the window off;
  • a failed dispatch fails only that rule, and a rule whose source dispatch fails has its persist {} vote ignored, with a control showing the vote counts when the dispatch succeeds.
• OTLPAnalysisBeforeStorageHandlerTest: a span that a span listener vetoes still reaches the TAL analysis, and only the other span is stored.

Four mutations were checked, each making its matching test fail: stopping at the first drop vote, counting a failed rule's vote, turning dedup off, and skipping the analysis of a vetoed span.

E2E

• download-mysql.sh used curl -Lo, which exits 0 on an HTTP 429 and saves the error body as the driver jar, and had no timeout. It now makes up to five attempts, 5 seconds apart, each with --fail and --max-time 60, and exits non-zero when all fail. After curl is installed, the download takes at most about 320 seconds, and if every attempt fails the OAP does not start, since the entrypoint runs it with &&. The attempts are retried by the script, not by curl's --retry: that sleeps for as long as a 429's Retry-After asks, and with --retry-max-time added, curl 8.19 exited 0 without writing the file when Retry-After exceeded it.
• Tested against a local server answering 429 with Retry-After: 1000 (5 attempts, exit 1 after 20 seconds, no file) and one that never answers (exit 1 after 5 timed-out attempts), and inside the OAP base image eclipse-temurin:25-jre, where it installed curl 8.18 and downloaded the jar.
• Why: in Move the native trace analysis from Java listeners to TAL rules (SWIP-17) #14208's run 42756183940, the Zipkin BanyanDB job's OAP never became healthy within about 11.5 minutes, while another job got HTTP 429 from Maven Central. A download stalled at startup (curl had no timeout) is a possible explanation, though a 429 alone would not have stalled the old curl -Lo, and no OAP log was collected to confirm it.

Verification

• Full unit-test suite (4,163 tests, 0 failures, 0 errors, 5 skipped), checkstyle, the -Pall build with javadoc, and the license-header check of every tracked file pass.

• Add a unit test to verify that the fix works.

• Explain briefly why the bug exists and how to fix it.

• If this pull request closes/resolves/fixes an existing issue, replace the issue number. Not applicable; there is no issue.

• Update the CHANGES log.

[Copilot]

Warning

Copilot couldn't run its full agentic review because it didn't start before the timeout. Make sure your repository has a runner available, or add a copilot-code-review.yml file specifying one with the runs-on attribute. See the docs for more details.

Copilot review overview

4 open issues

• This test relies on reflective access to mutate a private field, which is brittle and can break… · New
• The download writes directly to the final jar path and leaves ${MYSQL_URL} unquoted. If curl… · New
• This introduces an unconditional exit 0 on successful download, whereas the previous version… · New
• Subject–verb agreement: services.[].rate and services.[].duration should use 'have' (plural),… · New

What changed in this PR

Follow-up changes after #14208 to correct documentation, close test gaps around OTLP AI evaluation / trace analysis behavior, and harden an e2e dependency download step.

Changes:

• Hardened MySQL driver download in e2e setup with bounded retries and curl failure handling.
• Added unit tests for OTLP AI evaluation behavior and for analysis running even when a span is vetoed from storage.
• Optimized and expanded coverage for gateway host parsing, plus multiple documentation corrections.

File	Description
test/​e2e-v2/​script/​prepare/​setup-oap/​download-mysql.sh	Adds retry + timeout + --fail to prevent saving HTTP error bodies as a jar.
oap-server/​server-receiver-plugin/​otel-receiver-plugin/​src/​test/​java/​org/​apache/​skywalking/​oap/​server/​receiver/​otel/​otlp/​OTLPAnalysisBeforeStorageHandlerTest.java	New test asserting TAL analysis runs even if a span listener vetoes persistence.
oap-server/​analyzer/​trace-analyzer/​src/​test/​java/​org/​apache/​skywalking/​oap/​trace/​analyzer/​v2/​provider/​span/​OtlpAIEvaluationAnalysisTest.java	New tests for shipped otlp-ai-evaluation behavior (dedup, failures, vote handling).
oap-server/​analyzer/​trace-analyzer/​src/​test/​java/​org/​apache/​skywalking/​oap/​trace/​analyzer/​v2/​provider/​span/​AliasRegistrarTest.java	Adds cases covering host parsing edge cases, including empty/non-ASCII ports.
oap-server/​analyzer/​trace-analyzer/​src/​main/​java/​org/​apache/​skywalking/​oap/​trace/​analyzer/​v2/​provider/​span/​AliasRegistrar.java	Replaces substring+stream digit check with in-place loop.
docs/​en/​setup/​service-agent/​virtual-genai.md	Documents service.layer=OTLP_GENERAL requirement for native OTLP AI evaluation only.
docs/​en/​setup/​backend/​trace-sampling.md	Fixes setting name to default.rate and corrects examples/typos.
docs/​en/​setup/​backend/​trace-analyzer.md	Clarifies OTLP AI evaluation layer scoping and service.instance fallback.
docs/​en/​concepts-and-designs/​tal.md	Documents labelLimit compatibility requirement when sharing metrics.
docs/​en/​concepts-and-designs/​tal-otlp.md	Clarifies OTLP meta fallbacks and timestamp/latency normalization behavior.
docs/​en/​changes/​changes.md	Updates changelog to capture doc fixes and metadata behavior.
.claude/​skills/​new-monitoring-feature/​SKILL.md	Corrects guidance about browser/iOS metrics sources and anti-pattern note.

_{Review effort: Lite}