feat(configuration): add configurable trace style and rename threshold to trace_filter

[josecelano]

Summary

Make the tracing logging style configurable from the configuration file. Replace the hardcoded TraceStyle::Default with a user-selectable option, and rename threshold to trace_filter for clarity and consistency with tracing crate terminology.

Closes #889

Changes

• Redesigned TraceStyle enum: Renamed Default → Full, simplified Pretty(bool) → Pretty (dropped display_filename boolean parameter)
• New config fields:
  • trace_filter (renamed from threshold) — filtering level for tracing output
  • trace_style — configurable output style: full (default), pretty, compact, json
• Updated v3 configuration to use the new logging options
• Documentation updates: issue spec progress, migration guide references, epic restructuring

Config example

[logging]
trace_filter = "info"
trace_style = "full"

Verification

Manual verification is deferred to #1980.

[Copilot]

Pull request overview

This pull request updates the configuration v3.0.0 logging schema to make the tracing output style configurable via TOML, aligning naming with tracing terminology by renaming threshold to trace_filter. It also updates multiple EPIC/issue docs to reflect the ongoing configuration-overhaul restructuring and introduces a v2→v3 migration guide.

Changes:

• Add [logging].trace_style (full/pretty/compact/json) and rename [logging].threshold → trace_filter in the v3 schema, wiring both into tracing initialization.
• Extend/adjust v3 configuration tests and add focused unit tests for trace-style deserialization + rejecting the removed threshold key.
• Documentation restructuring: EPIC path updates and a new configuration-v2-to-v3-migration.md guide.

Reviewed changes

Copilot reviewed 20 out of 20 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/configuration/src/v3_0_0/mod.rs	Updates v3 config examples + mandatory-option validation key from logging.threshold to logging.trace_filter; adjusts fixtures/tests accordingly.
packages/configuration/src/v3_0_0/logging.rs	Implements configurable trace_style, renames threshold to trace_filter, and adds unit tests for style parsing and legacy-key rejection.
docs/pr-reviews/pr-2021-copilot-suggestions.md	Updates tracked references to match EPIC spec path changes.
docs/issues/open/AGENTS.md	Updates examples to reflect EPIC specs living under .../EPIC.md.
docs/issues/open/889-1978-new-config-option-for-logging-style.md	Marks #889 implementation tasks complete and documents scope decisions.
docs/issues/open/2023-1978-expose-configured-public-urls-in-runtime-observability.md	Adds “update migration guide” task to the plan.
docs/issues/open/1987-add-config-option-to-use-ip-from-announce-query-string/ISSUE.md	Updates EPIC link path and adds “update migration guide” task.
docs/issues/open/1980-1978-configuration-overhaul-final-cleanup.md	Adds deferred manual verification tasks for #889 to #1980 plan.
docs/issues/open/1978-configuration-overhaul-epic/EPIC.md	Updates EPIC metadata/spec path, adds migration-guide link, and updates #889 status.
docs/issues/open/1978-configuration-overhaul-epic/configuration-v2-to-v3-migration.md	New migration guide documenting v2→v3 breaking changes and TODO sections for pending subissues.
docs/issues/open/1490-1978-decompose-database-config-and-overhaul-secrets.md	Adds “update migration guide” task to the plan.
docs/issues/open/1453-1978-ip-bans-reset-interval-configurable/ISSUE.md	Adds “update migration guide” task completion entry.
docs/issues/open/1415-1978-use-service-binding-instead-of-socket-addr/ISSUE.md	Adds “update migration guide” task completion entry.
docs/issues/open/1136-1978-configurable-udp-connection-id-validation-policy.md	Updates EPIC link path and adds “update migration guide” task completion entry.
docs/issues/closed/1985-rename-peer-addr-to-ip-in-http-announce-request/ISSUE.md	Updates EPIC link path.
docs/issues/closed/1981-1978-fix-tsl-config-tls-config-typo.md	Updates EPIC link path and adds “update migration guide” task completion entry.
docs/issues/closed/1979-1978-copy-configuration-schema-v2-to-v3-baseline.md	Adds “update migration guide” task completion entry.
docs/issues/closed/1640-1978-per-http-tracker-on-reverse-proxy-setting.md	Adds “update migration guide” task completion entry.
docs/issues/closed/1417-1978-add-public-service-url-to-configuration.md	Adds “update migration guide” task completion entry.
.github/skills/dev/planning/write-markdown-docs/SKILL.md	Adds filename-convention guidance for Markdown docs and issue/EPIC specs.

Comments suppressed due to low confidence (4)

packages/configuration/src/v3_0_0/logging.rs:20

• The doc comment lists Off, Error, etc., but Threshold uses #[serde(rename_all = "lowercase")], so the actual TOML values are lowercase (e.g. "info"). Align the comment with the real config values to avoid confusing users.

    /// Trace filter level. Possible values are: `Off`, `Error`, `Warn`, `Info`,
    /// `Debug` and `Trace`. Default is `Info`.

.github/skills/dev/planning/write-markdown-docs/SKILL.md:113

• The filename-convention table has a couple of misleading examples: it uses 889-.../ISSUE.md even though #889 is currently a standalone spec file, and it marks README as "lowercase". Using an actual folder-based issue spec example and marking README as UPPERCASE would make this table accurate and consistent with the surrounding text.

| Category       | Convention | Example                                                 |
| -------------- | ---------- | ------------------------------------------------------- |
| Templates      | UPPERCASE  | `.github/ISSUE_TEMPLATE/BUG_REPORT.md`                  |
| Issue spec     | UPPERCASE  | `1978-configuration-overhaul-epic/EPIC.md`              |
| Issue spec     | UPPERCASE  | `889-1978-new-config-option-for-logging-style/ISSUE.md` |

docs/issues/open/1978-configuration-overhaul-epic/configuration-v2-to-v3-migration.md:47

• This sentence suggests the tracker already rejects non-3.0.0 configs, but the same document later notes v2 compatibility is retained until #1980. It would be clearer to qualify this as the post-#1980 behavior when the runtime switches to v3 by default.

The tracker will reject configs with a schema version other than `3.0.0`.

docs/issues/open/1978-configuration-overhaul-epic/configuration-v2-to-v3-migration.md:160

• The note says omitting trace_filter falls back to the default info, but the v3 loader treats logging.trace_filter as a mandatory option (it errors if not provided). The doc should reflect that trace_filter must be present in a v3 config file.

> **Breaking**: The old `threshold` key is rejected by v3. If you omit
> `trace_filter`, the default is `info`.

---

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

[codecov]

Codecov Report

❌ Patch coverage is 91.54930% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 81.52%. Comparing base (1731994) to head (dec5bd8).

Files with missing lines	Patch %	Lines
packages/configuration/src/v3_0_0/logging.rs	87.50%	6 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #2037      +/-   ##
===========================================
+ Coverage    81.46%   81.52%   +0.05%     
===========================================
  Files          344      344              
  Lines        24601    24645      +44     
  Branches     24601    24645      +44     
===========================================
+ Hits         20041    20091      +50     
+ Misses        4252     4246       -6     
  Partials       308      308              

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

[josecelano]

ACK dec5bd8

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (6)

packages/configuration/src/v3_0_0/logging.rs:16

• #[allow(clippy::struct_excessive_bools)] is now redundant (the Logging struct has no boolean fields). Keeping unnecessary clippy suppressions makes it easier to miss real lint findings later; please remove it.

#[allow(clippy::struct_excessive_bools)]
#[derive(Serialize, Deserialize, PartialEq, Eq, Debug, Clone)]

packages/configuration/src/v3_0_0/logging.rs:26

• Similarly, trace_style is deserialized as lowercase strings; documenting the default/value as full (and listing supported values) is less ambiguous than Full.

    /// Trace output style. Default is `Full`.
    #[serde(default = "Logging::default_trace_style")]
    pub trace_style: TraceStyle,

packages/configuration/src/v3_0_0/logging.rs:22

• The doc comment lists Threshold values as Off, Error, ... but the enum is deserialized with #[serde(rename_all = "lowercase")], so config values should be documented as lowercase (matching the TOML examples).

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

    /// Trace filter level. Possible values are: `Off`, `Error`, `Warn`, `Info`,
    /// `Debug` and `Trace`. Default is `Info`.
    #[serde(default = "Logging::default_trace_filter")]
    pub trace_filter: Threshold,

packages/configuration/src/v3_0_0/logging.rs:124

• The display string uses "Json" rather than the conventional all-caps acronym "JSON".

            TraceStyle::Json => "Json Format",

.github/skills/dev/planning/write-markdown-docs/SKILL.md:117

• The filename-conventions table mixes EPIC and issue examples, and references a folder-based 889-.../ISSUE.md that doesn't exist (this issue spec is currently the single-file docs/issues/open/889-1978-new-config-option-for-logging-style.md). Updating the examples to reflect both EPIC specs and both issue-spec layouts would avoid confusing contributors.

| Issue spec     | UPPERCASE  | `1978-configuration-overhaul-epic/EPIC.md`              |
| Issue spec     | UPPERCASE  | `889-1978-new-config-option-for-logging-style/ISSUE.md` |
| Supporting doc | lowercase  | `1978-configuration-overhaul-epic/migration-guide.md`   |

docs/issues/open/1978-configuration-overhaul-epic/configuration-v2-to-v3-migration.md:27

• The migration guide quick-reference marks #889 as DONE, but the EPIC currently tracks it as IN_REVIEW (docs/issues/open/1978-configuration-overhaul-epic/EPIC.md:97). Consider aligning the status here so readers don't assume the change is already merged/released.

| No logging style option     | `[logging] trace_style`                                          | #889     | DONE      |
| `threshold`                 | `trace_filter`                                                   | #889     | DONE      |