Publish runtime metrics and byte-weighted progress via System.Diagnostics.Metrics

[ptr727]

Implements #848 (v1).

What

Adds an always-on System.Diagnostics.Metrics meter (PlexCleaner.Process) so a long-running process/monitor pass can be inspected live with dotnet-counters — no config flag, no extra infrastructure (instruments are inert until observed). Overall progress is weighted by input bytes, not file count, so a run mixing tiny and huge files reports the actual work completed.

Design

• Metrics.cs owns the meter, all instruments, and Interlocked run-scoped state. Observable-gauge callbacks only read, so the parallel loop needs no lock. Tags are bounded (state, tool) — no filename tags (cardinality).
• ProcessDriver.ProcessFiles (the choke point every command and monitor cycle funnels through) drives files/bytes/in-flight, the byte-weighted progress.ratio and eta.seconds, and file.duration. Input sizes are summed once up front and the same size is credited at completion, so a remux/rename mid-run can't drift the total. Run-scoped gauges reset per pass; counters stay cumulative for rate display.
• Process.ProcessFiles records per-SidecarFile.StatesType outcomes; MediaTool execution paths and the ffprobe packet reader record tool.duration.

Instruments

files.total/completed/modified/errors/verifyfailed, files.processed{state}, files.inflight, threads.active, bytes.total/completed, progress.ratio, eta.seconds, file.duration, tool.duration{tool}.

Scope (v1)

In-flight files get no partial credit until they finish. Per-file child-process progress (ffmpeg -progress, mkvmerge --gui-mode, ffprobe pts-advance) feeding partial credit is a metrics-only v2 follow-up. No status.json — metrics are the sole surface.

Reading it

• Local: dotnet-counters monitor -p <pid> PlexCleaner.Process
• Docker: docker exec <container> counters — a bundled wrapper (Docker/counters.sh) that sets the self-extract dir and targets PID 1.

Notes

• Zero new NuGet packages — System.Diagnostics.Metrics is in the BCL; System.Diagnostics.DiagnosticSource.dll already ships transitively.
• Unit tests (MetricsTests.cs) cover the byte-weighted math, ETA guards, flag enumeration, and a MeterListener end-to-end assertion — no media files. Full suite 226/226.
• Minor version bump 3.21 → 3.22 (additive, backward-compatible).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds an always-on System.Diagnostics.Metrics meter (PlexCleaner.Process) to expose live runtime/process progress (byte-weighted) and tool/file timing via dotnet-counters, implementing #848.

Changes:

• Introduces PlexCleaner.Process metrics (Metrics.cs) with counters/gauges/histograms for files/bytes/progress/ETA and tool + per-file durations.
• Integrates metrics updates at key choke points: ProcessDriver.ProcessFiles, Process.ProcessFiles, MediaTool execution, and ffprobe packet scanning.
• Documents usage (README/ARCHITECTURE/HISTORY) and adds a Docker counters wrapper plus unit tests validating byte-weighted math and observability.

Reviewed changes

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

Show a summary per file

File	Description
version.json	Bumps version floor to 3.22.
README.md	Adds Runtime Metrics section + usage examples.
HISTORY.md	Adds 3.22 changelog entry describing metrics feature.
ARCHITECTURE.md	Documents metrics architecture and hook points.
PlexCleaner/Metrics.cs	New meter/instruments + run-scoped state and computations.
PlexCleaner/ProcessDriver.cs	Computes size totals and records per-file progress/ETA inputs and durations.
PlexCleaner/Process.cs	Records per-outcome state/modified/verifyfailed metrics.
PlexCleaner/MediaTool.cs	Records per-tool execution duration metrics.
PlexCleaner/FfProbeTool.cs	Records ffprobe packet-scan duration as tool time.
PlexCleaner/Program.cs	Disposes the meter on shutdown.
PlexCleanerTests/MetricsTests.cs	Adds unit tests for progress/ETA/flag enumeration and listener observability.
Docker/Dockerfile	Installs counters wrapper into the image.
Docker/counters.sh	Wrapper script for dotnet-counters targeting PID 1 with a writable extract dir.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

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

Comments suppressed due to low confidence (1)

PlexCleaner/ProcessDriver.cs:223

• Cancellation is checked before incrementing processedCount and before recording FileCompleted. If a cancellation is requested after taskFunc returns but before this check, the file has already finished but metrics (bytes.completed, files.completed, file.duration) and the processedCount-based percentage won't reflect it, making progress/ETA under-report completed work on interrupted runs. Consider deferring ThrowIfCancellationRequested until after recording completion for this file.

                        // Handle cancel request
                        Program.CancelToken().ThrowIfCancellationRequested();

[Copilot]

Pull request overview

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