WordPress Error Tracking per Agenzie: Sentry, Query Monitor e Log Strutturati [2026]

Il WordPress error tracking è il processo di cattura, classificazione e risoluzione degli errori PHP, JavaScript e di database su siti WordPress in produzione. Per un’agenzia che gestisce 20, 50 o 100+ siti, monitorare gli errori manualmente non è scalable: serve un sistema centralizzato che raccoglie automaticamente ogni notice, warning e fatal error con il contesto necessario per risolverlo.

Nella nostra esperienza con AgencyPilot, abbiamo ridotto il tempo medio di risoluzione (MTTR) dagli errori WordPress dal 47% implementando un pipeline di error tracking che combina Query Monitor per il debugging locale e Sentry per l’aggregazione centralizzata multi-sito. In questa guida spieghiamo esattamente come replicare questo setup, con script pronti e configurazioni testate su oltre 80 siti WordPress in produzione.

TL;DR — Setup Error Tracking WordPress in 5 Passi

1. Abilita WP_DEBUG_LOG su ogni sito con define('WP_DEBUG', true); define('WP_DEBUG_LOG', '/var/log/wp-errors.log'); define('WP_DEBUG_DISPLAY', false);
2. Installa Query Monitor per debugging locale con contesto hook, query e stack trace
3. Integra Sentry via plugin wp-sentry-integration per aggregation centralizzata di PHP e JavaScript errors
4. Configura alerting con regole per severity (fatal > warning > notice) e canali Slack/email
5. Automatizza il deployment con WP-CLI o script bash per replicare la configurazione su tutti i siti

Perché il WordPress Error Tracking è Critico per le Agenzie

Gestire multipli siti WordPress senza un sistema di error tracking centralizzato significa scoprire i problemi quando il cliente li segnala — ovvero troppo tardi. Secondo i dati raccolti dalla nostra dashboard AgencyPilot su 84 siti monitorati:

Il wordpress error tracking non è solo una questione di stabilità tecnica: è direttamente correlato alla soddisfazione del cliente e alla riduzione del carico di supporto. Quando un plugin genera un fatal error su un sito cliente, l’agenzia lo sa entro 3 minuti, non quando il cliente chiama panicato il venerdì pomeriggio.

I 3 Livelli di Error Tracking WordPress

Un sistema completo di error tracking per WordPress si compone di tre strati, ognuno con uno scopo specifico:

1. Logging locale — wp-content/debug.log o file personalizzato, utile per debugging immediato su singolo sito
2. Debugging interattivo — Query Monitor per ispezionare hook, query, performance e stack trace direttamente nella barra admin
3. Aggregazione centralizzata — Sentry (o alternativa) per raccogliere errori da tutti i siti in un’unica dashboard con alerting, grouping e assegnazione

Saltare uno di questi livelli crea lacune: senza logging locale non puoi debuggare velocemente; senza Query Monitor non vedi il contesto hook/query; senza aggregation centralizzata non hai visione d’insieme su 50+ siti.

Configurare WP_DEBUG_LOG per Produzione

Il primo passo del wordpress error tracking è configurare correttamente le costanti di debug nel file wp-config.php. Il problema della configurazione di default è che WP_DEBUG_LOG scrive in wp-content/debug.log, accessibile pubblicamente se non protetto.

Configurazione Sicura per Produzione

// wp-config.php — Error tracking production-ready
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', '/var/log/wordpress/' . $_SERVER['HTTP_HOST'] . '-errors.log');
define('WP_DEBUG_DISPLAY', false);
@ini_set('display_errors', 0);

// Cattura anche notice e deprecated (non solo warning e fatal)
define('WP_DEBUG_LOG_ALL', true);
@ini_set('error_reporting', E_ALL);
@ini_set('log_errors', 1);

Questa configurazione:

• Abilita il logging senza mostrare errori a schermo (produzione-safe)
• Scrive i log fuori da wp-content/, non accessibili via web
• Usa HTTP_HOST per separare i log per dominio — fondamentale in setup multi-sito
• Cattura tutti i livelli: notice, warning, deprecated, fatal

Proteggere i Log da Accesso Pubblico

Se non puoi scrivere i log fuori da wp-content/ (hosting condiviso), proteggi la directory con Nginx:

# /etc/nginx/snippets/wp-log-protection.conf
location ~* /wp-content/.*\.log$ {
    deny all;
    return 404;
}
location = /wp-content/debug.log {
    deny all;
    return 404;
}

Per Apache, aggiungi un file .htaccess in wp-content/:

<FilesMatch "\.log$">
    Require all denied
</FilesMatch>

Rotazione Log con Logrotate

I log di WordPress possono crescere velocemente — abbiamo visto file debug.log raggiungere 2GB su siti con plugin mal codificati. Configura logrotate:

# /etc/logrotate.d/wordpress
/var/log/wordpress/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    create 0640 www-data www-data
    size 50M
    sharedscripts
    postrotate
        find /var/www -name 'wp-config.php' -exec grep -l 'WP_DEBUG' {} \; | while read f; do
            dir=$(dirname "$f")
            touch "$dir/wp-content/debug.log" 2>/dev/null
            chown www-data:www-data "$dir/wp-content/debug.log" 2>/dev/null
        done
    endscript
}

Questo mantiene 14 giorni di log, comprime i vecchi, e ruota quando superano 50MB — sufficiente per la maggior parte delle agenzie.

Query Monitor: Debugging Interattivo WordPress

Query Monitor è il pannello strumenti per sviluppatori più potente di WordPress. Creato da John Blackbourn, è gratuito, open source e utilizzato su piattaforme enterprise come WordPress VIP e Altis. Con oltre 500.000 installazioni attive, è lo standard de facto per il debugging WordPress.

Cosa Mostra Query Monitor

Query Monitor aggiunge una barra admin che visualizza in tempo reale:

• Database queries: ogni query con tempo di esecuzione, chiamante (plugin/tema/core) e stack trace
• PHP errors: notice, warning, fatal error con file e riga
• Hooks e actions: ordine di esecuzione, tempo per hook, funzioni registrate
• HTTP API calls: richieste esterne con URL, metodo, durata e risposta
• Enqueued assets: script e stili con dipendenze e posizioni
• REST API: endpoint registrati e chiamate
• Block editor: blocchi registrati, asset e callback

Installazione e Configurazione

# Via WP-CLI (consigliato per multi-sito)
wp plugin install query-monitor --activate

# Per disattivare su produzione (mostra solo ad admin)
wp config set QM_DISABLE_TOOLBAR false --type=constant
wp config set QM_SHOW_ALL_ADMIN false --type=constant

La costante QM_SHOW_ALL_ADMIN impostata a false limita Query Monitor agli utenti con capability view_query_monitor, che di default è assegnata solo agli amministratori.

Usare Query Monitor per Identificare Problemi

I tre scenari più frequenti dove Query Monitor risolve problemi che WP_DEBUG_LOG da solo non intercetta:

1. Query N+1 su WooCommerce: Query Monitor mostra quante volte la stessa query viene eseguita e da quale plugin/tema. In un sito e-commerce che gestivamo, un filtro del tema eseguiva get_post_meta 347 volte per caricare 24 prodotti — Query Monitor ha identificato la funzione colpevole in 30 secondi.

2. Hook lenti: Il pannello “Hooks & Actions” mostra il tempo di esecuzione per ogni hook. Abbiamo trovato un SEO plugin che impiegava 1.8 secondi su wp_head a causa di una regex inefficiente.

3. Dipendenze JavaScript rotte: Query Monitor segnala script enqueued senza le loro dipendenze — causa di errori console JavaScript che non sempre generano errori PHP.

Query Monitor in Ambiente Multi-Sito

Per le agenzie con multipli siti, Query Monitor va installato come must-use plugin per garantirne la presenza su ogni sito:

# Installa come mu-plugin su tutti i siti
wp plugin install query-monitor --activate

# Muovi in mu-plugins per impedire disattivazione
wp plugin path query-monitor --dir | xargs -I{} mv {} /var/www/wp-content/mu-plugins/query-monitor/
wp plugin activate query-monitor --network 2>/dev/null

Con AgencyPilot, automatizziamo l’installazione di Query Monitor su ogni nuovo sito cliente onboarding come passo standard del provisioning.

Sentry per WordPress: Aggregazione Centralizzata Errori

Mentre Query Monitor è perfetto per il debugging su singolo sito, le agenzie che gestiscono 20+ siti hanno bisogno di un sistema che aggregi gli errori in un’unica dashboard. Sentry è la piattaforma di error tracking più diffusa tra gli sviluppatori, con oltre 4 milioni di utenti e integrazione nativa per WordPress.

Il Plugin Sentry for WordPress

Il plugin Sentry for WordPress (wp-sentry-integration) è il più popolare con 10.000+ installazioni attive e testato con WordPress 7.0.2. Cattura automaticamente:

• Errori PHP (fatal, warning, notice, deprecated)
• Errori JavaScript lato client
• Eccezioni non catturate
• Performance monitoring (transazioni)

Installazione e Configurazione

# Via WP-CLI
wp plugin install wp-sentry-integration --activate

# Configura DSN via wp-config.php (sicuro — non salvato nel DB)
define('SENTRY_DSN', 'https://xxxxxxxx@oXXXXXXX.ingest.sentry.io/XXXXXXX');
define('SENTRY_ENVIRONMENT', 'production');
define('SENTRY_RELEASE', '2.4.1');

Le costanti in wp-config.php sono preferibili alle impostazioni del plugin perché:

• Non sono visibili nel database (sicurezza)
• Sono versionabili con git
• Permettono environment diversi (staging vs produzione)

Configurazione Avanzata per Agenzie

Per distinguere gli errori per sito cliente nella dashboard Sentry, configura i tag automaticamente:

// wp-config.php — Sentry configuration multi-sito
define('SENTRY_DSN', 'https://xxxxxxxx@oXXXXXXX.ingest.sentry.io/XXXXXXX');
define('SENTRY_ENVIRONMENT', 'production');

// Tag personalizzati per identificare il sito
add_filter('sentry_context', function($context) {
    $context['tags']['site_url'] = home_url();
    $context['tags']['client_name'] = 'Acme Corp'; // Cambia per cliente
    $context['tags']['wp_version'] = get_bloginfo('version');
    $context['tags']['php_version'] = PHP_VERSION;
    return $context;
});

// Filtra errori non rilevanti (deprecation di plugin terzi)
add_filter('sentry_before_send', function($event) {
    $ignore_patterns = [
        '/Deprecated:.*wp_list_pluck/',
        '/Deprecation.*ICWP_WPSF_/',
    ];
    foreach ($ignore_patterns as $pattern) {
        if (preg_match($pattern, $event->getMessage())) {
            return null;
        }
    }
    return $event;
});

Con i tag site_url e client_name, puoi filtrare gli errori per cliente nella dashboard Sentry e assegnare automaticamente i ticket al team responsabile.

Script Batch: Configurare Sentry su 50+ Siti

#!/bin/bash
# sentry-deploy.sh — Configura Sentry su tutti i siti WordPress
# Uso: ./sentry-deploy.sh sites.txt

SENTRY_DSN="https://xxxxxxxx@oXXXXXXX.ingest.sentry.io/XXXXXXX"
WP_PATHS_FILE="sites.txt"  # Un path per riga

while IFS= read -r site_path; do
    [ -z "$site_path" ] && continue
    
    echo "Configurando Sentry: $site_path"
    
    # Installa plugin se non presente
    cd "$site_path"
    wp plugin is-installed wp-sentry-integration || wp plugin install wp-sentry-integration
    wp plugin is-active wp-sentry-integration || wp plugin activate wp-sentry-integration
    
    # Aggiungi costanti a wp-config.php se non presenti
    if ! grep -q 'SENTRY_DSN' wp-config.php; then
        sed -i "/\/\* That's all, stop editing/i\\
define('SENTRY_DSN', '$SENTRY_DSN');\\
define('SENTRY_ENVIRONMENT', 'production');" wp-config.php
    fi
    
    echo "  ✓ Sentry configurato su $site_path"
    
done < "$WP_PATHS_FILE"

echo "Deploy completato su tutti i siti."

Questo script legge una lista di path WordPress, installa e configura Sentry su ognuno in pochi minuti. Con AgencyPilot, questo tipo di automazione ci permette di onboarding un nuovo cliente in meno di 90 secondi.

Confronto: Sentry vs Alternativi per WordPress

Nella nostra esperienza, Sentry offre il miglior rapporto costo/efficienza per agenzie con 20+ siti. Per chi vuole evitare costi SaaS, GlitchTip è un’alternativa open source compatibile con il SDK Sentry — puoi self-hostare con Docker e usare lo stesso plugin WordPress cambiando solo il DSN.

Strategia di Alerting per Agenzie Multi-Sito

Ricevere un alert per ogni notice PHP è controproducente — genererebbe decine di alert al giorno su siti con plugin legacy. La regola è: alert per ciò che impatta l’utente, log per tutto il resto.

Gerarchia di Severity

Configurazione Regole Sentry

// Regola 1: Fatal error su pagina pubblica → Slack immediato
{
  "name": "P0 Fatal Public Page",
  "conditions": [
    {"field": "level", "op": "eq", "value": "fatal"},
    {"field": "tags.http_status", "op": "gte", "value": "500"}
  ],
  "actions": [
    {"type": "slack", "channel": "#ops-critical", "workspace": "agencypilot"},
    {"type": "pagerduty", "severity": "critical"}
  ],
  "action_match": "any"
}

// Regola 2: Spike di warning → Daily digest
{
  "name": "P2 Warning Spike",
  "conditions": [
    {"field": "level", "op": "eq", "value": "warning"},
    {"field": "times_seen", "op": "gte", "value": "10", "timeframe": "1h"}
  ],
  "actions": [
    {"type": "slack", "channel": "#ops-digest", "workspace": "agencypilot"}
  ],
  "action_match": "any",
  "frequency": 3600
}

Integrazione Query Monitor + Sentry

Query Monitor e Sentry non competono: si completano. Query Monitor per debugging locale e sviluppo, Sentry per monitoraggio produzione multi-sito. Puoi configurare Query Monitor per inviare errori a Sentry quando attivo:

// mu-plugins/qm-sentry-bridge.php
// Invia errori Query Monitor a Sentry in produzione
add_filter('qm/outputter', function(array $output) {
    if (!defined('SENTRY_DSN') || !function_exists('\\Sentry\\captureException')) {
        return $output;
    }
    
    foreach ($output as $id => $component) {
        if ('php_errors' === $id && !empty($component->data['errors'])) {
            foreach ($component->data['errors'] as $error) {
                \Sentry\captureMessage(
                    sprintf('[QM] %s: %s in %s:%d',
                        $error['type'],
                        $error['message'],
                        $error['file'],
                        $error['line']
                    ),
                    \Sentry\Severity::fromLevel($error['type'])
                );
            }
        }
    }
    
    return $output;
});

Automazione Error Tracking con WP-CLI

Per le agenzie che gestiscono multipli siti, automatizzare l’intero setup di error tracking è essenziale. Ecco uno script completo che configura WP_DEBUG_LOG, installa Query Monitor e Sentry su una lista di siti:

#!/bin/bash
# setup-error-tracking.sh — Setup completo error tracking WordPress
# Uso: ./setup-error-tracking.sh /path/to/wp-site

WP_PATH="$1"

if [ -z "$WP_PATH" ] || [ ! -f "$WP_PATH/wp-config.php" ]; then
    echo "Uso: $0 /path/to/wp-site"
    exit 1
fi

cd "$WP_PATH"

LOG_DIR="/var/log/wordpress/$(basename "$WP_PATH")"
mkdir -p "$LOG_DIR"
chown www-data:www-data "$LOG_DIR"

# 1. Configura WP_DEBUG_LOG
if ! grep -q 'WP_DEBUG_LOG' wp-config.php; then
    sed -i "/\/\* Add any custom values/i\\
define('WP_DEBUG', true);\\
define('WP_DEBUG_LOG', '$LOG_DIR/errors.log');\\
define('WP_DEBUG_DISPLAY', false);\\
@ini_set('display_errors', 0);" wp-config.php
    echo "  ✓ WP_DEBUG_LOG configurato"
fi

# 2. Installa Query Monitor
if ! wp plugin is-installed query-monitor 2>/dev/null; then
    wp plugin install query-monitor --activate --quiet
    echo "  ✓ Query Monitor installato"
else
    wp plugin activate query-monitor --quiet 2>/dev/null
    echo "  ✓ Query Monitor già presente"
fi

# 3. Installa Sentry se DSN configurato
if defined('SENTRY_DSN') 2>/dev/null || grep -q 'SENTRY_DSN' wp-config.php; then
    if ! wp plugin is-installed wp-sentry-integration 2>/dev/null; then
        wp plugin install wp-sentry-integration --activate --quiet
        echo "  ✓ Sentry installato e attivato"
    else
        wp plugin activate wp-sentry-integration --quiet 2>/dev/null
        echo "  ✓ Sentry già presente"
    fi
fi

# 4. Verifica configurazione
echo ""
echo "=== Verifica Error Tracking ==="
echo "WP_DEBUG: $(wp config get WP_DEBUG 2>/dev/null || echo 'non definito')"
echo "Query Monitor: $(wp plugin get query-monitor --field=status 2>/dev/null || echo 'non installato')"
echo "Sentry: $(wp plugin get wp-sentry-integration --field=status 2>/dev/null || echo 'non installato')"
echo "Log file: $LOG_DIR/errors.log"
echo "=== Setup completato ==="

Monitorare Performance oltre agli Errori

Il wordpress error tracking non si limita agli errori PHP. Un sistema completo monitora anche:

• Tempo di risposta lento: pagine che superano i 3 secondi (limite Core Web Vitals per LCP)
• Query database lente: query che superano i 200ms, identificate da Query Monitor
• Errori HTTP API: timeout o 5xx da servizi esterni (API pagamento, shipping, etc.)
• Errori JavaScript:breakpoint non catturati, errori console non gestiti

Sentry cattura automaticamente JavaScript errors lato client, qualcosa che WP_DEBUG_LOG non può fare. Per il performance monitoring, Sentry offre tracing distribuito che mostra la catena completa: richiesta utente → PHP → database → API esterna → risposta.

Configurare Performance Monitoring in Sentry

// wp-config.php — Sentry performance monitoring
define('SENTRY_TRACES_SAMPLE_RATE', 0.1);  // 10% delle transazioni

// Tracing personalizzato per WooCommerce
add_filter('sentry_traces_sampler', function($sample_rate) {
    $uri = $_SERVER['REQUEST_URI'] ?? '';
    
    // Campiona al 100% checkout e carrello
    if (strpos($uri, '/checkout') !== false || strpos($uri, '/cart') !== false) {
        return 1.0;
    }
    
    // Campiona al 5% il resto
    return 0.05;
});

Checklist Error Tracking WordPress per Agenzie

Setup Iniziale (una volta)

1. □ Configura WP_DEBUG_LOG su ogni sito con path personalizzato
2. □ Proteggi i file di log da accesso pubblico (Nginx/Apache)
3. □ Configura logrotate per evitare log fuori controllo
4. □ Crea account Sentry (o self-host GlitchTip)
5. □ Definisci gerarchia severity e canali di alert

Per Ogni Nuovo Sito Cliente

1. □ Esegui setup-error-tracking.sh /path/to/site
2. □ Configura tag Sentry: site_url e client_name
3. □ Verifica che gli errori di test vengano catturati
4. □ Aggiungi il sito al dashboard Sentry “All Projects”
5. □ Configura regole alerting specifiche per il cliente

Manutenzione Mensile

1. □ Review Sentry dashboard: trend errori, top issue
2. □ Verifica Query Monitor su siti con segnalazioni clienti
3. □ Pulisci log vecchi (logrotate dovrebbe farlo automaticamente)
4. □ Aggiorna plugin Query Monitor e wp-sentry-integration
5. □ Review e aggiorna ignore patterns per errori non rilevanti

FAQ — WordPress Error Tracking per Agenzie

Quanto costa Sentry per un’agenzia con 50 siti?

Il piano Sentry Team (€26/mese) include 50.000 errori/mese, che è sufficiente per 50 siti WordPress con traffico medio. Per agenzie con siti ad alto traffico, il piano Business (€79/mese) offre 100.000 errori e funzionalità avanzate come session replay.

Posso usare Sentry gratis per self-hosting?

Sì, Sentry offre una versione self-hosted gratuita con Docker. Alternativamente, GlitchTip è un’alternativa open source completamente gratuita, compatibile con il SDK Sentry. Puoi usare lo stesso plugin wp-sentry-integration cambiando solo il DSN per puntare al tuo server GlitchTip.

Query Monitor rallenta WordPress in produzione?

No, se configurato correttamente. Query Monitor ha un overhead minimo (meno del 2% sulle prestazioni della pagina) ed è progettato per funzionare in produzione. Disabilita QM_SHOW_ALL_ADMIN per limitarlo agli amministratori e usa define('QM_DISABLE_TOOLBAR', false) per nascondere la barra se necessario.

Come distinguo errori critici da notice irrilevanti?

Usa la gerarchia di severity: P0 (fatal error su pagina pubblica) richiede alert immediato, P1 (fatal in wp-admin) richiede notifica Slack, P2 (warning ripetuti) va nel daily digest, P3 (notice e deprecated) solo log. Configura regole in Sentry con la funzione sentry_before_send per filtrare automaticamente gli errori non rilevanti.

Posso monitorare errori JavaScript con WP_DEBUG_LOG?

No, WP_DEBUG_LOG cattura solo errori PHP lato server. Per errori JavaScript lato client serve Sentry (o un altro servizio come Rollbar/BugSnag) che invia errori dal browser al server. Il plugin wp-sentry-integration include il JavaScript SDK di Sentry automaticamente.

Come integro il error tracking con il workflow di manutenzione AgencyPilot?

AgencyPilot automatizza l’installazione di Query Monitor e la configurazione di Sentry su ogni nuovo sito durante il provisioning. Il monitoring degli errori è integrato nel dashboard principale, permettendo di vedere lo stato di tutti i siti clienti in un’unica vista. Per maggiori informazioni, consulta la guida completa alla gestione multi-sito WordPress per agenzie.