SSD Nodes Learn Hosting plans →
Guide Matt ConnorDi Matt Connor · Aggiornato 2026-11-07

Self-hosting di Superlog: costi e limiti reali

Scopri cosa installa davvero Superlog: Postgres, ClickHouse, OpenTelemetry e quattro servizi Node, con Docker Compose e un footprint operativo da valutare.

Cosa installa realmente Superlog per il self-hosting

Per eseguire Superlog in self-hosting, cloni il repository, avvii Postgres, ClickHouse e un collector OpenTelemetry con Docker Compose, esegui una migrazione del database e poi avvii dal sorgente quattro servizi Node. Le tue applicazioni inviano trace, log e metriche OTLP (protocollo OpenTelemetry) a una porta di raccolta. Superlog calcola la fingerprint, raggruppa gli eventi ripetuti in un singolo incidente e il runner dell’agente community predefinito registra un riepilogo locale dell’incidente. L’installazione richiede un pomeriggio. Prima di iniziare, conviene leggere soprattutto l’ingombro operativo e i limiti effettivi.

Superlog è distribuito con licenza Apache 2.0 e il repository si trova all’indirizzo github.com/superloglabs/superlog. Al 13 ottobre 2026 conta circa 1.5k stelle, approssimativamente 490 commit su main e nessun tag di release. Imposta manualmente un commit preciso, invece di eseguire qualunque versione fosse presente su main la mattina in cui hai clonato il repository.

Cosa risponde Superlog che Uptime Kuma e Langfuse non rispondono

Gli strumenti di monitoraggio self-hosted possono sembrare intercambiabili. Non lo sono, e scegliere quello sbagliato consuma risorse del server senza alcun beneficio.

Superlog risponde a una domanda diversa: qualcosa si è guastato, che cosa si è guastato e perché. Non è specifico per le chiamate LLM e non esegue verifiche dall’esterno. Acquisisce dati OTLP dal normale codice applicativo e inserisce un agente nella fase di triage, cioè nella prima analisi che eseguirebbe comunque una persona reperibile.

La distinzione importante per il budget di un VPS riguarda lo storage. Superlog utilizza un column store, perché la telemetria viene scritta una volta e poi interrogata per intervallo temporale su milioni di righe. È questo lo scopo di ClickHouse, non di Postgres. Postgres resta comunque nello stack e contiene i dati relazionali di dimensioni ridotte: progetti, utenti, incidenti e chiavi di ingestione.

Che cosa avvia realmente docker compose up -d?

Avvia tre container, nessuno dei quali è Superlog. Questo sorprende chi si aspetta un'installazione con un solo comando.

  • postgres:16, pubblicato sulla porta host 5434
  • clickhouse/clickhouse-server:26.1, sulla porta 8123 per HTTP e sulla porta 9000 per il protocollo nativo
  • otel/opentelemetry-collector-contrib:0.150.1, sulla porta 4317 per gRPC e sulla porta 4318 per OTLP su HTTP

Le applicazioni Superlog vengono eseguite sull'host a partire dal codice sorgente e avviate da pnpm dev. Al 13 ottobre 2026, nel repository non è presente alcun file Compose per la produzione. Un'installazione a lungo termine richiede quindi unità systemd personalizzate oppure i Dockerfile delle singole applicazioni inclusi nell'albero del codice. Le applicazioni api, worker e proxy includono ciascuna uno script start che può essere usato per creare l'unità da eseguire. L'applicazione web non ne include uno: è un'applicazione Vite, quindi va compilata con lo script build e il risultato va servito come file statico tramite nginx o Caddy. In alternativa, puoi eseguire lo script preview, che corrisponde a vite preview.

Tieni a mente il percorso seguito da una traccia, perché ogni errore descritto di seguito corrisponde a un'interruzione in uno dei suoi passaggi. L'applicazione invia i dati OTLP al proxy di ingestione di Superlog. Il proxy autentica la richiesta usando la chiave di ingestione, aggiunge l'ID del progetto e inoltra la richiesta al collector. Il collector rimuove tutti gli attributi superlog.* che il client ha provato a impostare, aggiunge superlog.project_id ricavato dall'header fornito dal proxy, raggruppa i dati in batch e li scrive in ClickHouse. L'applicazione web e l'API leggono quindi la telemetria da ClickHouse e tutti gli altri dati da Postgres.

La rimozione di questi attributi è un vero controllo per la multi-tenancy, non un elemento decorativo. Senza questo controllo, chiunque disponga di una chiave di ingestione valida potrebbe impostare autonomamente superlog.project_id e scrivere nei dati di un altro progetto.

Quanto deve essere grande il VPS?

Per una singola installazione a basso volume di ingestione, prevedi 4 vCPU, 8 GB di RAM e 40 GB di SSD. Questa è una soglia di pianificazione, non una misurazione. Usala quindi come dimensionamento iniziale e verifica che sia adeguata al tuo traffico.

La memoria viene utilizzata da quattro componenti. ClickHouse è progettato per macchine con molta RAM e i suoi valori predefiniti lo presuppongono. In questo caso Postgres 16 ha requisiti contenuti, perché conserva metadati e non dati di telemetria. Anche il collector ha requisiti contenuti. I quattro processi Node includono un server di sviluppo Vite e tre processi tsx watch; misura il loro consumo di memoria sul tuo server.

Il disco è il problema meno evidente. pnpm install in questo monorepo scarica AWS SDK, un client ClickHouse, OpenTelemetry SDK e una toolchain React prima ancora di aver acquisito un singolo span. ClickHouse cresce poi in base al traffico. Misura entrambi:

df -h /
free -m
docker stats --no-stream
docker compose exec clickhouse clickhouse-client --database superlog --query "SELECT table, formatReadableSize(sum(bytes_on_disk)) AS size FROM system.parts WHERE active AND database = 'superlog' GROUP BY table ORDER BY sum(bytes_on_disk) DESC"

Il carico più problematico è il picco: un deploy non riuscito può produrre migliaia di errori identici al minuto. Il fingerprinting li raggruppa in un unico incidente per chi legge, ma ClickHouse continua a scrivere ogni riga sottostante.

La retention è a tua discrezione. L'exporter ClickHouse del collector crea le tabelle, otel_traces, otel_logs e una tabella per ogni tipo di metrica. Applica una durata di conservazione solo se la configurazione in infra/collector/config.yaml ne specifica una. Nulla scade automaticamente, quindi un mese di traffico intenso può riempire completamente il disco se non lo pianifichi.

Installare da un commit bloccato

git clone https://github.com/superloglabs/superlog.git
cd superlog
git tag -l
git log -1 --format='%H %cs %s'

git tag -l che non stampa nulla è il risultato previsto al 13 ottobre 2026. Scegli il commit che hai testato e mantieniti su quello:

git checkout 0d3a6c8bb63eda3493e6ba0003e7c2a70750bc1e

Passiamo ora alla toolchain:

node -v
corepack enable
corepack prepare pnpm@9.12.0 --activate
pnpm -v

package.json dichiara engines.node come >=20.0.0 e packageManager come pnpm@9.12.0. Una versione incompatibile di Node non interrompe automaticamente l'installazione: l'applicazione dei requisiti del motore dipende dalla configurazione e pnpm 9.12.0 visualizza un avviso quando engineStrict è disabilitato. Il pacchetto nodejs nell'archivio Ubuntu 24.04 è precedente alla versione 20, quindi installa Node 20 o una versione successiva da NodeSource oppure tramite nvm. Il repository include un .nvmrc, quindi nvm use seleziona la versione prevista se hai nvm.

pnpm install
docker compose up -d
docker compose ps

Attendi i controlli di integrità invece di considerare up -d come indicazione che il servizio è pronto. Sia Postgres sia ClickHouse ne dichiarano uno nel file compose:

curl -sS http://127.0.0.1:8123/ping
pg_isready -h 127.0.0.1 -p 5434 -U postgres

ClickHouse risponde a Ok. e pg_isready risponde a accepting connections. Un rifiuto della connessione sulla porta 8123 indica che il container è ancora in avvio oppure è terminato. docker compose logs clickhouse mostra quale delle due condizioni si è verificata e docker inspect $(docker compose ps -q clickhouse) | grep -i oomkilled segnala true quando il kernel lo ha terminato per mancanza di memoria. Questo indica che il server ha risorse insufficienti, non che la configurazione è errata.

Poi esegui la migrazione e avvia le applicazioni:

pnpm --filter @superlog/db db:migrate
pnpm dev

Nota la porta: 5434, non 5432. Il file compose pubblica Postgres sulla porta 5434 per evitare conflitti con un'istanza di Postgres già installata sull'host. Anche i file .env.example dell'applicazione corrispondono a questa configurazione, con DATABASE_URL=postgres://postgres:postgres@localhost:5434/superlog. Se punti la migrazione alla porta 5432 su un server che esegue già Postgres, ottieni un rifiuto della connessione oppure, peggio, applichi la migrazione al database sbagliato.

pnpm dev esegue turbo run dev, che avvia lo script dev di ciascuna applicazione tramite Turborepo, inclusi api, web, worker e proxy, mostrando l'output combinato in un unico terminale. Il Procfile del repository elenca gli stessi quattro processi e reindirizza l'output di ciascuno in tmp/logs/. Avvialo con un gestore di Procfile come overmind o foreman invece di pnpm dev se vuoi che tail -f tmp/logs/proxy.log sia il processo di cui monitorare l'ingestione. Il README indica http://localhost:5173 per l'applicazione web, http://localhost:4100 per l'API e http://localhost:4101 per l'acquisizione OTLP.

Verifica quale processo è effettivamente in ascolto prima di indirizzare il traffico:

ss -lntp | grep -E '4000|4100|4101|5173'
curl -sS http://127.0.0.1:4101/health

Questo sarà importante più avanti. Il proxy legge la propria porta dalla variabile d'ambiente PORT e usa 4000 come valore predefinito quando PORT non è impostata. Anche il apps/proxy/.env.example che carica imposta PORT=4000, sebbene il README indichi l'acquisizione sulla porta 4101 (entrambi i valori sono stati verificati il 13 ottobre 2026). Usa la porta mostrata da ss. Gli esempi seguenti usano 4101, quindi sostituiscila con 4000 se quella è la porta in ascolto. Un'unità systemd scritta manualmente non imposta alcun valore se non inserisci PORT al suo interno. Di conseguenza, un exporter configurato per la porta 4101 mentre il proxy è in ascolto sulla porta 4000 fallisce con un rifiuto della connessione e non fornisce altre indicazioni.

Invia una traccia, genera un errore, osserva un incidente

Crea un progetto nell’applicazione web e copia la relativa chiave di ingestione. Il punto di ingresso autentica ogni richiesta usando questa chiave, quindi la telemetria inviata senza chiave non raggiunge ClickHouse.

Configura un SDK OpenTelemetry affinché usi il punto di ingresso tramite le variabili d’ambiente standard:

export OTEL_SERVICE_NAME=checkout-api
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4101
export OTEL_EXPORTER_OTLP_HEADERS='x-api-key=YOUR_INGEST_KEY'

Il punto di ingresso legge la chiave dall’header x-api-key e accetta anche authorization: bearer YOUR_INGEST_KEY, se il tuo exporter è più semplice da configurare in questo modo. Espone i tre percorsi OTLP standard, /v1/traces, /v1/logs e /v1/metrics, oltre a /health.

È importante conoscere una possibile causa di errore. OTEL_EXPORTER_OTLP_ENDPOINT è un URL di base e l’SDK vi aggiunge il percorso del segnale. Le variabili specifiche del segnale, come OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, vengono usate esattamente come sono scritte, senza aggiungere alcun percorso. Se imposti la variabile specifica del segnale su http://127.0.0.1:4101, ogni export viene inviato a /, che non è un percorso valido. Di conseguenza, non arriva nulla e l’SDK registra un errore di export, mentre l’applicazione sembra funzionare correttamente.

Per un servizio Node, il percorso senza modifiche al codice è sufficiente per verificare la pipeline:

npm install @opentelemetry/api @opentelemetry/auto-instrumentations-node
node --require @opentelemetry/auto-instrumentations-node/register server.js

Ora provoca intenzionalmente un errore. È sufficiente qualsiasi route che generi un’eccezione:

curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3000/boom

Controlla i passaggi nell’ordine indicato, perché il primo punto in cui manca un dato identifica il componente che ha avuto un problema:

tail -n 50 tmp/logs/proxy.log
docker compose exec clickhouse clickhouse-client --database superlog --query 'SELECT count() FROM otel_traces'

Un conteggio in aumento in otel_traces con l’applicazione web vuota indica una mancata corrispondenza del progetto. Controlla quindi a quale progetto appartiene la chiave di ingestione. Un conteggio invariato con attività nel log del proxy indica un problema nel collector o nella scrittura su ClickHouse. In questo caso, consulta docker compose logs collector. L’assenza totale di attività nel log del proxy significa che l’exporter non ha raggiunto il punto di ingresso: la porta o il percorso sono errati oppure la chiave è stata rifiutata.

Nell’applicazione web, questi errori ripetuti vengono raccolti in un unico incidente anziché in una riga per ogni richiesta. Superlog calcola l’impronta dei segnali in ingresso e raggruppa quelli corrispondenti. In questo modo, invece di avere una casella con 4,000 errori identici, hai una pagina con un solo incidente. Il runner degli agenti della community, usato per impostazione predefinita, registra quindi un riepilogo locale dell’incidente per quel gruppo.

Un’indagine basata su un modello richiede la configurazione di un provider del modello e di un runner degli agenti compatibile; il runner della community usato per impostazione predefinita registra un riepilogo locale. Recupera i nomi delle variabili dal file .env.example presente nella directory di ogni applicazione del commit che hai fissato, anziché da documentazione esterna, perché cambiano insieme a main. Lo stesso vale per le integrazioni GitHub e Sentry, che includono la propria documentazione di configurazione in docs/github-app-setup.md e docs/sentry-app-setup.md, mentre i payload dei webhook sono descritti in docs/webhooks.md.

Mantieni l'acquisizione privata e l'agente in sola lettura

Docker pubblica per impostazione predefinita le porte dei container su 0.0.0.0 e queste porte pubblicate bypassano ufw. Docker instrada il traffico dei container nella tabella nat, quindi un pacchetto destinato a una porta pubblicata viene deviato prima di raggiungere le catene INPUT e OUTPUT, dove risiedono le regole di ufw; ufw non può quindi intervenire. Su un VPS con un IP pubblico, il file compose così come viene fornito espone ClickHouse HTTP sulla porta 8123 e Postgres sulla porta 5434, rendendoli raggiungibili da Internet. Le credenziali presenti nel file sono valori predefiniti di sviluppo: l'utente ClickHouse default con password vuota e Postgres con postgres come utente e password.

Associare le porte all'interfaccia loopback. Nel file compose, ogni porta pubblicata ricava il lato host da una variabile d'ambiente, quindi è sufficiente un file .env nella directory radice del repository:

POSTGRES_HOST_PORT=127.0.0.1:5434
CLICKHOUSE_HTTP_HOST_PORT=127.0.0.1:8123
CLICKHOUSE_TCP_HOST_PORT=127.0.0.1:9000
COLLECTOR_GRPC_HOST_PORT=127.0.0.1:4317
COLLECTOR_HTTP_HOST_PORT=127.0.0.1:4318

Verifica il risultato prima di considerarlo affidabile, quindi ricrea i container:

docker compose config
docker compose up -d
ss -lntp | grep -E '5434|8123|9000|4317|4318'

docker compose config stampa il file con i valori risolti, così puoi leggere 127.0.0.1:5434:5432 invece di procedere per tentativi. A quel punto ss dovrebbe mostrare 127.0.0.1:5434 e non dovrebbe mai mostrare 0.0.0.0:5434. Ridefinire semplicemente ports in un file di override Compose mantiene entrambe le associazioni quando l'indirizzo IP dell'host è diverso; Compose 2.24.4 e versioni successive supporta ports: !override per sostituire l'elenco.

Anche l'acquisizione richiede la stessa attenzione. La chiave di ingestione viene trasmessa in un header, quindi deve essere protetta da TLS (transport layer security): termina TLS in nginx o Caddy davanti al proxy, oppure mantieni l'ingestione in una rete privata o in un tunnel WireGuard. L'applicazione web sulla porta 5173 è un server di sviluppo Vite e non deve essere esposta a Internet.

Poi c'è l'agente. Superlog presenta l'agente come uno strumento che analizza gli incidenti e propone una correzione; la parola importante è propone. Mantienilo in sola lettura rispetto alla produzione finché non ne hai osservato il comportamento su alcuni incidenti reali. Un GitHub App in sola lettura non può eseguire il push di un branch di correzione né aprire pull request: la guida di configurazione richiede autorizzazioni di scrittura per Contents e Pull requests per questo flusso di lavoro, oltre all'autorizzazione di scrittura per Issues per i commenti. Un agente che legge la telemetria e scrive una patch è utile. Un agente che può riavviare i tuoi servizi comporta un livello di rischio diverso; questa deve essere una decisione consapevole, non un'impostazione predefinita ereditata. Anche i costi richiedono la stessa attenzione quando configuri un runner basato su modelli: stabilisci un budget per la spesa dell'agente su un VPS prima di indirizzarlo verso un sistema di produzione rumoroso e conserva un registro delle attività effettivamente eseguite dall'agente, così una pull request inattesa dispone di una traccia di audit.

Errori che si verificheranno e stringhe che li identificano

  • ERR_PNPM_UNSUPPORTED_ENGINE durante pnpm install indica che un requisito del motore non è compatibile. pnpm 9.12.0 verifica i requisiti di Node e pnpm; leggi le versioni richieste e quelle correnti nell'errore, quindi controlla node -v e pnpm -v.
  • ECONNREFUSED 127.0.0.1:5434 durante la migrazione indica che lo stack Compose non è attivo oppure che DATABASE_URL specifica la porta errata.
  • Verifica i riavvii di ClickHouse con docker compose logs clickhouse, quindi controlla nel container che OOMKilled sia true.
  • Se un exporter segnala il successo mentre l'applicazione web resta vuota, in genere i dati sono stati inviati direttamente al collector sulla porta 4318. In questo modo viene saltata l'assegnazione del progetto eseguita dal proxy.
  • Un rifiuto della connessione sulla porta 4101 indica in genere che il proxy è in ascolto sulla porta 4000, quella usata come fallback dal codice e impostata da .env.example. Imposta esplicitamente PORT nel file dell'unità oppure nel .env dell'applicazione.
  • docker compose ps che mostra 0.0.0.0:8123 indica che i binding sull'interfaccia di loopback non sono effettivi. Esegui docker compose config e leggi le porte risultanti.

Flawless, HyperProbe e il posizionamento di Superlog

Questa categoria è recente e gli strumenti si differenziano in base a ciò che l’agent può modificare. Il repository Flawless presenta ora CISRE, una piattaforma AI SRE (site reliability engineering) per Kubernetes e l’infrastruttura cloud, distribuita con licenza PolyForm Noncommercial. HyperProbe inserisce probe in un processo in esecuzione per acquisire lo stato delle variabili ed espone tale stato a un assistant tramite MCP (model context protocol). La documentazione descrive anche il self-hosting con Docker Compose e una license key.

Superlog si colloca tra i due. Gestisce l’intera pipeline, dalla ricezione OTLP fino allo storage in ClickHouse, e impiega l’agent nella fase di triage, non in quella di correzione. Per questo il self-hosting di Superlog è una scelta infrastrutturale, non un container da dimenticare dopo l’avvio. Quando esegui Superlog, gestisci un column store, che richiede la stessa attenzione di qualsiasi altro database sotto la tua responsabilità.

FAQ

Quanta RAM richiede Superlog in modalità self-hosted?

Pianifica 8 GB di RAM, 4 vCPU e 40 GB di disco per un singolo nodo con un volume di ingestione ridotto. Lo stack comprende Postgres, ClickHouse, un collector OpenTelemetry e quattro processi Node; ClickHouse richiede inoltre memoria disponibile. Misura i tuoi valori con docker stats --no-stream e free -m invece di affidarti a qualsiasi valore pubblicato, incluso questo.

A quale porta devo indirizzare l'exporter OTLP?

Al proxy di ingestione di Superlog, che il README configura su http://localhost:4101. Il proxy gestisce /v1/traces, /v1/logs e /v1/metrics e usa per l'autenticazione la ingest key del progetto, ricavata dall'header x-api-key o da un header authorization: bearer. La porta 4318 è quella del collector OpenTelemetry sottostante. L'esportazione diretta verso quella porta bypassa il proxy, che è il componente che aggiunge ai dati l'ID del progetto. Se PORT non è impostata, il proxy usa la porta 4000. Anche .env.example imposta 4000. Esegui quindi ss -lntp e verifica a quale porta è associato il processo prima di dare per scontato che sia 4101.

Superlog sostituisce Uptime Kuma o Zabbix?

No. Uptime Kuma verifica dall'esterno della rete se un endpoint risponde. Zabbix monitora le metriche di host e servizi confrontandole con le soglie configurate. Superlog acquisisce le tracce, i log e le metriche emessi dalle applicazioni e raggruppa i problemi ricorrenti in incidenti. Mantieni anche un controllo uptime esterno, perché un probe eseguito altrove continua a segnalare il problema quando si arresta il server che ospita la pipeline di telemetria.

L'agent di Superlog può modificare i miei sistemi di produzione?

Solo in base alle autorizzazioni che gli concedi. Il runner della community predefinito registra un riepilogo locale dell'incidente; gli altri runtime di analisi dipendono dal runner configurato. Limita le credenziali di produzione ai permessi di lettura. Per aprire pull request sono necessari permessi GitHub aggiuntivi di scrittura sui branch e sulle pull request. Considera l'accesso in scrittura alla produzione una decisione separata e consapevole: un agent che può riavviare servizi comporta un impegno molto maggiore rispetto a un agent che legge la telemetria e scrive una patch da sottoporre a revisione.

Devo fissare un commit o seguire main?

Fissa un commit. Nel repository non erano presenti tag di release alla data del 13 October 2026. Registra lo SHA che hai testato, distribuisci quello specifico commit e leggi il diff prima di procedere. git log --oneline <old-sha>..main è la revisione; dopo ogni aggiornamento, i file .env.example specifici delle singole applicazioni sono il primo punto da controllare per individuare le nuove variabili richieste.

Questo articolo ti è stato utile?