Documentazione · Operazioni e manutenzione

Registrazione e monitoraggio

Questo documento spiega il sistema di log del plugin, come leggere e gestire i file di log e come utilizzare i pannelli di monitoraggio integrati nell'amministrazione di WordPress per tracciare errori e avvisi in produzione.

Quando utilizzare questo documento

Leggi questo documento se sei un amministratore del sito responsabile del monitoraggio di un sito live, della diagnosi di comportamenti imprevisti o della preparazione di informazioni per una richiesta di supporto. Copre tutto il necessario per comprendere, visualizzare e mantenere il log del plugin.

Panoramica

Il plugin scrive tutti i dati diagnostici in un singolo file di log flat memorizzato nella directory uploads di WordPress. Il log acquisisce l'attività di importazione, le risposte API, i risultati del download delle immagini, gli eventi cron e qualsiasi errore o avviso che si verifica durante il funzionamento del plugin.

L'accesso al log è fornito tramite la pagina di amministrazione ADP Car Market Hub → Logs, che presenta:

Un pannello Errori recenti che mostra le voci più recenti con livello di errore
Un pannello Avvisi recenti che mostra le voci più recenti con livello di avviso
Un Visualizzatore di log per leggere e svuotare il file di log non elaborato

La scheda System & Help (ADP Car Market Hub → System & Help) fornisce un monitoraggio complementare a livello di sistema: stato della connettività API, pianificazione delle attività cron, controlli dell'ambiente PHP e azioni delle attività in background.

Requisiti

Account amministratore con la funzionalità manage_as24_imports.
La directory uploads di WordPress deve essere scrivibile dal processo del server web affinché il file di log possa essere creato e scritto.

Posizione e formato del file di log

Il file di log viene scritto in:

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

Dove {wp-uploads} è la directory di base degli uploads di WordPress, in genere wp-content/uploads/.

La directory dei log è protetta automaticamente dall'accesso web pubblico da un file .htaccess (per Apache) e da un file index.php silenzioso. Entrambi vengono creati quando la directory viene configurata per la prima volta dal plugin.

Ogni riga di log segue il formato:

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

Ad esempio:

[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

Livelli di log

Livello	Quando viene utilizzato
`INFO`	Funzionamento normale: importazione avviata/completata, avanzamento della coda delle immagini, eventi di configurazione
`WARNING`	Funzionamento degradato: errori di download delle immagini, rilevamento di lock obsoleti, fallback della conversione WebP
`ERROR`	Errori che richiedono attenzione: errori API, sideload dei media non riusciti, errori di salvataggio dei post
`DEBUG`	Messaggi diagnostici dettagliati (registrati solo quando si verificano condizioni specifiche, come l'uso dell'autenticazione tramite token con parametro di query)

Registrazione dettagliata (Verbose logging)

Quando la registrazione dettagliata è abilitata (impostazione predefinita), l'importatore scrive una riga di log aggiuntiva per ogni veicolo elaborato e per ogni azione eseguita sulle immagini. Questo è utile per diagnosticare problemi di importazione su cataloghi di piccole dimensioni, ma può generare un volume di log significativo su quelli grandi.

La registrazione dettagliata è controllata dall'opzione Verbose logging. Per ridurre il volume dei log sui cataloghi di grandi dimensioni, disabilita la registrazione dettagliata nelle impostazioni del plugin.

Quando la registrazione dettagliata è abilitata, vedrai righe come:

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

Mascheramento di sicurezza nei log

Il logger maschera automaticamente i valori sensibili prima di scriverli su disco:

I parametri di query token=... vengono sostituiti con token=***
I parametri client_secret=... vengono sostituiti con client_secret=***
I valori dell'intestazione Authorization: Bearer ... vengono sostituiti con Bearer ***

Ciò significa che il file di log non contiene credenziali API o token cron anche se appaiono in un URL o nel contesto di una richiesta.

Rotazione dei log e gestione dell'archivio

Il logger controlla periodicamente la dimensione del file di log (alla prima chiamata e successivamente ogni 100 chiamate di log). Quando il file supera i 10 MB, il file di log corrente viene spostato in un archivio con timestamp nella stessa directory utilizzando il formato:

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

Un nuovo file di log attivo vuoto viene quindi avviato automaticamente.

I file di archivio più vecchi di 7 giorni vengono eliminati automaticamente a ogni controllo di rotazione.

Se hai bisogno di conservare la cronologia dei log per più di 7 giorni, copia i file di log archiviati in una posizione di archiviazione separata prima che vengano eliminati.

Utilizzo della pagina di amministrazione Logs

Visualizzazione degli errori e degli avvisi recenti

Apri ADP Car Market Hub → Logs.
Il pannello Errori recenti mostra le voci più recenti contenenti [ERROR] dalle ultime 2.000 righe del file di log (fino a 50 voci).
Il pannello Avvisi recenti mostra le voci più recenti contenenti [WARNING] dalla stessa finestra di scansione.
Se entrambi i pannelli sono vuoti, non sono stati trovati errori o avvisi nella cronologia recente dei log.

Visualizzazione del log non elaborato

Nella stessa pagina, scorri verso il basso fino alla scheda Visualizzatore di log.
Il visualizzatore mostra le ultime 500 righe per impostazione predefinita. Modifica il campo Righe e fai clic su Ricarica per visualizzare un numero diverso (da 100 a 2.000 righe).
Facendo clic in un punto qualsiasi del testo del visualizzatore di log si seleziona tutto il contenuto visibile, semplificando la copia del log per l'analisi esterna.

Svuotare il file di log

Nella barra degli strumenti del Visualizzatore di log, fai clic su Svuota file di log.
Conferma la richiesta della finestra di dialogo. Il file viene svuotato e viene scritta una singola voce di conferma.
Lo svuotamento del log è un'azione unidirezionale e non può essere annullata. Fai una copia prima se hai bisogno di conservarne il contenuto.

Il pulsante per svuotare il log viene mostrato solo quando il file di log esiste. Se il file non viene trovato o non è scrivibile, viene visualizzato un avviso.

Monitoraggio della scheda System & Help

La pagina ADP Car Market Hub → System & Help fornisce il monitoraggio dell'ambiente e della connettività:

Sezione	Cosa mostra
Connettività e API	Raggiungibilità e codice di risposta dell'endpoint API di AutoScout24, stato e scadenza del token OAuth, raggiungibilità dell'endpoint cron della REST API, raggiungibilità dell'API di Market Hub
Attività in background	Nomi degli hook di WP-Cron, pianificazione, ora della prossima esecuzione, stato del lock e pulsanti di attivazione manuale per il processo di importazione, il worker della coda delle immagini, la pulizia degli analytics e l'analisi dei prezzi
Requisiti del plugin	Versione di PHP, estensioni PHP (mbstring, JSON, OpenSSL, cURL, GD/Imagick, ZipArchive), versione di WordPress
Ambiente	Limite di memoria PHP e tempo massimo di esecuzione con badge di stato codificati a colori; scrivibilità della directory uploads; spazio su disco

I badge di stato utilizzano una convenzione a semaforo:

Verde (ok) — entro l'intervallo raccomandato
Arancione (avviso) — accettabile ma potrebbe essere necessaria attenzione
Rosso (critico) — al di fuori dell'intervallo raccomandato; probabile causa di problemi

Esportazione della diagnostica

La scheda System & Help include un pulsante Scarica diagnostica che esporta un file ZIP (o JSON se ZipArchive non è disponibile) contenente informazioni di sistema utili per le richieste di supporto. L'esportazione non include credenziali o dati privati.

Riferimento di configurazione

Opzione	Predefinito	Scopo
Registrazione dettagliata	Attivo (1)	Registra una riga per ogni veicolo e ogni azione sulle immagini durante l'importazione
Percorso del file di log	`{uploads}/as24ci-logs/adp-car-market-hub.log`	Fisso; basato sulla directory uploads di WordPress
Dimensione massima del file di log prima della rotazione	10 MB	Hard-coded nella classe Logger
Conservazione dell'archivio dei log	7 giorni	Hard-coded nella classe Logger
Righe predefinite del Visualizzatore di log	500	Regolabile nell'interfaccia utente (100–2.000)

Note operative

Se la directory uploads non è scrivibile, il file di log non può essere creato e tutte le scritture di log vengono eliminate silenziosamente. La scheda System & Help mostrerà un avviso per lo stato della directory uploads.
La rotazione dei log è attivata dalle scritture dei log, non da un'attività pianificata separata. Se non si verifica alcuna registrazione (ad esempio, il sito è inattivo), la rotazione non verrà eseguita fino alla successiva scrittura di log.
Il log non registra le visualizzazioni delle pagine frontend o gli eventi di analisi. Questi sono memorizzati nella tabella del database {prefix}as24ci_analytics. Consulta la scheda Analytics per questi dati.
Sulle installazioni multisito di WordPress, ogni sito della rete ha la propria directory uploads e quindi il proprio file di log separato.

Risoluzione dei problemi

Sintomo	Causa probabile	Controllo
Messaggio "File di log non trovato" nella scheda Logs	Directory dei log non scrivibile o nessuna importazione è stata ancora eseguita	Controlla i permessi della directory uploads nella scheda System & Help; avvia un'importazione manuale
Messaggio "Impossibile svuotare il file di log"	File di log non scrivibile dal server web	Controlla i permessi del file system sulla directory `as24ci-logs/`
La scheda Logs non mostra errori recenti ma le importazioni falliscono	Registrazione dettagliata disabilitata o gli errori non raggiungono il logger	Abilita la registrazione dettagliata; controlla il log degli errori di PHP per individuare errori fatali
Il file di log diventa molto grande	Registrazione dettagliata attiva su un catalogo di grandi dimensioni	Disabilita la registrazione dettagliata nelle impostazioni del plugin
Protezione `.htaccess` non funzionante su nginx	`.htaccess` è solo per Apache	Aggiungi regole nginx equivalenti per bloccare l'accesso diretto alla directory dei log
I file di log archiviati si accumulano oltre i 7 giorni	La rotazione dei log non viene eseguita (il sito è inattivo)	Attiva un'importazione manuale per eseguire un controllo di rotazione