Coroot Observability

Strumento di osservabilità e APM open-source basato su eBPF con metriche senza strumentazione, log, tracce e continuous profiling per ambienti Kubernetes e Docker.

Installation

Docker Compose (Quickest)

# Distribuzione con un singolo comando con ClickHouse e Prometheus
curl -fsS https://raw.githubusercontent.com/coroot/coroot/main/deploy/docker-compose.yaml | \
  docker compose -f - up -d

# Accedere all'interfaccia utente su http://localhost:8080

Kubernetes (Helm)

# Aggiungere il repository Helm di Coroot
helm repo add coroot https://coroot.github.io/helm-charts
helm repo update coroot

# Installare l'operatore Coroot
helm install -n coroot --create-namespace coroot-operator coroot/coroot-operator

# Distribuire Community Edition
helm install -n coroot coroot coroot/coroot-ce

# Distribuire con replica ClickHouse
helm install -n coroot coroot coroot/coroot-ce \
  --set "clickhouse.shards=2,clickhouse.replicas=2"

# Port forward per accedere all'interfaccia utente
kubectl port-forward -n coroot service/coroot-coroot 8080:8080

# Accedere all'interfaccia utente su http://localhost:8080

Docker Swarm

# Distribuire lo stack Coroot
curl -fsS https://raw.githubusercontent.com/coroot/coroot/main/deploy/docker-swarm-stack.yaml | \
  docker stack deploy -c - coroot

Ubuntu/Debian

# Installare il server Coroot
curl -sfL https://raw.githubusercontent.com/coroot/coroot/main/deploy/install.sh | \
  BOOTSTRAP_PROMETHEUS_URL="http://PROMETHEUS_IP:9090" \
  BOOTSTRAP_REFRESH_INTERVAL=15s \
  BOOTSTRAP_CLICKHOUSE_ADDRESS=CLICKHOUSE_IP:9000 \
  sh -

RHEL/CentOS

# Lo stesso installatore funziona per le distribuzioni basate su RHEL
curl -sfL https://raw.githubusercontent.com/coroot/coroot/main/deploy/install.sh | \
  BOOTSTRAP_PROMETHEUS_URL="http://PROMETHEUS_IP:9090" \
  BOOTSTRAP_REFRESH_INTERVAL=15s \
  BOOTSTRAP_CLICKHOUSE_ADDRESS=CLICKHOUSE_IP:9000 \
  sh -

Node Agent Installation

Docker

# Eseguire l'agente node come container privilegiato
docker run --detach --name coroot-node-agent \
  --pull=always --privileged --pid host \
  -v /sys/kernel/tracing:/sys/kernel/tracing:rw \
  -v /sys/kernel/debug:/sys/kernel/debug:rw \
  -v /sys/fs/cgroup:/host/sys/fs/cgroup:ro \
  ghcr.io/coroot/coroot-node-agent \
  --cgroupfs-root=/host/sys/fs/cgroup \
  --collector-endpoint=http://COROOT_IP:8080

Linux (systemd)

# Installare l'agente node su bare-metal o VM
curl -sfL https://raw.githubusercontent.com/coroot/coroot-node-agent/main/install.sh | \
  COLLECTOR_ENDPOINT=http://COROOT_IP:8080 \
  SCRAPE_INTERVAL=15s \
  sh -

Kubernetes (via Helm operator)

# L'agente node è distribuito automaticamente dall'operatore Coroot
# Nessuna installazione separata necessaria quando si utilizza Helm

Basic Commands

Command	Description
`docker compose up -d`	Avviare Coroot con Docker Compose
`docker compose down`	Interrompere tutti i servizi Coroot
`docker compose logs -f`	Seguire i log di Coroot
`helm install coroot coroot/coroot-ce`	Installare Coroot su Kubernetes
`helm upgrade coroot coroot/coroot-ce`	Aggiornare Coroot
`helm uninstall coroot -n coroot`	Rimuovere Coroot dal cluster
`kubectl port-forward svc/coroot-coroot 8080:8080 -n coroot`	Accedere all’interfaccia utente di Coroot

Configuration Parameters

Server Configuration

Variable	Description	Default
`BOOTSTRAP_PROMETHEUS_URL`	Endpoint del server Prometheus	Required
`BOOTSTRAP_REFRESH_INTERVAL`	Intervallo di raccolta delle metriche	`15s`
`BOOTSTRAP_CLICKHOUSE_ADDRESS`	Indirizzo del server ClickHouse	Required
`LISTEN_ADDRESS`	Indirizzo di ascolto HTTP	`:8080`
`DATA_DIR`	Percorso della directory dei dati	`/var/lib/coroot`

Node Agent Configuration

Flag	Description	Default
`--collector-endpoint`	Endpoint del server Coroot	Required
`--cgroupfs-root`	Percorso radice del filesystem Cgroup	`/sys/fs/cgroup`
`--scrape-interval`	Intervallo di scraping delle metriche	`15s`
`--log-level`	Verbosità della registrazione	`info`

Architecture Components

Component	Role
Coroot Server	Dashboard centrale, motore di analisi, avvisi
Node Agent	Raccolta di metriche e log basata su eBPF su ogni nodo
Cluster Agent	Monitoraggio del database (MySQL, PostgreSQL, Redis)
ClickHouse	Archiviazione di metriche, log, tracce e profili
Prometheus	Scraping delle metriche e remote write

Key Features

Zero-Instrumentation Observability

Feature	Description
Automatic Discovery	Servizi auto-scoperti tramite eBPF — nessuna modifica al codice necessaria
Service Map	Mappa della topologia in tempo reale mostrante tutte le dipendenze dei servizi
Distributed Tracing	Tracciamento delle richieste tra microservizi senza SDK
Log Collection	Raccolta automatica dei log e clustering dei pattern
Continuous Profiling	Profiling di CPU/memoria con attivazione con un clic

Monitoring Capabilities

Capability	Description
SLO Tracking	Definire e monitorare gli obiettivi a livello di servizio
Issue Detection	Identificazione automatica di oltre l’80% dei problemi
Deployment Tracking	Tracciamento dei deployment Kubernetes e rollback
Cost Monitoring	Analisi dei costi delle risorse AWS, GCP, Azure
Network Analysis	Metriche di connessione TCP, latenza DNS, ritrasmissioni

Supported Protocols (eBPF)

Protocol	Metrics Collected
HTTP/HTTPS	Latenza, tasso di errore, throughput
gRPC	Latenza a livello di metodo e errori
PostgreSQL	Latenza delle query, connessioni, errori
MySQL	Prestazioni delle query, query lente
Redis	Latenza dei comandi, rapporto hit/miss
MongoDB	Latenza delle operazioni, connessioni
Kafka	Lag dei produttori/consumatori, throughput
DNS	Latenza di risoluzione, tasso di errore

Helm Chart Values

Common Overrides

# Dimensionamento personalizzato di ClickHouse
helm install coroot coroot/coroot-ce \
  --set clickhouse.shards=3 \
  --set clickhouse.replicas=2 \
  --set clickhouse.storage=100Gi

# Impostazioni Prometheus personalizzate
helm install coroot coroot/coroot-ce \
  --set prometheus.storage=50Gi \
  --set prometheus.retention=30d

# Abilitare ingress
helm install coroot coroot/coroot-ce \
  --set ingress.enabled=true \
  --set ingress.host=coroot.example.com

Alerting Configuration

Alert Type	Description
SLO Breach	Attivato quando l’obiettivo SLO è a rischio
Latency Spike	La latenza p99 supera la soglia
Error Rate	La percentuale di errore supera la soglia
Resource	Anomalia nell’utilizzo di CPU, memoria o disco
Deployment	Deployment non riuscito o degradato rilevato

Notification Channels

Channel	Configuration
Slack	URL Webhook
PagerDuty	Chiave di integrazione
Opsgenie	Chiave API
Email	Impostazioni SMTP
Webhook	Endpoint HTTP personalizzato

Troubleshooting

Issue	Solution
Nessun dato visualizzato	Verificare che l’agente node `--collector-endpoint` punti al server Coroot
Servizi mancanti	Verificare che l’agente node sia in esecuzione con `--privileged` e `--pid host`
eBPF non caricato	Assicurarsi che la versione del kernel sia 4.16+ con supporto BTF
Utilizzo di memoria elevato	Ridurre `--scrape-interval` o limitare gli spazi dei nomi monitorati
Connessione ClickHouse	Verificare che ClickHouse sia in esecuzione e accessibile sulla porta 9000

Best Practices

Distribuire agenti node su ogni nodo nel cluster per visibilità completa
Utilizzare la replica ClickHouse per i deployment di produzione (minimo 2 repliche)
Impostare obiettivi SLO significativi prima di affidarsi agli avvisi automatici
Iniziare con Docker Compose per la valutazione, migrare a Helm per la produzione
Configurare il remote write di Prometheus per persistere le metriche oltre i riavvii del pod
Utilizzare il profiler integrato per identificare i hotspot di CPU/memoria prima del ridimensionamento
Abilitare il tracciamento dei deployment per correlare i cambiamenti di prestazioni con i rilasci