Add diagnostics feature

[marcelveldt]

What does this implement/fix?

Users reporting issues often need multiple back-and-forth rounds before we have enough info to help. This adds an always-on diagnostics facility: one privacy-safe report you can download and attach to a GitHub issue.

• Always-on capture (stdlib only, near-zero overhead): exceptions aggregated by fingerprint (count, first/last seen, one representative traceback) plus a bounded ring of recent warnings/errors.
• Report built only on request: system info (version, platform, memory, event loop lag, task/thread counts), install census (providers, player/library counts, non-default config key names only — never values), captured exceptions and optional log tail.
• Everything passing through the report is redacted: home dirs, media paths, URLs, tokens/passwords, e-mails, IP and MAC addresses. The sanitizer is the load-bearing part and is tested against adversarial fixtures.
• Access: admin-only diagnostics/get API command + authenticated GET /diagnostics download (JSON, or ?format=md for pasting into issues), served with content-disposition so the frontend can add a "download diagnostics" button.
• Extensible: providers and core controllers can implement get_diagnostics() to contribute a section; mass.diagnostics.register_section() for anything else (the upcoming profiler provider will plug in through this). Sections run with a 2s timeout and can't break the report.

Follow-ups (separate PRs): frontend settings button, issue template line asking for the attachment, profiler provider.

Redacted sample (from a live server with a deliberately broken provider)

{
  "type": "SetupFailedError",
  "fingerprint": "62c2b502e720",
  "count": 2,
  "logger": "music_assistant.webserver",
  "origin": "music_assistant/providers/filesystem_local/__init__.py:249 in handle_async_init",
  "message": "Error executing command config/providers/save: SetupFailedError: Music Directory /nonexistent/diag-test-library does not exist"
}

{"time": "2026-07-07T23:16:01+00:00", "level": "WARNING", "logger": "aiosendspin.server.connection.<mac-7f85b52c>", "message": "WebSocket closed, close_code=1006"}
{"time": "2026-07-07T23:15:53+00:00", "level": "WARNING", "logger": "music_assistant.streams", "message": "...Starting streamserver on <redacted-ip>:8097..."}

Related issue (if applicable):

• related issue N/A

Types of changes

• Bugfix (non-breaking change which fixes an issue) — bugfix
• New feature (non-breaking change which adds functionality) — new-feature
• Enhancement to an existing feature — enhancement
• New music/player/metadata/plugin provider — new-provider
• Breaking change (fix or feature that would cause existing functionality to not work as expected) — breaking-change
• Refactor (no behaviour change) — refactor
• Documentation only — documentation
• Maintenance / chore — maintenance
• CI / workflow change — ci
• Dependencies bump — dependencies

Checklist

• The code change is tested and works locally.
• pre-commit run --all-files passes.
• pytest passes, and tests have been added/updated under tests/ where applicable.
• For changes to shared models, the companion PR in music-assistant/models is linked.
• For changes affecting the UI, the companion PR in music-assistant/frontend is linked.
• I have read and complied with the project's AI Policy for any AI-assisted contributions.
• I have raised a PR against the documentation repository targeting the main or beta branch as appropriate.

[Copilot]

Pull request overview

This PR adds an always-on diagnostics facility that captures a bounded ring of WARNING+ logs and aggregates exception fingerprints, and exposes an admin-only API/HTTP download endpoint to generate a privacy-redacted diagnostics report on demand.

Changes:

• Introduces always-on capture + sanitization helpers, plus an on-demand diagnostics report builder/controller with pluggable sections.
• Adds get_diagnostics() hooks on core controllers/providers and wires the diagnostics controller into startup, API command registration, and the webserver route table.
• Adds comprehensive tests covering sanitization, bounded capture behavior, section isolation/timeouts, and authz/formatting for the download endpoint.

Reviewed changes

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

Show a summary per file

File	Description
tests/core/test_diagnostics.py	Adds end-to-end and unit tests for capture, sanitization, section collection, and HTTP/API access control.
music_assistant/models/provider.py	Adds optional get_diagnostics() hook for providers.
music_assistant/models/core_controller.py	Adds optional get_diagnostics() hook for core controllers.
music_assistant/mass.py	Installs capture early, instantiates/sets up the diagnostics controller, and registers its API commands.
music_assistant/helpers/logging.py	Ensures the diagnostics capture handler stays on the root logger (not migrated into the queue handler).
music_assistant/helpers/diagnostics.py	Implements always-on bounded capture and sanitization primitives (stdlib-only).
music_assistant/controllers/webserver/controller.py	Registers authenticated /diagnostics download route.
music_assistant/controllers/streams/controller.py	Implements get_diagnostics() contribution for streams controller.
music_assistant/controllers/diagnostics/init.py	New diagnostics controller to assemble/redact reports and manage pluggable sections.
music_assistant/main.py	Installs diagnostics capture handler early during logger setup.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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