Fix MAL line attribution: separate the operator and machine coordinates

[wu-sheng]

Fix MAL generated-class and debug-record line attribution

• If this is non-trivial feature, paste the links/URLs to the design doc.

  • Background on the generated-class artifacts: Dynamic code generation debugging

• Update the documentation to include this new feature.

  • docs/en/setup/backend/admin-api/dsl-debugging-mal.md (the sourceLine wire shape), docs/en/operation/dynamic-code-generation-debugging.md (the SourceFile format and the two coordinate spaces)

• Tests(including UT, IT, E2E) are added to verify the new feature.

  • 31 new unit tests across 6 classes; see the verification table below.

• If it's UI related, attach the screenshots below.

• If this pull request closes/resolves/fixes an existing issue, replace the issue number. Closes #.

• Update the CHANGES log.

---

The problem

A MAL rule's compiled expression lives in two independent coordinate spaces, and a single
overloaded yamlSource string was serving as class label, file identifier and line coordinate at
once. All four resulting artifacts were wrong:

artifact	before	why it was wrong
class name	vm_L0_cpu_total_percentage	L0 is the rules-list index, not a line — every file's first rule was L0
SourceFile	(vm.yaml:0)cpu_total_percentage.java	names a file that is never written (the file is named after the class), so IDE source-attach could never resolve — independent of the line being wrong
LineNumberTable	1,2,3,4,5,6,7	statement ordinals, matching neither the YAML nor the generated source
debug sourceLine	omitted	hardcoded 0 at all five probe sites; the docs said "omitted for MAL (no per-line mapping)" — true only because the mapping was never built

The fix

Operator coordinate — the rule .yaml the operator wrote — now reaches the dsl-debugging API
as a per-stage sourceLine. Per stage, not per rule, because formatExp splices expPrefix,
exp and expSuffix into one expression. Real generated output for a rule whose exp: is on line
38 and whose file-level expSuffix: is on line 32:

captureInput(..., "node_cpu",                         _node_cpu, 38);   // exp:
captureStage(..., "sum(['host'])",                    _node_cpu, 38);   // exp:
captureStage(..., "rate('PT1M')",                     _node_cpu, 38);   // exp:
captureStage(..., "service(['host'], Layer.GENERAL)", _node_cpu, 32);   // expSuffix:

A per-rule implementation emits 38 on all four and looks perfectly plausible.

Machine coordinate — the generated .java — is now self-consistent: SourceFile equals the
file actually written, and LineNumberTable points at real statements in it.

SourceFile        (vm.yaml:0)cpu_total_percentage.java  →  vm_L37_cpu_total_percentage.java
LineNumberTable   1,2,3,4,5,6,7                         →  11,12,13,14,15,16,17

File line 16 really is .service(...), 17 is return.

MalSourceRef carries both coordinates with distinct accessors, so substituting one for the other
is a visible mistake rather than the default. An unresolvable line is -1, never 0 or omitted, so
a resolution failure stays visible in the artifact; it renders as unknown inside class names,
where - is not legal in an identifier.

Deliberate decisions worth reviewing

• Companion closure classes now emit no LineNumberTable. No .java is written for them, and
  the store-scan is not a statement-boundary detector there (one real companion had a single entry
  spanning 204 bytes). An absent table makes the JVM report "unknown line", which is honest; the
  previous one attributed every frame in the closure to line 1.
• Source anchors are excluded from equals/hashCode. Otherwise adding a comment above a rule
  shifts its line, changes its identity, and triggers a spurious STRUCTURAL re-apply in
  runtime-rule — dropping and recreating BanyanDB measures for a semantically identical edit.
• MALDebugRecorder's five append* methods gained a sourceLine parameter. One in-tree
  implementor; not a public API/SPI.
• zabbix-rules is untouched. It is not a runtime-rule catalog, has no debug binding, and
  ZabbixConfig does not override getSourceName() — so its classes were never source-named and
  are unaffected.

Verification

check	result
clean checkstyle:check (full repo)	exit 0
license-eye header check	0 invalid / 4981
clean install javadoc:javadoc -Pall	exit 0 — 90 jars, 12 apidocs
shipped MAL rules (MALExpressionExecutionTest)	1362 / 1362
shipped filters / LAL / parser	35 / 55 / 22
module suites	213, 206, 149, 49, 23, 10

The 22 parser tests confirm the injectExpPrefix rewrite (right-to-left replace → left-to-right
build, so splice ranges are recoverable) produces byte-identical output.

New tests, by coordinate:

coordinate	tests
machine	MalGeneratedSourceLinesTest (4), MalLineAttributionTest (4 — compiles for real, reads the written .java/.class, asserts SourceFile == filename and every table entry indexes a statement)
operator	MalYamlLineIndexTest (6), MalPrefixInjectionRangesTest (4), MalSourceMapTest (5), MalProbeSourceLineTest (5), MalProbeEmissionTest (3 — runs with injection enabled and asserts the literal in the emitted probe)

The wrapper-geometry guard was mutation-tested: shifting the constant by one fails
MalLineAttributionTest with line 17 should hold a statement but was: '}'.

Both shipped MAL file-format variants are covered by test-scope fixtures (no bundled rules are read):
the zabbix metrics: rules key, and folded/literal block scalars, which anchor on their key line and
must not shift the rule that follows.

Not run locally: the dsl-debugging/mal e2e. Everything up to the emitted probe literal is
unit-verified, but a live debug session showing sourceLine in an API response is CI's first look.

[Copilot]

Pull request overview

Fixes MAL operator-facing YAML attribution and generated Java debug coordinates.

Changes:

• Adds YAML source indexing and per-stage debug line propagation.
• Aligns generated SourceFile and LineNumberTable metadata.
• Adds tests, documentation, and changelog updates.

Reviewed changes

Copilot reviewed 34 out of 34 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
MalFileApplier.java	Stamps runtime-rule source lines.
MALDebugRecorderImpl.java	Records probe source lines.
MalYamlLineIndexTest.java	Tests YAML anchor indexing.
MalProbeSourceLineTest.java	Tests per-stage attribution.
MalSourceMapTest.java	Tests expression source mapping.
MalProbeEmissionTest.java	Tests emitted probe literals.
MalPrefixInjectionRangesTest.java	Tests prefix splice ranges.
MalLineAttributionTest.java	Validates generated class metadata.
MalGeneratedSourceLinesTest.java	Tests statement-line detection.
RuleSourceLines.java	Applies source anchors to rules.
Rules.java	Indexes disk-loaded rule text.
Rule.java	Stores file-level anchors.
MetricsRule.java	Stores per-rule anchors.
MetricRuleConfig.java	Exposes source-line contracts.
MetricConvert.java	Builds and propagates source maps.
MalYamlLineIndex.java	Resolves YAML node lines.
MALDebugRecorder.java	Adds source-line parameters.
MALDebug.java	Forwards probe source lines.
DSL.java	Adds source-mapped parsing.
MalSourceRef.java	Models YAML/generated coordinates.
MalSourceMap.java	Maps expression offsets to YAML.
MALScriptParser.java	Tracks prefix and method offsets.
MALMethodChainCodegen.java	Attributes chain-stage probes.
MalGeneratedSourceLines.java	Finds generated statement lines.
MALExpressionModel.java	Stores method-call source offsets.
MALExprCodegen.java	Emits attributed probes.
MALCodegenHelper.java	Adds line literals to probes.
MALClosureCodegen.java	Removes misleading companion tables.
MALClassGenerator.java	Aligns generated source metadata.
MALBytecodeHelper.java	Builds generated-source line tables.
Analyzer.java	Attributes filter/output probes.
dsl-debugging-mal.md	Documents MAL sourceLine.
dynamic-code-generation-debugging.md	Documents coordinate spaces.
changes.md	Records the attribution fix.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.