Fix trace-file accumulation and Data Retention job failure (#972)

[erikdarlingdata]

Problem

The trace-file cleanup added in v2.11.0 (#951) failed the PerformanceMonitor - Data Retention Agent job on every run with Msg 22049 once any Monitor_LongQueries_*.trc files existed.

Root causes found while investigating #972:

1. xp_delete_file cannot delete .trc files at all — it only accepts SQL Server backup files and Maintenance Plan report files, and validates the file header. The [BUG] Trace files never get cleaned up #951 cleanup could never have worked.
2. The call passed a wildcard path as the folder argument, which raised an uncatchable Msg 22049 (extended-proc errors bypass TRY...CATCH) that failed the whole Agent job step.
3. The trace files accumulate because scheduled_master_collector issued RESTART every cycle (tearing down the trace and spawning a fresh timestamped one), and the trace was created with no rollover file-count cap.

Changes

• config.data_retention — removed the broken xp_delete_file block (the crash).
• collect.trace_management_collector — new @max_files parameter (default 5) → sp_trace_create @filecount, so SQL Server prunes old .trc files itself as the trace rolls. START now also replaces an unbounded trace left by an older version, so the fix self-heals without waiting for a SQL Server restart.
• scheduled_master_collector — calls START instead of RESTART; keeps one bounded trace running instead of orphaning files every cycle.
• tools/Remove-OrphanedTraceFiles.ps1 — new one-time cleanup for .trc files left on disk by versions ≤ 2.11.0; referenced from the README troubleshooting section.

No version bump (release-time step). CHANGELOG.md updated under [Unreleased].

Test plan

Tested live on SQL Server 2016 and 2019:

• Collector: @max_files = 1 → validation error; START → trace created with max_files = 5 and rollover on; START against an unbounded trace → replaced with a bounded one; START against a bounded trace → idempotent no-op; RESTART / STATUS / STOP all work.
• config.data_retention runs SUCCESS — Cleaned 51 tables, no Msg 22049.
• Remove-OrphanedTraceFiles.ps1: -WhatIf preview + real run deleted 181 (2019) / 280 (2016) orphaned files, correctly skipping the running trace's file and locked files.
• @filecount rollover-delete behavior verified against MS Learn sp_trace_create docs.
• All three existing callers of trace_management_collector use named parameters, so the new parameter is safe.

🤖 Generated with Claude Code