Logging and Monitoring

This document explains the plugin's logging system, how to read and manage log files, and how to use the built-in monitoring panels in the WordPress admin to track errors and warnings in production.

When to use this document

Read this document if you are a site administrator responsible for monitoring a live site, diagnosing unexpected behavior, or preparing information for a support request. It covers everything needed to understand, view, and maintain the plugin log.

Overview

The plugin writes all diagnostic output to a single flat log file stored in the WordPress uploads directory. The log captures import activity, API responses, image download results, cron events, and any errors or warnings that occur during plugin operation.

Access to the log is provided through the ADP Car Market Hub → Logs admin page, which presents:

• A Recent Errors panel showing the latest error-level entries
• A Recent Warnings panel showing the latest warning-level entries
• A Log Viewer for reading and clearing the raw log file

The System & Help tab (ADP Car Market Hub → System & Help) provides complementary system-level monitoring: API connectivity status, cron task schedules, PHP environment checks, and background task actions.

Requirements

• Administrator account with the manage_as24_imports capability.
• The WordPress uploads directory must be writable by the web server process for the log file to be created and written.

Log file location and format

The log file is written to:

{wp-uploads}/as24ci-logs/adp-car-market-hub.log

Where {wp-uploads} is the WordPress uploads base directory, typically wp-content/uploads/.

The log directory is automatically protected from public web access by an .htaccess file (for Apache) and a silent index.php file. Both are created when the directory is first set up by the plugin.

Each log line follows the format:

[YYYY-MM-DD HH:MM:SS UTC] [LEVEL] Message text

For example:

[2025-04-30 06:15:03 UTC] [INFO] Import runner (wp-cron): started.
[2025-04-30 06:15:47 UTC] [INFO] Import runner (wp-cron) finished: inserted=3 updated=12 skipped=85 errors=0
[2025-04-30 06:16:02 UTC] [INFO] Image queue worker: processed=30 errors=0 remaining=45

Log levels

Verbose logging

When verbose logging is enabled (the default), the importer writes an additional log line for every vehicle processed and every image action taken. This is useful for diagnosing import problems on small catalogues but can generate significant log volume on large ones.

Verbose logging is controlled by the Verbose logging option. To reduce log volume on large catalogues, disable verbose logging in the plugin settings.

When verbose logging is enabled, you will see lines such as:

[INFO] Import vehicle abc123 (seller 456) begin.
[INFO] Import vehicle abc123 result=updated.

Security masking in logs

The logger automatically masks sensitive values before writing them to disk:

• token=... query parameters are replaced with token=***
• client_secret=... parameters are replaced with client_secret=***
• Authorization: Bearer ... header values are replaced with Bearer ***

This means the log file does not contain API credentials or cron tokens even if they appear in a URL or request context.

Log rotation and archive management

The logger checks the log file size periodically (on the first call and every 100 log calls thereafter). When the file exceeds 10 MB, the current log file is moved to a timestamped archive in the same directory using the format:

adp-car-market-hub-YYYYMMDD-HHMMSS.log

A new empty active log file is then started automatically.

Archive files older than 7 days are automatically deleted on each rotation check.

If you need to retain log history longer than 7 days, copy archived log files to a separate storage location before they are purged.

Using the Logs admin page

Viewing recent errors and warnings

1. Open ADP Car Market Hub → Logs.
2. The Recent Errors panel shows the most recent entries containing [ERROR] from the last 2,000 lines of the log file (up to 50 entries).
3. The Recent Warnings panel shows the most recent entries containing [WARNING] from the same scan window.
4. If both panels are empty, no errors or warnings were found in the recent log history.

Viewing the raw log

1. On the same page, scroll down to the Log Viewer card.
2. The viewer displays the last 500 lines by default. Change the Lines field and click Reload to display a different number (100 to 2,000 lines).
3. Clicking anywhere in the log viewer text selects all visible content, making it easy to copy the log for external analysis.

Clearing the log file

1. In the Log Viewer toolbar, click Clear log file.
2. Confirm the dialog prompt. The file is truncated to empty and a single confirmation entry is written.
3. Clearing the log is a one-way action and cannot be undone. Take a copy first if you need to preserve the contents.

The clear button is only shown when the log file exists. If the file is not found or is not writable, a notice is displayed.

System & Help tab monitoring

The ADP Car Market Hub → System & Help page provides environment and connectivity monitoring:

Status badges use a traffic-light convention:

• Green (ok) — within recommended range
• Amber (warn) — acceptable but attention may be needed
• Red (bad) — outside recommended range; likely to cause issues

Diagnostics export

The System & Help tab includes a Download Diagnostics button that exports a ZIP (or JSON if ZipArchive is unavailable) containing system information useful for support requests. The export does not include credentials or private data.

Configuration reference

Operational notes

• If the uploads directory is not writable, the log file cannot be created and all log writes are silently dropped. The System & Help tab will show a warning for the uploads directory status.
• Log rotation is triggered by log writes, not by a separate scheduled task. If no logging occurs (for example, the site is idle), rotation will not run until the next log write.
• The log does not record frontend page views or analytics events. Those are stored in the {prefix}as24ci_analytics database table. See the Analytics tab for that data.
• On WordPress multisite installations, each site in the network has its own uploads directory and therefore its own separate log file.

Troubleshooting

Related documents

• Import Monitoring
• Daily Operation
• Update Process