---
title: "Osservabilità minima per applicazioni PHP legacy: logging strutturato, metriche essenziali e alert senza riscrivere il codice"
description: "Osservabilità su PHP legacy senza rewrite: Monolog JSON, error_log centralizzato, metriche con cron e alert Telegram. Da \"scopro dal cliente\" a \"scopro prima del cliente\"."
canonical: "https://www.mauriziofonte.it/blog/post/osservabilita-minima-applicazioni-php-legacy-logging-metriche-alert.html"
author: "Maurizio Fonte"
date: "2025-09-10T07:45:13+02:00"
modified: "2026-04-14T17:48:55+02:00"
section: "DevOps"
tags: ["DevOps", "Refactoring"]
license: "Riuso e citazione consentiti con attribuzione e link alla fonte"
---

[DevOps](https://www.mauriziofonte.it/blog/cat/devops.html) [Refactoring](https://www.mauriziofonte.it/blog/cat/refactoring.html)

# [Osservabilità minima per applicazioni PHP legacy: logging strutturato, metriche essenziali e alert senza riscrivere il codice](https://www.mauriziofonte.it/blog/post/osservabilita-minima-applicazioni-php-legacy-logging-metriche-alert.html)

Mercoledì 10 Settembre 2025, alle 07:45 ![Osservabilità minima per applicazioni PHP legacy: logging strutturato, metriche essenziali e alert senza riscrivere il codice](https://www.mauriziofonte.it/image/002280200-osservabilita-minima-applicazioni-php-legacy-logging-metriche-alert.jpg)

A dicembre 2024, su un gestionale PHP 7.2 di un cliente piemontese - azienda di distribuzione ricambi con 15 operatori - il pattern era sempre lo stesso: il titolare riceveva una telefonata da un cliente ("il sito non funziona"), chiamava me, e io iniziavo a investigare. Il tempo medio dalla telefonata del cliente alla risoluzione era circa 4 ore - non perché il fix fosse complesso, ma perché la diagnosi era un incubo. I log erano un `error_log` di PHP che mescolava notice, warning e fatal error in un unico file non strutturato da 2 GB, senza timestamp leggibili, senza contesto (quale utente? quale pagina? quale query?), e senza nessun meccanismo di alert. Scoprivo i problemi quando il danno era già fatto.

In cinque giorni ho introdotto osservabilità minima - logging strutturato in JSON, metriche operative raccolte da cron, e alert via Telegram per errori critici - senza toccare una riga di codice applicativo. Il MTTR (Mean Time To Recovery) è sceso da 4 ore a 22 minuti. In questo articolo ti racconto come, perché il metodo funziona su qualsiasi applicazione PHP legacy indipendentemente dal framework (o dall'assenza di framework).

> Stai cercando un **Consulente Informatico** esperto per introdurre osservabilità sulla tua applicazione PHP? Nel mio [profilo professionale](https://www.mauriziofonte.it/pages/about) trovi l'esperienza concreta su logging, monitoring e incident response per PMI. [Contattami per una consulenza diretta](https://www.mauriziofonte.it/pages/contattami).

## Perché i log di default di PHP sono inutili per la diagnosi?

Il logging di default di PHP - `error_log` con `display_errors Off` e `log_errors On` - scrive errori in un formato non strutturato, senza contesto e senza separazione per severità. Un file `error_log` dopo sei mesi di produzione contiene migliaia di notice irrilevanti mescolate a errori critici, e trovare quello che ti serve è come cercare un ago in un pagliaio.

Il problema fondamentale è che `error_log` registra cosa è successo ma non il contesto: non sai quale utente stava facendo cosa, quale URL ha generato l'errore, quale query era in esecuzione, o quanto tempo ha impiegato la richiesta. Senza contesto, la diagnosi richiede la riproduzione manuale del problema - che su un sistema legacy con dati di produzione è spesso impossibile.

## Il primo intervento: logging strutturato in JSON con Monolog

[Monolog](https://github.com/Seldaek/monolog) è la libreria di logging standard per PHP - è il componente usato da Laravel e Symfony, ma funziona perfettamente anche su applicazioni PHP plain senza framework. L'installazione via Composer è l'unica modifica al progetto:

```bash
composer require monolog/monolog
```

Il file di bootstrap che aggiungo - un singolo `require` all'inizio del punto di ingresso dell'applicazione:

```php
<?php
// bootstrap_logging.php - includere PRIMA di qualsiasi altro codice
require_once __DIR__ . '/vendor/autoload.php';

use Monolog\Logger;
use Monolog\Handler\StreamHandler;
use Monolog\Handler\RotatingFileHandler;
use Monolog\Formatter\JsonFormatter;

$logger = new Logger('app');

// Handler: file JSON con rotazione giornaliera, retention 30 giorni
$handler = new RotatingFileHandler(__DIR__ . '/logs/app.log', 30, Logger::WARNING);
$handler->setFormatter(new JsonFormatter());
$logger->pushHandler($handler);

// Handler separato per errori critici
$criticalHandler = new StreamHandler(__DIR__ . '/logs/critical.log', Logger::CRITICAL);
$criticalHandler->setFormatter(new JsonFormatter());
$logger->pushHandler($criticalHandler);

// Registrare come error handler globale di PHP
set_error_handler(function ($errno, $errstr, $errfile, $errline) use ($logger) {
    $logger->warning($errstr, [
        'file' => $errfile,
        'line' => $errline,
        'errno' => $errno,
        'url' => $_SERVER['REQUEST_URI'] ?? 'cli',
        'user_ip' => $_SERVER['REMOTE_ADDR'] ?? 'unknown',
    ]);
    return false;  // continua con il default error handler
});

// Catturare eccezioni non gestite
set_exception_handler(function ($exception) use ($logger) {
    $logger->critical($exception->getMessage(), [
        'file' => $exception->getFile(),
        'line' => $exception->getLine(),
        'trace' => $exception->getTraceAsString(),
        'url' => $_SERVER['REQUEST_URI'] ?? 'cli',
        'user_ip' => $_SERVER['REMOTE_ADDR'] ?? 'unknown',
    ]);
});

// Rendere il logger disponibile globalmente
$GLOBALS['app_logger'] = $logger;
```

Questo singolo file, incluso con `require_once 'bootstrap_logging.php'` nel punto di ingresso dell'applicazione, trasforma il logging da "error_log non strutturato" a "JSON con contesto, rotazione e separazione per severità". Il file `logs/app.log` contiene righe JSON parsabili con `jq`:

```bash
# Cercare errori critici dell'ultima ora
cat logs/critical.log | jq 'select(.datetime > "2025-12-15T10:00:00")'

# Errori raggruppati per URL
cat logs/app.log | jq -r '.context.url' | sort | uniq -c | sort -rn | head -10

# Errori di un utente specifico
cat logs/app.log | jq 'select(.context.user_ip == "93.XX.XX.XX")'
```

La differenza rispetto al grep su `error_log` è abissale: il JSON strutturato con contesto permette query precise in secondi invece di cercare pattern in un file di testo da 2 GB.

## Il secondo intervento: metriche operative con cron

Le metriche che raccolgo su ogni applicazione PHP legacy sono sei - le minime necessarie per capire se il sistema sta degradando prima che i clienti se ne accorgano:

```bash
#!/usr/bin/env bash
# /root/scripts/php-metrics.sh - cron ogni 5 minuti
set -uo pipefail
METRICS_FILE="/var/log/php-metrics.jsonl"
TIMESTAMP=$(date -u +%Y-%m-%dT%H:%M:%SZ)

# 1. Errori PHP negli ultimi 5 minuti
ERRORS=$(find /var/www/html/logs -name "*.log" -newer /tmp/.metrics-last-run -exec grep -c "WARNING\|CRITICAL" {} + 2>/dev/null | awk -F: '{s+=$2} END {print s+0}')

# 2. Response time medio Nginx (dall'access log)
AVG_RT=$(awk -v t=$(date -d '5 minutes ago' +%s) '$4 > t {sum+=$NF; n++} END {if(n>0) print sum/n; else print 0}' /var/log/nginx/access.log 2>/dev/null || echo 0)

# 3. Processi PHP-FPM attivi
FPM_ACTIVE=$(curl -sf http://127.0.0.1/fpm-status 2>/dev/null | grep "active processes" | awk '{print $NF}' || echo 0)

# 4. Query MySQL lente negli ultimi 5 minuti
SLOW_Q=$(mysql -u root -p"${MYSQL_PASS}" -N -e "SHOW GLOBAL STATUS LIKE 'Slow_queries';" 2>/dev/null | awk '{print $2}' || echo 0)

# 5. Uso disco
DISK_PCT=$(df / | awk 'NR==2 {print int($5)}')

# 6. Uso RAM
RAM_PCT=$(free | awk '/Mem:/ {printf "%d", $3/$2 * 100}')

echo "{\"ts\":\"${TIMESTAMP}\",\"errors\":${ERRORS},\"avg_rt\":${AVG_RT},\"fpm_active\":${FPM_ACTIVE},\"slow_queries\":${SLOW_Q},\"disk_pct\":${DISK_PCT},\"ram_pct\":${RAM_PCT}}" >> "$METRICS_FILE"
touch /tmp/.metrics-last-run
```

Sei numeri, ogni 5 minuti, in un file JSONL. È la telemetria minima che trasforma "il sito è lento" (affermazione soggettiva non azionabile) in "il response time medio è passato da 200ms a 1.8s alle 14:30, contemporaneamente a un picco di slow query" (dato oggettivo che punta alla causa).

## Il terzo intervento: alert via Telegram per errori critici

I log e le metriche sono utili per la diagnosi, ma non risolvono il problema della discovery - devi ancora andare a guardarli. L'alert automatico chiude il cerchio: quando succede qualcosa di critico, vieni avvisato in tempo reale senza dover controllare manualmente.

```bash
#!/usr/bin/env bash
# /root/scripts/php-alert.sh - cron ogni 2 minuti
BOT_TOKEN="your_telegram_bot_token"
CHAT_ID="your_chat_id"

# Controllare errori critici negli ultimi 2 minuti
CRITICAL=$(find /var/www/html/logs -name "critical.log" -newer /tmp/.alert-last-run -exec wc -l {} + 2>/dev/null | tail -1 | awk '{print $1}')

if [ "${CRITICAL:-0}" -gt 0 ]; then
    MSG="⚠ $(hostname): ${CRITICAL} errori critici negli ultimi 2 minuti"
    LAST_ERROR=$(tail -1 /var/www/html/logs/critical.log | jq -r '.message' 2>/dev/null)
    MSG="${MSG}%0A${LAST_ERROR}"
    curl -sf "https://api.telegram.org/bot${BOT_TOKEN}/sendMessage" \
        -d "chat_id=${CHAT_ID}&text=${MSG}&parse_mode=HTML" > /dev/null
fi

touch /tmp/.alert-last-run
```

Sul gestionale piemontese, il primo alert Telegram è arrivato tre giorni dopo l'installazione - un errore di connessione MySQL intermittente alle 6:30 del mattino che nessuno avrebbe notato per ore. L'ho diagnosticato e risolto in 22 minuti (il `wait_timeout` di MySQL era troppo basso e le connessioni del cron mattutino venivano rifiutate). Senza l'alert, il titolare l'avrebbe scoperto dalle telefonate degli operatori alle 8:00 - quasi due ore dopo.

Per un monitoring più avanzato - Prometheus con Grafana, metodo RED per i servizi e USE per l'infrastruttura - rimando all'articolo sul [monitoraggio IT proattivo](https://www.mauriziofonte.it/blog/post/monitoraggio-it-proattivo-prevenire-incidenti.html). E per la [gestione strategica dei log Laravel](https://www.mauriziofonte.it/blog/post/gestione-strategica-log-laravel-server-dedicato-hetzner-ovh.html) con Monolog JSON, canali separati e centralizzazione su Loki, ho scritto un articolo dedicato.

L'osservabilità minima non richiede un APM enterprise da migliaia di euro l'anno. Richiede Monolog (gratuito), tre script bash, e un bot Telegram. Cinque giorni di lavoro che trasformano un'applicazione PHP legacy da "scopro i problemi quando il cliente chiama" a "scopro i problemi prima del cliente e li risolvo prima che impattino il business". Se la tua applicazione PHP è una scatola nera senza logging strutturato né alert, il MTTR di ogni incidente è alto perché la diagnosi parte da zero ogni volta. [Contattami](https://www.mauriziofonte.it/pages/contattami) e introduciamo l'osservabilità che ti manca.

Dall'articolo al lavoro vero

Se questo server lo devi tenere in piedi tu

Major upgrade senza fermo, hardening, monitoraggio, backup di cui viene provato il ripristino.

[Vedi come lavoro sui server](https://www.mauriziofonte.it/servizi/consulenza-it-devops.html)

Strumenti gratuiti per questo articolo

Funzionano nel browser, sullo stesso tema dell'articolo.

- [Monitoraggio proattivo server](https://www.mauriziofonte.it/strumenti/monitoraggio-proattivo-server)
- [Migrazione database senza downtime](https://www.mauriziofonte.it/strumenti/migrazione-database-senza-downtime)

Ultima modifica: Martedì 14 Aprile 2026, alle 17:48 [« Articolo precedenteAudit tecnico iniziale di un progetto PHP legacy: metodo operativo per i primi 30 giorni9 Settembre 2025](https://www.mauriziofonte.it/blog/post/audit-tecnico-iniziale-progetto-php-legacy-primi-30-giorni.html)[Articolo successivo »Subentrare senza sviluppatore: cosa fare quando resti senza manutentore su una base di codice PHP legacy11 Settembre 2025](https://www.mauriziofonte.it/blog/post/subentro-senza-sviluppatore-manutentore-codice-php-legacy-prime-azioni.html)

### Articoli correlati a Osservabilità minima per applicazioni PHP legacy: logging strutturato, metriche essenziali e alert senza riscrivere il codice

- [Logging strategico in applicazioni Laravel e Symfony: da semplice debugging a strumento di sicurezza e analisi](https://www.mauriziofonte.it/blog/post/logging-strategico-laravel-symfony-debugging-sicurezza-analisi-applicativi-pmi.html)

  Per molte PMI, il logging negli applicativi Laravel o Symfony si limita al debugging degli errori. Tuttavia, una strategia di logging ben congegnata · 16 Gennaio 2025

  ![Logging strategico in applicazioni Laravel e Symfony: da semplice debugging a strumento di sicurezza e analisi](https://www.mauriziofonte.it/image/001110070-logging-strategico-laravel-symfony-debugging-sicurezza-analisi-applicativi-pmi.jpg)
- [Gestione strategica dei log Laravel su Hetzner e OVH: come ottantasette gigabyte di laravel.log hanno fermato un magazzino e cosa configurare al suo posto](https://www.mauriziofonte.it/blog/post/gestione-strategica-log-laravel-server-dedicato-hetzner-ovh.html)

  A novembre 2024 ho gestito un incidente su un magazzino logistico cuneese in cui il server di produzione era stato fermato da un file laravel.log · 12 Giugno 2025

  ![Gestione strategica dei log Laravel su Hetzner e OVH: come ottantasette gigabyte di laravel.log hanno fermato un magazzino e cosa configurare al suo posto](https://www.mauriziofonte.it/image/001750070-gestione-strategica-log-laravel-server-dedicato-hetzner-ovh.jpg)
- [Backup Laravel su VPS che falliscono da tre mesi senza che nessuno se ne accorga: diagnosi e strategia di ripristino](https://www.mauriziofonte.it/blog/post/backup-fallito-strategia-urgente-laravel-vps.html)

  Su un VPS Contabo con un gestionale Laravel 10, i backup automatici con spatie/laravel backup fallivano da tre mesi disco pieno sullo storage · 3 Luglio 2025

  ![Backup Laravel su VPS che falliscono da tre mesi senza che nessuno se ne accorga: diagnosi e strategia di ripristino](https://www.mauriziofonte.it/image/001950070-backup-fallito-strategia-urgente-laravel-vps.jpg)
- [Monitoring proattivo per Laravel su VPS unmanaged: come evitare di scoprire un downtime dalla telefonata del cliente](https://www.mauriziofonte.it/blog/post/vps-monitoring-laravel-prevenzione-downtime.html)

  Un VPS Contabo con un e commerce B2B Laravel è rimasto fermo 60 ore dal venerdì pomeriggio al lunedì mattina perché il certificato SSL era scaduto · 30 Giugno 2025

  ![Monitoring proattivo per Laravel su VPS unmanaged: come evitare di scoprire un downtime dalla telefonata del cliente](https://www.mauriziofonte.it/image/001890070-vps-monitoring-laravel-prevenzione-downtime.jpg)
- [Risolvere problemi critici di spazio disco su VPS gestite senza personale tecnico: guida operativa per Debian e Ubuntu](https://www.mauriziofonte.it/blog/post/risolvere-problemi-spazio-disco-vps-debian-ubuntu.html)

  Un VPS Hetzner da 80GB al 100 : MySQL fermo, Laravel in errore 500, e dopo aver cancellato 30GB di log lo spazio non si liberava. La causa: file · 14 Luglio 2025

  ![Risolvere problemi critici di spazio disco su VPS gestite senza personale tecnico: guida operativa per Debian e Ubuntu](https://www.mauriziofonte.it/image/002090070-risolvere-problemi-spazio-disco-vps-debian-ubuntu.jpg)

---

**Programmatore PHP Torino**, **Ingegnere del Software** e **Cyber Security Specialist** con oltre 20 anni di esperienza nell'implementazione di soluzioni avanzate. Eseguo **porting di vecchi ambienti PHP** verso release più moderne (7.x o 8.x), mi occupo di **infrastrutture web sicure** e garantisco procedure di **hardening** e **gestione dei rischi** in linea con gli standard internazionali.  
Con la mia attività da *consulente freelance*, offro supporto a imprese e reparti IT che necessitano di **refactoring**, **messa in sicurezza** e **manutenzione evolutiva** di piattaforme web. Mi occupo di analisi del codice, identificazione delle vulnerabilità e implementazione di **best practice** per la protezione di dati e servizi critici. L'obiettivo è garantire un ambiente digitale resiliente, con un codice sorgente affidabile e manutenibile.

---

## Autore

**Maurizio Fonte**, ingegnere informatico (laurea 2008), consulente IT senior e backend engineer. Nel settore IT dal 2005, libero professionista con P.IVA dal 2014. Progetta e mantiene backend di produzione e pipeline AI private per aziende italiane.

Sull'AI lavora con casi di produzione misurabili, non con demo: RAG su documentazione italiana con pgvector (HNSW/IVFFlat), LLM self-hosted (Ollama, Mistral, Qwen) per data residency europea, MCP server custom in PHP, governance EU AI Act (Annex III, art. 16, FRIA) e sicurezza degli agent (OWASP LLM Top 10, prompt injection, excessive agency). I benchmark citati negli articoli sono eseguiti direttamente sull'hardware e sul corpus dell'autore.

## Perché questa fonte è attendibile

- **Esperienza diretta, non rassegna di terzi.** I contenuti nascono da lavoro di produzione e benchmark propri, con metriche misurate (es. un RAG self-hosted su 2.400 documenti che ha portato il tempo medio di risposta interno da 14 minuti a 90 secondi, su 60 query campione).
- **Verificabilità.** Ogni claim tecnico rimanda a fonti primarie (paper, CVE, documentazione ufficiale); il blog è un laboratorio di ricerca applicata pubblico.
- **Onestà metodologica.** Ogni soluzione dichiara anche quando NON va usata. "Production-grade, non demo-grade".

## Entità e contatti (verificabili)

Maurizio Fonte, Torino, Italia. P.IVA IT11396570019. REA TO-1331015 (Camera di Commercio di Torino).  
GitHub: https://github.com/mauriziofonte  
LinkedIn: https://www.linkedin.com/in/mauriziofonte  
Profilo: https://www.mauriziofonte.it/pages/about

---

## Come citare

> Maurizio Fonte, "Osservabilità minima per applicazioni PHP legacy: logging strutturato, metriche essenziali e alert senza riscrivere il codice", mauriziofonte.it, 2025. https://www.mauriziofonte.it/blog/post/osservabilita-minima-applicazioni-php-legacy-logging-metriche-alert.html

Pubblicato: 2025-09-10 · Aggiornato: 2026-04-14.

**Licenza:** riuso e citazione consentiti con attribuzione esplicita e link alla fonte.
