docs(events): plan per-instance metrics normalization

[josecelano]

Summary

• Document the current HTTP/UDP event and metrics topology in docs/events-architecture.md.
• Correct the shared-services ADR: the UDP server currently has one application-wide event bus and aggregate repository; this is independent from the public TOML configuration shape.
• Archive the earlier Fix duplicate port-zero tracker instance bootstrap #2035 implementation attempt as reference-only and revise Fix duplicate port-zero tracker instance bootstrap #2035’s delivery order.
• Add approved issue Normalize per-instance event metrics policy #2039 and its progressive baseline/post-change manual evidence protocol.
• Add future shared-event-bus integration coverage to Allow multiple integration tests at the main app level #1419.

Validation

• linter markdown
• linter cspell
• cargo +nightly fmt --check
• cargo +nightly check --tests --benches --examples --workspace --all-targets --all-features
• cargo +nightly doc --no-deps --bins --examples --workspace --all-features
• cargo +stable test --tests --benches --examples --workspace --all-targets --all-features

Scope

Documentation and specifications only; no runtime behavior changes.

Related to #2035, #2036, and #2039.

[Copilot]

Pull request overview

Documentation-focused PR that formalizes the current HTTP/UDP event-bus + metrics topology and records a plan to normalize per-listener metrics policy (while keeping objective events and UDP banning independent), aligning upcoming work across #2035/#2036/#2039/#1419.

Changes:

• Added approved issue spec #2039 (plus a progressive baseline/post-change manual evidence protocol).
• Documented current event topology and the intended producer-vs-consumer (metrics filtering) responsibility split in a new docs/events-architecture.md, and linked it from docs/index.md.
• Updated #2035 and the shared-services ADR to reflect the current “single UDP server container/event bus/repository shared across UDP listeners” reality and archived the previous #2035 implementation attempt as reference-only; updated #1419 to include future integration coverage.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
docs/issues/open/2039-normalize-per-instance-event-metrics-policy/ISSUE.md	New approved spec defining the normalized per-instance metrics policy and task plan.
docs/issues/open/2039-normalize-per-instance-event-metrics-policy/evidence.md	New manual evidence log template/protocol for progressive baseline vs post-change probes.
docs/issues/open/2035-fix-duplicate-port-zero-tracker-instance-bootstrap/ISSUE.md	Revised #2035 delivery order and added references to #2036/#2039 + archived attempt context.
docs/issues/open/2035-fix-duplicate-port-zero-tracker-instance-bootstrap/archived-attempt.md	Records why the prior attempt must not be merged and what it demonstrated.
docs/issues/open/1419-allow-multiple-integration-tests-at-main-app-level/ISSUE.md	Adds a future shared-event-bus / metrics-policy integration test task after prerequisites land.
docs/index.md	Adds the new events architecture guide to the documentation index.
docs/events-architecture.md	New architecture guide documenting current event/metrics topology and the normalization direction.
docs/adrs/20260727180000_shared_services_across_tracker_instances.md	Corrects/clarifies that UDP server bus + stats repository are application-wide shared services and links to the new architecture guide.

---

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

docs/issues/open/2035-fix-duplicate-port-zero-tracker-instance-bootstrap/ISSUE.md:83

• The revised delivery-plan text makes #2035 depend on #2036, but the current #2036 spec still states that #2035 is a prerequisite. This creates a circular dependency across the two specs. Either update #2036 in this PR to match the new order, or soften this wording here so it doesn’t assert an ordering that contradicts the #2036 document.

Issue [#2035](https://github.com/torrust/torrust-tracker/issues/2035) must be reimplemented after #2036 provides canonical runtime identity and
after [#2039](../2039-normalize-per-instance-event-metrics-policy/ISSUE.md)
lands. The new implementation will preserve bootstrap identity without creating
a second runtime identity or metrics-policy mechanism.

docs/issues/open/2039-normalize-per-instance-event-metrics-policy/evidence.md:7

• This evidence file says the probes are required by the "draft specification", but the spec has been promoted to an approved/open issue spec (#2039). Updating this wording avoids confusion about whether the protocol is still tentative.

This file records the progressive manual baseline and post-change probes
required by the draft specification. Each code-changing task must have one
entry before its change and one entry after it.

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (2)

docs/issues/open/2036-add-runtime-service-registry-metadata/ISSUE.md:20

• related-issues for #2036 only lists #1419, but this spec explicitly ties into #2035 (bootstrap propagation), #2041 (registry metadata migration), and #2039 (event/metrics normalization). Adding them here makes the dependency chain discoverable from the frontmatter.

  related-issues:
    - 1419

docs/issues/open/2036-add-runtime-service-registry-metadata/ISSUE.md:18

• The semantic-links metadata for #2036 omits the #2039 spec from related-artifacts, even though #2039 is a primary consumer of the canonical identity types described here. Keeping related-artifacts complete helps navigation and any tooling that builds cross-links.

This issue also appears on line 19 of the same file.

    - docs/issues/open/1419-allow-multiple-integration-tests-at-main-app-level/ISSUE.md
    - docs/issues/open/2035-fix-duplicate-port-zero-tracker-instance-bootstrap/ISSUE.md
    - docs/issues/open/2041-migrate-runtime-service-registry-metadata/ISSUE.md

[josecelano]

ACK 26c7018

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

docs/issues/open/2036-add-runtime-service-registry-metadata/ISSUE.md:28

• The #2036 spec’s title/goal has been changed to “Define Canonical Runtime Service Identity”, but the folder slug and spec-path still use 2036-add-runtime-service-registry-metadata. This diverges from the docs/issues/open/ naming convention {ISSUE_NUMBER}-{short-description}/ISSUE.md and makes the spec harder to discover by name.

Consider renaming the folder (and updating spec-path plus any relative links/references to it) so the short description matches the current issue scope.

# Issue #2036 - Define Canonical Runtime Service Identity

## Goal

Define tracker-owned canonical service-role and configuration-instance identity
types that can be used consistently by bootstrap, runtime registration, and

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.56%. Comparing base (1731994) to head (26c7018).
⚠️ Report is 16 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2040      +/-   ##
===========================================
+ Coverage    81.46%   81.56%   +0.10%     
===========================================
  Files          344      344              
  Lines        24601    24645      +44     
  Branches     24601    24645      +44     
===========================================
+ Hits         20041    20102      +61     
+ Misses        4252     4238      -14     
+ Partials       308      305       -3     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.