Support runtime rule hot-update and DSL debugging for meter-analyzer-config

[wu-sheng]

Support runtime rule hot-update and DSL debugging for the meter-analyzer-config catalog

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

  • Design doc for the mechanism this catalog now joins: Runtime rule hot-update

• Update the documentation to include this new feature.

  • docs/en/setup/backend/backend-meter.md, docs/en/concepts-and-designs/runtime-rule-hot-update.md, docs/en/setup/backend/admin-api/runtime-rule.md, docs/en/setup/backend/admin-api/dsl-debugging.md, docs/en/setup/backend/admin-api/dsl-debugging-mal.md

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

  • UT: new MeterProcessServiceConverterRegistryTest; MeterProcessorTest retargeted onto the shared loader.
  • E2E: new test/e2e-v2/cases/runtime-rule/meter/ (readiness + 5 capability phases) plus a CI matrix entry.

• 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.

---

Target

Give the meter-analyzer-config catalog the same debugging context and hot-update
lifecycle otel-rules already has. otel-rules behaviour is the reference and does
not change; where the meter path fell short, the meter path moved.

capability	otel-rules	meter (before)	meter (now)
named generated classes	Rules.parseRule sets name	getSourceName() null → MalExpr_<N>	same as otel
DSL-debug session can bind	MalStaticBindingHook.publish	no publish at all	publishes
Catalog entry → RuleKey resolves	OTEL_RULES	absent	METER_ANALYZER_CONFIG
RuleSetMerger / StaticRuleRegistry	yes	bypassed (raw snakeyaml)	yes
hot-swappable converter	MalConverterRegistry	plain List<MetricConvert>	MalConverterRegistry

Principle

Same management, same compiler, same runtime — only the inputs differ. Rather than
teach MeterConfig each capability one at a time, meter rules now load through the
identical Rules.loadRules + Rule model otel uses, and MeterConfig/MeterConfigs
are deleted. One MAL rule model repo-wide, so this divergence cannot silently return.

No compiler changes (meter-analyzer/.../compiler/**, .../compiler/rt/**,
.../dsl/** untouched). No MAL runtime changes.

Out of scope, noted for a future PR: MetricConvert.java:135 derives the class-name
L<n> segment from the rules-list index, not the YAML line, so production emits
vm_L0_cpu_total_percentage while the test harness emits vm_L37_…. Real, but it
affects every MAL catalog and is not this change's agenda.

Scope

• Catalog registration — Catalog, MalRuleEngine (CATALOGS +
  resolveConverterRegistry → agent-analyzer), DbOverrideRuntimeRuleResolver,
  MALHolderRegistry, MALDebugRecorderFactory, javadoc/proto catalog lists.

• agent-analyzer — MeterProcessService implements MalConverterRegistry
  (volatile copy-on-write map, same shape as the otel receiver) and publishes
  MalStaticBindingHook; registered on AnalyzerModule under both contracts; rule
  loading moved prepare() → start() so the override resolver sees a live storage
  module; MeterProcessor re-reads converts() per batch, so a hot-add lands on the
  next batch with no restart.

• Tests — MeterProcessorTest retargeted (3 lines, assertions unchanged); new
  MeterProcessServiceConverterRegistryTest mirroring the otel registry contract test.

• E2E — test/e2e-v2/cases/runtime-rule/meter/ + one CI matrix entry. Six phases,
  each guarding one thing this PR changes:
  0. admin API reachable;

  1. bundled visibility — shipped batch-meter.yaml appears in runtime-rule list
     (proves StaticRuleRegistry participation; fails on master);
  2. hot add — a twin-less runtime rule becomes queryable with no restart;
  3. edit — re-applying the same (catalog, name) with an extra metric registers the
     new metric and keeps the already-registered one flowing (converter replacement);
  4. DSL debug — a session binds a bundled meter rule and captures records carrying
     verbatim DSL, real samples and a terminal meterEmit (proves the MAL catalog
     predicates plus MeterProcessService's boot-time MalStaticBindingHook publish);
  5. inactivate — row goes explicitly INACTIVE, its metrics stop producing new
     buckets, bundled keeps producing (converter removal).

  Freshness: every "flowing / stopped" assertion diffs the set of time-bucket ids carrying
  a non-null value against a baseline taken at the transition, so a metric cannot pass on
  stale pre-transition buckets and a stopped metric cannot be masked by history. Bucket-id
  deltas are used instead of absolute --start/--end so the assertions are immune to
  host-vs-container clock/timezone skew.

  Failure vs. absence: the bucket-reading helper returns a non-zero status for transport
  errors, non-JSON bodies and malformed envelopes, which is deliberately distinct from a
  successful query that found no data. The negative ("has it stopped") assertion counts
  only successful observations and refuses to conclude anything below a floor of 3, so a
  broken query path fails the test instead of silently satisfying it. No existing e2e case
  was modified.

• Docs — 5 docs + changelog.

• Drive-by fix — library-pprof-parser was the only module in the repo with
  <checkstyle.skip>true</checkstyle.skip>, hiding 2 real violations. Removed the
  exemption and fixed the violations; full-repo checkstyle is clean.

Behaviour change

An entry in meterAnalyzerActiveFiles / SW_METER_ANALYZER_ACTIVE_FILES with no
matching rule file now fails OAP startup instead of being silently ignored. The
list is operator-supplied, so the files must exist; this also matches how otel-rules
has always behaved. Documented in backend-meter.md and the changelog.

Verification

Passing locally: compile, full-repo checkstyle:check, license-eye (0 invalid /
4969 files), MeterProcessorTest + MeterProcessServiceConverterRegistryTest (4/4),
docker compose config (mounts and the 3-level relative jar path resolve), bash -n,
and the bucket-delta helper unit-tested offline across 5 cases — including the critical
"stale buckets only must NOT count as fresh".

Not run locally: the e2e case itself — needs a built OAP image and a full compose
cycle. Static validation only; watch it in CI.

Review

A multi-agent adversarial review over the whole change set raised 15 candidate findings;
12 were refuted on inspection, 3 confirmed and fixed here:

• Missing StorageModule dependency (real bug, introduced by this PR). Meter rule
  loading moved to start() precisely because RuleSetMerger consults the runtime-rule
  DB override resolver — but AnalyzerModuleProvider.requiredModules() never declared
  StorageModule. A boot-order simulation over all 40 default-enabled modules put
  agent-analyzer at sequence 6 and storage at 13, so RuntimeRuleManagementDAO.getAll()
  would throw "management schema not registered yet", the resolver would log a WARN and
  return empty, and an operator's meter-rule override / inactivate would be ignored until
  the reconciler's next tick. Every other Rules.loadRules caller (otel, telegraf, envoy,
  log-analyzer) already declares it. Fixed, with the same rationale comment; no cycle
  (storage requires only CoreModule).
• E2E raced the async apply. Phase 2 read rule status once immediately after
  addOrUpdate; the apply is async (durable commit returns before the schema fence rolls
  out). Now polls to ACTIVE, as dsl-debugging/mal does — and likewise for the phase-3
  edit and the phase-5 inactivate.
• Budget vs. timeout. Trimmed internal budgets so the pathological worst case is
  ~27.5m inside a 40m case timeout. This matters beyond tidiness: a harness timeout
  cancels the job, and upload-artifact: if failure() does not run on cancellation, so
  a timeout kill yields no logs. Internal budgets must always trip first.

Follow-up (separate repo)

skywalking-cli help text lists only 4 catalogs. The Catalogs vars are declared but
never referenced, so --catalog meter-analyzer-config already works — this is
cosmetic: pkg/admin/runtimerule/runtimerule.go:35,
pkg/admin/dsldebug/dsldebug.go:40,
internal/commands/admin/runtimerule/runtimerule.go:39,54,
internal/commands/admin/dsldebug/dsldebug.go:89.

[Copilot]

Pull request overview

Adds runtime hot-update and DSL debugging support for native meter analyzer rules.

Changes:

• Unifies meter rule loading with the shared MAL pipeline.
• Adds hot-swappable converter registration and debugging bindings.
• Adds documentation, unit tests, and an end-to-end workflow.

Reviewed changes

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

Show a summary per file

File	Description
.github/workflows/skywalking.yaml	Adds the meter runtime-rule E2E job.
docs/en/changes/changes.md	Records the feature and behavior change.
docs/en/concepts-and-designs/runtime-rule-hot-update.md	Adds the meter catalog to MAL scope.
docs/en/setup/backend/admin-api/dsl-debugging-mal.md	Documents the meter MAL catalog.
docs/en/setup/backend/admin-api/dsl-debugging.md	Updates the MAL catalog list.
docs/en/setup/backend/admin-api/runtime-rule.md	Documents runtime-rule support.
docs/en/setup/backend/backend-meter.md	Documents hot updates, debugging, and validation.
oap-server/analyzer/agent-analyzer/.../AnalyzerModule.java	Exposes MalConverterRegistry.
oap-server/analyzer/agent-analyzer/.../AnalyzerModuleProvider.java	Loads shared rules and registers the converter service.
oap-server/analyzer/agent-analyzer/.../MeterConfig.java	Removes the former meter rule model.
oap-server/analyzer/agent-analyzer/.../MeterConfigs.java	Removes the former meter loader.
oap-server/analyzer/agent-analyzer/.../MeterProcessService.java	Implements hot-swappable converter storage.
oap-server/analyzer/agent-analyzer/.../MeterProcessor.java	Reads the current converter snapshot per batch.
oap-server/analyzer/agent-analyzer/.../MeterProcessServiceConverterRegistryTest.java	Tests converter replacement and removal.
oap-server/analyzer/agent-analyzer/.../MeterProcessorTest.java	Uses the shared rule loader.
oap-server/server-admin/dsl-debugging/.../MALDebugRecorderFactory.java	Accepts meter debug keys.
oap-server/server-admin/dsl-debugging/.../MALHolderRegistry.java	Registers meter debug holders.
oap-server/server-admin/runtime-rule/.../MalFileApplier.java	Documents meter catalog application.
oap-server/server-admin/runtime-rule/.../MalRuleEngine.java	Routes meter rules to agent analyzer.
oap-server/server-admin/runtime-rule/.../RuleEngine.java	Updates supported-catalog documentation.
oap-server/server-admin/runtime-rule/.../DbOverrideRuntimeRuleResolver.java	Parses meter layer definitions.
oap-server/server-admin/runtime-rule/.../RuntimeRuleModuleProvider.java	Updates engine-routing documentation.
oap-server/server-admin/runtime-rule/.../RuntimeRuleService.java	Updates catalog scope documentation.
oap-server/server-admin/runtime-rule/.../runtime-rule-cluster.proto	Updates the cluster catalog list.
oap-server/server-core/.../Catalog.java	Adds the meter catalog enum.
oap-server/server-core/.../RuleKey.java	Documents meter debug keys.
oap-server/server-core/.../RuntimeRule.java	Documents meter runtime rows.
oap-server/server-library/library-pprof-parser/pom.xml	Enables checkstyle for the module.
oap-server/server-library/library-pprof-parser/.../FrameTreeBuilder.java	Fixes checkstyle violations.
test/e2e-v2/cases/runtime-rule/meter/bundled/batch-meter.yaml	Defines the bundled test rule.
test/e2e-v2/cases/runtime-rule/meter/docker-compose.yml	Configures the E2E services.
test/e2e-v2/cases/runtime-rule/meter/e2e.yaml	Defines setup, execution, and log collection.
test/e2e-v2/cases/runtime-rule/meter/expected/ok.txt	Defines the verification output.
test/e2e-v2/cases/runtime-rule/meter/meter-runtime-rule-flow.sh	Exercises add, edit, debug, and inactivate flows.
test/e2e-v2/cases/runtime-rule/meter/seed-rules/meter-v1.yaml	Defines the initial runtime rule.
test/e2e-v2/cases/runtime-rule/meter/seed-rules/meter-v2.yaml	Defines the structural update.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 36 out of 36 changed files in this pull request and generated no new comments.

Suppressed comments (2)

test/e2e-v2/cases/runtime-rule/meter/meter-runtime-rule-flow.sh:310

• add_resp comes from the pinned swctl, whose ApplyResult model only retains applyStatus, catalog, name, and message; it drops the server's applyId before rendering JSON. Consequently this is always empty and every structural add/edit is treated as synchronous, so the intended 200-second fence wait never runs (and the subsequent 150-second metric wait can expire before the server's 180-second fence). Submit these two add/update requests with a client that preserves the raw response, or update the pinned CLI model to expose applyId, before polling it here.
  oap-server/server-admin/runtime-rule/src/main/java/org/apache/skywalking/oap/server/receiver/runtimerule/engine/mal/MalRuleEngine.java:164
• This new lookup makes agent-analyzer a functional dependency, but RuntimeRuleModuleProvider.requiredModules() does not declare it. If that module is absent, resolveConverterRegistry swallows the lookup failure and the API can report a successful meter-rule apply while no ingest path receives the converter. Declare agent-analyzer in requiredModules() (as this provider already does for its other mandatory lookups at RuntimeRuleModuleProvider.java:459-489) so bootstrap orders and validates the dependency instead of silently degrading.

            case "meter-analyzer-config":
                // String literal keeps agent-analyzer out of runtime-rule's pom. The registry
                // is MeterProcessService, which serves both the native meter gRPC receiver and
                // the Kafka meter fetcher — one registry covers both ingest paths.
                moduleName = "agent-analyzer";
                break;