Add phase labels and structured fields to config-load observability (#304)

[leynos]

Summary

Closes #304

Extends the #303 config-load instrumentation with per-phase metric labels and structured error-log fields, the additional observability the review audit identified.

Stacked on #379 (#303); retargets to main automatically once #379 merges.

Changes

• src/main.rs:
  • record_config_load_phase records the diag_mode and merge phases separately, adding a phase label to netsuke_config_load_total (with outcome) and netsuke_config_load_duration_seconds.
  • handle_config_load_error annotates the configuration load failed event with operation = "config_merge" and an error_category (parse/io/validation/aggregate/other) derived from the OrthoError variant via the new const fn error_category.
• docs/developers-guide.md: per-phase label documentation plus a new Structured log fields subsection documenting the operation/error_category/error contract and the JSON-mode exception.

Testing

• Unit tests assert the phase/outcome labels on the counter and histogram and the error_category classification for representative OrthoError variants.

Validation

• make check-fmt / make markdownlint / make lint / make test — pass (37 suites)

🤖 Generated with Claude Code

Summary by Sourcery

Add per-phase observability to configuration loading and enrich error logging for config-load failures.

New Features:

• Expose configuration-load metrics per phase with phase and outcome labels on existing counter and duration histogram.
• Emit structured error logs for configuration-load failures including operation name and coarse error category.

Enhancements:

• Refine configuration resolution flow to record separate diagnostic-mode and merge phases with fixed-label values for metrics.
• Introduce a helper to classify configuration-load errors into bounded categories for easier operational filtering.

Documentation:

• Document per-phase configuration-load metrics and their labels in the developer guide.
• Describe the structured log fields emitted on configuration-load failures and clarify their applicability to human-output vs JSON modes.

Tests:

• Extend metrics tests to cover phase and outcome labels on config-load metrics and add tests for error category classification.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 39e6d12b-8c89-457f-88de-b903fff3348c

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch issue-304-config-load-observability

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sourcery-ai]

Reviewer's Guide

Adds per-phase metrics labeling and structured error logging for configuration loading, splitting diagnostic-mode and merge phases and documenting the new observability contract.

Sequence diagram for per-phase config-load metrics

sequenceDiagram
    participant Main
    participant resolve_configuration
    participant cli_resolve_merged_diag_json as cli::resolve_merged_diag_json
    participant cli_merge_with_config as cli::merge_with_config
    participant record_config_load_phase

    Main->>resolve_configuration: resolve_configuration(parsed_cli, matches)
    activate resolve_configuration

    resolve_configuration->>cli_resolve_merged_diag_json: resolve_merged_diag_json(parsed_cli, matches)
    cli_resolve_merged_diag_json-->>resolve_configuration: mode_json_enabled

    resolve_configuration->>record_config_load_phase: record_config_load_phase(PHASE_DIAG_MODE, diag_elapsed, true)

    resolve_configuration->>cli_merge_with_config: merge_with_config(parsed_cli, matches)
    cli_merge_with_config-->>resolve_configuration: merged_result

    resolve_configuration->>record_config_load_phase: record_config_load_phase(PHASE_MERGE, merge_elapsed, merged_result.is_ok())
    resolve_configuration-->>Main: (mode, merged_result)
    deactivate resolve_configuration

Loading

Sequence diagram for structured error logging on config-load failure

sequenceDiagram
    participant Main
    participant handle_config_load_error
    participant error_category
    participant tracing_error as tracing::error

    Main->>handle_config_load_error: handle_config_load_error(err, mode)
    activate handle_config_load_error

    alt mode.is_json()
        handle_config_load_error-->>Main: diagnostic_json::emit_or_fallback(...)
    else human_output_mode
        handle_config_load_error->>error_category: error_category(err)
        error_category-->>handle_config_load_error: category
        handle_config_load_error->>tracing_error: error!(error=%err, operation="config_merge", error_category=category, ...)
        tracing_error-->>handle_config_load_error: event_recorded
        handle_config_load_error-->>Main: ExitCode::FAILURE
    end

    deactivate handle_config_load_error

Loading

File-Level Changes

Change	Details	Files
Split configuration-load observability into per-phase metrics with phase labels and updated tests.	Refactored configuration resolution to measure diagnostic-mode and merge phases separately with distinct start times. Replaced record_config_load_metrics with record_config_load_phase, adding a phase label to both the duration histogram and outcome counter. Introduced PHASE_DIAG_MODE and PHASE_MERGE constants and used them when recording metrics. Updated unit tests to assert presence of phase and outcome labels on the counter and histogram and adjusted test names accordingly, adding a small label-search helper.	src/main.rs
Add structured error logging for configuration-load failures with coarse error categorization.	Introduced const fn error_category that maps OrthoError variants into coarse categories (parse, io, validation, aggregate, other). Extended handle_config_load_error to emit structured tracing::error! fields: error, operation="config_merge", and error_category derived from the OrthoError. Added a dedicated test to verify error_category classification for representative OrthoError variants.	src/main.rs
Update developer documentation to describe new per-phase metrics and structured log fields for config-load failures.	Rewrote metrics documentation to describe record_config_load_phase semantics, including phase/outcome label combinations and recommended usage for failure rate calculations. Clarified duration histogram semantics as per-phase samples and reaffirmed bucket recommendations and cardinality constraints. Added a new "Structured log fields" subsection documenting operation/error_category/error fields and the JSON-mode exception for human vs machine-readable output.	docs/developers-guide.md

Possibly linked issues

• Improve observability of config-load error paths: structured log fields, metrics by phase #304: PR implements structured log fields, per-phase metrics, histograms, and documentation exactly as requested in issue Improve observability of config-load error paths: structured log fields, metrics by phase #304.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.