Traceable Logging Proposal
Flag semantics
Add a --trace flag to localpoc download. When present:
CLI prints timestamped timings for each major phase.
All API calls include header X-LocalPOC-Trace: 1 so the plugin logs matching phases to error_log().
When the flag is absent, behavior is unchanged (no extra logging).
CLI implementation
Argument parsing (Cli.php) – extend the option parser to detect --trace. Pass a boolean down to DownloadOrchestrator.
Trace helper (new cli/src/Localpoc/TraceLogger.php)
Lightweight class storing a monotonic start time.
Methods: section($name) returns closure to emit [timestamp] start/done (Δms); log($msg) prints [TRACE] lines to STDERR.
Integration points
Instantiate TraceLogger only when --trace is set; otherwise use a no-op stub.
Wrap key phases: DB job init/process/download, manifest init/iteration, file download batches, archive creation, cleanup.
Ensure Http::postJson/streamToFile append the trace header when flag is on.
Output
Trace lines go to STDERR so they don’t interfere with normal stdout (which still prints the archive summary).
Example line: [2024-11-17T10:42:31.512Z] DB chunk processed (4150 ms, +2.3 MB).
Plugin-side toggles
New helper (plugin/includes/class-trace-logger.php)
Singleton with is_enabled() (checks header HTTP_X_LOCALPOC_TRACE), section($name) (logs to error_log with timing), and log($msg).
Bootstrap
localpoc.php loads the helper.
In LocalPOC_Ajax_Handlers methods (db job init/process/download, manifest init/files, file batch zip) wrap the heavy sections with Trace_Logger::section('db_job_process').
In class-database-job-manager.php use the logger when reading metadata or writing chunks; no behavior change when trace is off.
Traceable Logging Proposal
Flag semantics
Add a --trace flag to localpoc download. When present:
CLI prints timestamped timings for each major phase.
All API calls include header X-LocalPOC-Trace: 1 so the plugin logs matching phases to error_log().
When the flag is absent, behavior is unchanged (no extra logging).
CLI implementation
Argument parsing (Cli.php) – extend the option parser to detect --trace. Pass a boolean down to DownloadOrchestrator.
Trace helper (new cli/src/Localpoc/TraceLogger.php)
Lightweight class storing a monotonic start time.
Methods: section($name) returns closure to emit [timestamp] start/done (Δms); log($msg) prints [TRACE] lines to STDERR.
Integration points
Instantiate TraceLogger only when --trace is set; otherwise use a no-op stub.
Wrap key phases: DB job init/process/download, manifest init/iteration, file download batches, archive creation, cleanup.
Ensure Http::postJson/streamToFile append the trace header when flag is on.
Output
Trace lines go to STDERR so they don’t interfere with normal stdout (which still prints the archive summary).
Example line: [2024-11-17T10:42:31.512Z] DB chunk processed (4150 ms, +2.3 MB).
Plugin-side toggles
New helper (plugin/includes/class-trace-logger.php)
Singleton with is_enabled() (checks header HTTP_X_LOCALPOC_TRACE), section($name) (logs to error_log with timing), and log($msg).
Bootstrap
localpoc.php loads the helper.
In LocalPOC_Ajax_Handlers methods (db job init/process/download, manifest init/files, file batch zip) wrap the heavy sections with Trace_Logger::section('db_job_process').
In class-database-job-manager.php use the logger when reading metadata or writing chunks; no behavior change when trace is off.