In un mondo di architetture distribuite e microservizi, l’osservabilità è diventata una colonna portante per garantire la stabilità, la gestibilità e l’efficienza delle nostre applicazioni. Capire “cosa sta succedendo” all’interno dei nostri servizi, in produzione e non solo, è cruciale per diagnosticare problemi, monitorare le performance e pianificare aggiornamenti. Un elemento fondamentale per raggiungere l’osservabilità è l’esposizione dei metadati.
Ma cosa intendiamo esattamente per metadati in questo contesto? E perché sono così importanti?
Cosa sono i metadati di un microservizio?
I metadati di un microservizio sono, in breve, “dati sui dati”. Nel contesto delle nostre applicazioni, si tratta di informazioni che descrivono il servizio stesso, il suo ambiente di esecuzione, la versione del codice in esecuzione, le configurazioni e molto altro. Questi dati contestuali, pur non essendo la logica di business principale del servizio, diventano essenziali per operare e gestire il servizio in modo efficace.
Perché esporre i metadati è fondamentale?
Come abbiamo discusso in precedenza, esporre i metadati abilita una serie di benefici chiave.
- Service Discovery: permette ad altri servizi di trovare e comunicare con il tuo microservizio dinamicamente.
- Monitoraggio e Osservabilità: fornisce informazioni vitali per monitorare la salute, le performance e il comportamento del servizio.
- Gestione e Orchestrazione: facilita il deployment, lo scaling e la gestione del ciclo di vita del servizio.
- Documentazione e Comprensione: aiuta a documentare e comprendere l’architettura e le dipendenze dei tuoi microservizi.
- Sicurezza: può contribuire a definire policy di accesso e audit.
L’estensione Quarkus Info: la soluzione semplice ed efficace
Quarkus, il framework Supersonic Subatomic Java e cloud-native, ci viene in aiuto con l’estensione quarkus-info. Questa estensione, incredibilmente semplice da aggiungere e configurare, espone automaticamente una ricca gamma di metadati tramite l’endpoint HTTP /q/info.
In questa guida pratica, vedremo passo passo come integrare l’estensione quarkus-info in un progetto Quarkus esistente e come sfruttare i metadati esposti per migliorare l’osservabilità della tua applicazione. Utilizzeremo come progetto di esempio Quarkus GraphQL Quickstart + MinIO as Object Store S3 i cui sorgenti sono pubblicati su GitHub.
Nota: In questa guida vedrete degli aspetti dell’estensione quarkus-info specifici della versione 3.18.1 di Quarkus rilasciata il 29/01/2025.
Passo 1: aggiungere l’estensione quarkus-info al tuo progetto Quarkus
Per aggiungere questa estensione al tuo progetto Quarkus, esegui il comando appropriato nella directory del progetto. Puoi utilizzare Quarkus CLI, Maven o Gradle. Di seguito, trovi i comandi corrispondenti in ordine.
# Tramite Quarkus CLI
quarkus ext add io.quarkus:quarkus-infoCode language: Bash (bash)# Tramite Maven
./mvnw quarkus:add-extension -Dextensions="io.quarkus:quarkus-info"Code language: Bash (bash)# Tramite Gradle
./gradlew addExtension --extensions="io.quarkus:quarkus-info"Code language: Bash (bash)In ogni caso è possibile agire direttamente sul file pom.xml o build.gradle aggiungendo manualmente la dipendenza. A seguire l’esempio della dipendenza da aggiungere al pom.xml.
<dependency>
<groupId>io.quarkus</groupId>
<artifactId>quarkus-info</artifactId>
</dependency>Code language: HTML, XML (xml)Dopo aver aggiunto la dipendenza e sincronizzato il tuo progetto (ad esempio, eseguendo mvn clean install con Maven o ricaricando il progetto Gradle), l’estensione quarkus-info sarà attiva e pronta all’uso!
Passo 2: avvia l’applicazione e accedi all’endpoint /q/info
Avvia ora la tua applicazione Quarkus in modalità sviluppo (ad esempio, con mvn quarkus:dev o quarkus dev). Una volta che l’applicazione è in esecuzione, puoi accedere all’endpoint /q/info tramite il tuo browser o utilizzando uno strumento come curl.
Apri il tuo browser e naviga all’indirizzo http://localhost:8080/q/info , oppure, apri un terminale ed esegui il comando cURL.
# Chiamata HTTP verso end-point /q/info
curl http://localhost:8080/q/infoCode language: Bash (bash)Dovresti visualizzare una risposta JSON simile a questa (il contenuto esatto varierà a seconda del tuo ambiente e del progetto).
{
"build": {
"artifact": "quarkus-graphql-quickstart",
"enabled": "true",
"group": "it.dontesta.labs.quarkus.graphql",
"name": "quarkus-graphql-quickstart",
"quarkusVersion": "3.18.2",
"time": "2025-02-07T15:54:05.935644+01:00",
"version": "1.0.0-SNAPSHOT"
},
"git": {
"branch": "main",
"commit": {
"id": "689bac488212a182ad323cc525c98dbf09bad1b7",
"time": "2025-02-06T13:42:29+01:00"
}
},
"java": {
"vendor": "Amazon.com Inc.",
"vendorVersion": "Corretto-21.0.2.13.1",
"version": "21.0.2"
},
"os": {
"arch": "aarch64",
"name": "Mac OS X",
"version": "15.3"
}
}Code language: JSON / JSON with Comments (json)Analisi dei metadati esposti
Come puoi vedere, l’endpoint /q/info espone una vasta gamma di metadati strutturati in formato JSON, suddivisi in diverse sezioni:
git: informazioni base sul repository Git, inclusi ramo, commit utilizzato per la build (idetime);java: dettagli sulla Java Virtual Machine (JVM) in esecuzione, come versione, vendor e vendor version;os: informazioni sul sistema operativo su cui l’applicazione è in esecuzione, inclusi nome, versione e architettura.build: informazioni relative al processo di build, versione dell’applicazione, artifact ID, group ID, versione di Quarkus e timestamp della build.
Personalizzare i metadati esposti (opzionale)
L’estensione quarkus-info offre anche un certo grado di personalizzazione. Sebbene la configurazione predefinita sia già molto completa, è possibile aggiungere o rimuovere sezioni o informazioni specifiche tramite configurazione nel file application.properties o application.yml.
Ad esempio, per disabilitare completamente la sezione git, puoi aggiungere la seguente proprietà in application.properties:
quarkus.info.git.enabled=falseCode language: JavaScript (javascript)Potremmo per esempio, ottenere maggiori informazioni che riguardano git, aggiungendo la seguente proprietà quarkus.info.git.mode in application.properties impostando il valore FULL.
quarkus.info.git.mode=FULLQuesta proprietà permette di scegliere tra due modalità di esposizione dei metadati Git: SIMPLE e FULL.
SIMPLE (valore predefinito): in questa modalità (di default non configurando nulla), l’estensione mostra solo le informazioni base su Git. Questo è generalmente sufficiente per scenari standard di build locale o CI/CD. Le informazioni estratte includono:
- ramo corrente (
branch); - informazioni sul commit più recente (
commit), inclusi ID e timestamp.
FULL: impostando quarkus.info.git.mode=FULL, l’estensione Quarkus Info estrae informazioni complete su Git. Questa modalità può essere utile in scenari più complessi o quando si desidera una descrizione Git più dettagliata, inclusi eventuali tag e commit abbreviato, etc.
Con la nuova configurazione (FULL), dovresti visualizzare una risposta JSON simile a questa nella sezione che concerne git.
"git": {
"branch": "main",
"build": {
"host": "amusarra-macbook-pro.local",
"user": {
"email": "antonio.musarra@gmail.com",
"name": "Antonio Musarra"
},
"version": "1.0.0-SNAPSHOT"
},
"commit": {
"author": {
"time": "2025-02-06T13:42:29+01:00"
},
"committer": {
"time": "2025-02-06T13:42:29+01:00"
},
"id": {
"abbrev": "689bac488212a",
"full": "689bac488212a182ad323cc525c98dbf09bad1b7",
"message": {
"full": "Project upgraded to Quarkus 3.18.2",
"short": "Project upgraded to Quarkus 3.18.2"
}
},
"time": "2025-02-06T13:42:29+01:00",
"user": {
"email": "antonio.musarra@gmail.com",
"name": "Antonio Musarra"
}
},
"remote": "https://github.com/amusarra/quarkus-graphql-quickstart.git",
"tags": [
"v1.0.0-rc.01"
]
}Code language: JavaScript (javascript)L’impostazione quarkus.info.git.mode=FULL amplifica i benefici dell’estensione Quarkus Info per l’application discovery fornendo un livello di dettaglio significativamente maggiore sulle informazioni relative alla versione del codice in esecuzione. Vediamo come questo dettaglio extra si traduce in vantaggi concreti.
- Tracciabilità estremamente precisa della versione: mentre la modalità
SIMPLEfornisce l’hash completo del commit e il branch, la modalitàFULLaggiunge informazioni temporali (commit.time), messaggi di commit (commit.short-message,commit.full-message) e dettagli sui tag (tags). Queste informazioni rendono la tracciabilità della versione dell’applicazione in esecuzione estremamente precisa. Non solo si conosce quale commit è in esecuzione, ma anche quando è stato committato, perché (grazie al messaggio di commit), e se è associato a un rilascio ufficiale (grazie ai tag). - Diagnostica avanzata e debugging: in scenari di troubleshooting o debugging, avere l’intero messaggio di commit a disposizione tramite l’endpoint
/q/infopuò essere estremamente utile. Il messaggio di commit spesso descrive in dettaglio le modifiche introdotte da quel commit specifico, offrendo un contesto prezioso per capire il codice in esecuzione e identificare potenziali cause di problemi. La data e ora del commit (commit.time) possono anche aiutare a correlare eventi e log. - Rollback e ripristino di versioni precedenti con maggiore sicurezza: quando si necessita di effettuare un rollback a una versione precedente dell’applicazione, le informazioni complete di Git fornite dalla modalità
FULLrendono il processo più sicuro e meno incline a errori. Si può identificare con precisione la versione esatta a cui si vuole tornare, non solo tramite l’hash del commit, ma anche tramite il timestamp, il messaggio di commit e i tag associati. Questo è cruciale in ambienti di produzione dove l’accuratezza nel rollback è fondamentale. - Audit e conformità: per scopi di audit e conformità, avere un registro dettagliato delle versioni del codice in produzione è spesso un requisito. La modalità
FULLdiquarkus.info.git.modefornisce un modo semplice e standardizzato per esporre queste informazioni, facilitando la generazione di report di audit e la dimostrazione della conformità a determinati standard. - Integrazione con strumenti di gestione del ciclo di vita delle applicazioni (ALM) e DevOps: le informazioni dettagliate di Git fornite dalla modalità
FULLsi integrano meglio con strumenti ALM e DevOps. Questi strumenti possono consumare le informazioni dall’endpoint/q/infoper automatizzare processi come la gestione delle release, il tracciamento delle modifiche, l’analisi dell’impatto delle modifiche, e la correlazione tra codice in produzione e attività di sviluppo.
Quali considerazioni fare sull’utilizzo di questa modalità?
- Performance in build-time: l’estrazione di informazioni Git più dettagliate (specialmente il messaggio di commit completo e i tag) potrebbe richiedere leggermente più tempo durante la fase di build rispetto alla modalità
SIMPLE. Tuttavia, l’impatto sulle performance di build è generalmente trascurabile nella maggior parte dei casi. - Dimensione dell’output: l’output JSON dell’endpoint
/q/infosarà leggermente più grande conquarkus.info.git.mode=FULLa causa delle informazioni aggiuntive. Anche in questo caso, l’aumento di dimensione è solitamente modesto e non dovrebbe rappresentare un problema. - Sensibilità delle informazioni (messaggi di commit): è importante considerare se i messaggi di commit contengono informazioni sensibili che non si desidera esporre tramite l’endpoint
/q/info. In rari casi, i messaggi di commit potrebbero contenere dettagli interni o informazioni di sicurezza che potrebbero essere considerate inappropriate per l’esposizione pubblica. In questi scenari estremamente rari, si potrebbe optare perquarkus.info.git.mode=SIMPLEo valutare attentamente cosa viene committato e se è appropriato includere certe informazioni nei messaggi di commit. Nella maggior parte dei casi, i benefici in termini di tracciabilità e diagnostica superano di gran lunga questo potenziale rischio, e buone pratiche di commit message writing dovrebbero mitigare qualsiasi problema.
È possibile aggiungere informazioni addizionali?
Certamente! L’interfaccia InfoContributor è il meccanismo principale fornito dall’estensione Quarkus Info per permetterti di aggiungere informazioni personalizzate all’endpoint /q/info, andando oltre i metadati predefiniti (Git, Java, OS, Build). Questo è particolarmente utile quando vuoi esporre informazioni specifiche del tuo dominio applicativo, configurazioni custom, o lo stato di componenti esterni.
Vediamo un esempio pratico passo dopo passo su come utilizzare l’interfaccia InfoContributor.
Immagina di voler aggiungere al tuo endpoint /q/info le seguenti informazioni aggiuntive.
- Stato di un feature flag custom: vuoi esporre lo stato di un feature flag chiamato
nuova-dashboard-abilitatache controlla se una nuova funzionalità della dashboard è attiva o meno. - Stato della connessione a MinIO: vuoi indicare se la connessione all’Object Store S3 MinIO è attualmente attiva e funzionante.
Passo 1: Creare una classe che implementa InfoContributor
Il primo passo è creare una nuova classe Java che implementi l’interfaccia io.quarkus.info.runtime.spi.InfoContributor. A seguire vedremo i dettagli su come proseguire con l’implementazione.
Crea una nuova classe Java, ad esempio chiamata CustomInfoContributor.java, nel tuo progetto Quarkus.
package it.dontesta.labs.quarkus.graphql.info.contributor;
import io.quarkus.info.runtime.spi.InfoContributor;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.Map;
@ApplicationScoped
public class CustomInfoContributor implements InfoContributor {
@Override
public String name() {
return "app-detail-info";
}
@Override
public Map<String, Object> data() {
// Add custom information
return Map.of();
}
}
Code language: Java (java)Vediamo quali sono i punti chiave del codice che implementa InfoContributor.
Annotazione @ApplicationScoped:
@ApplicationScoped– fondamentale! Indica che questa classe è un CDI bean e viene gestita dal container CDI di Quarkus, permettendo all’estensione Info di rilevarla e usarla.
Metodo name():
- Scopo di
name(): il metodoname()deve restituire unaStringche identifica univocamente il tuo contributor. Questo nome viene utilizzato dall’estensione Info per organizzare e presentare i metadati. Nel nostro caso il valore restituito èapp-detail-info.
Metodo data():
- Scopo di
data(): il metododata()deve restituire un oggettoMap<String, Object>. È in questoMapche devi inserire i tuoi metadati personalizzati. La chiave della mappa sarà il nome del metadato (es."status","version","feature-flags") e il valore sarà il valore del metadato (che può essere unaString, unNumber, unBoolean, un’altraMap, unaList, ecc.). - Nel tuo esempio di base, sopra mostrato, il metodo
data()restituisceMap.of(), cioè una mappa vuota. Questo significa che al momento non stai aggiungendo alcun metadato personalizzato con questo contributor.
Per tener fede allo scenario sopra descritto, l’implementazione completa della classe CustomInfoContributor è mostrata dal codice a seguire.
package it.dontesta.labs.quarkus.graphql.info.contributor;
import io.quarkus.info.runtime.spi.InfoContributor;
import jakarta.enterprise.context.ApplicationScoped;
import java.util.HashMap;
import java.util.Map;
@ApplicationScoped
public class CustomInfoContributor implements InfoContributor {
@Override
public String name() {
return "app-detail-info";
}
@Override
public Map<String, Object> data() {
Map<String, Object> customData = new HashMap<>();
// Sezione Feature Flags
Map<String, Boolean> featureFlags = new HashMap<>();
featureFlags.put("nuova-dashboard-abilitata", isNuovaDashboardAbilitata());
customData.put("feature-flags", featureFlags);
// Sezione MinIO Connection Status
Map<String, Object> minioInfo = new HashMap<>();
minioInfo.put("status", getMinIOConnectionStatus());
customData.put("minio", minioInfo);
return customData;
}
// Metodo di esempio per simulare lo stato del feature flag
private boolean isNuovaDashboardAbilitata() {
// Sostituisci con la logica reale
return true;
}
// Metodo di esempio per simulare lo stato della connessione MinIO
// Da implementare health check reale.
private String getMinIOConnectionStatus() {
// Sostituisci con la logica di health check MinIO reale
return "UP";
}
}
Code language: Java (java)Passo 2: avviare l’applicazione e verificare l’endpoint /q/info
Avvia nuovamente la tua applicazione Quarkus (es. mvn quarkus:dev o quarkus dev). Ora, se accedi all’endpoint /q/info, dovresti vedere le nuove sezioni feature-flags e minio nel JSON di risposta all’interno di app-detail-info.
{
"app-detail-info": {
"feature-flags": {
"nuova-dashboard-abilitata": true
},
"minio": {
"status": "UP"
}
},
"build": {
// ...
},
"git": {
// ...
},
"java": {
// ...
},
"os": {
// ...
}
}Code language: JSON / JSON with Comments (json)Ora che hai esteso l’endpoint /q/info con informazioni personalizzate, puoi utilizzarle in modo simile ai metadati predefiniti.
L’interfaccia InfoContributor in Quarkus Info è uno strumento potente ed elegante per estendere l’endpoint /q/info con metadati personalizzati. Implementando questa interfaccia e registrando la tua classe come @ApplicationScoped, puoi facilmente arricchire l’osservabilità dei tuoi microservizi Quarkus con informazioni specifiche del tuo dominio applicativo. Ricorda di sostituire i metodi di esempio (isNuovaDashboardAbilitata() e getMinIOConnectionStatus()) con la logica reale per recuperare le informazioni che desideri esporre dal tuo sistema.
Sfruttare i metadati per un osservabilità migliore
Ora che abbiamo visto come esporre i metadati con l’estensione quarkus-info, è importante capire come sfruttare queste informazioni preziose nel mondo reale. Ecco alcuni esempi di come questi metadati possono essere utilizzati.
- Monitoraggio Centralizzato: integra l’endpoint
/q/infocon il tuo sistema di monitoraggio (come Prometheus, Grafana, Datadog, ecc.). Puoi configurare il tuo sistema di monitoraggio per scrape periodicamente l’endpoint/q/infoe visualizzare le informazioni in dashboard personalizzate. Questo ti permette di avere una visione centralizzata delle versioni dei tuoi servizi, dell’ambiente di runtime e di altre informazioni contestuali. - Service Catalog: utilizza i metadati esposti dall’endpoint
/q/infoper popolare un catalogo di servizi centralizzato (come Backstage, Port, Cortex). Il catalogo può utilizzare informazioni come il nome del servizio, la versione, il link al repository Git e altro per fornire una documentazione dinamica e un punto di riferimento unico per tutti i tuoi microservizi. - Troubleshooting e Debugging rapido: in caso di problemi in produzione, l’endpoint
/q/infodiventa uno strumento di diagnostica fondamentale. Puoi rapidamente interrogare l’endpoint per identificare la versione esatta del servizio che sta generando l’errore, il commit di riferimento, la versione di Java e del sistema operativo. Queste informazioni accelerano notevolmente il processo di debugging e ti permettono di isolare più rapidamente la causa del problema. - Audit e Compliance: per scenari che richiedono audit di sicurezza o compliance normativa, avere traccia precisa della versione del codice e dell’ambiente in esecuzione diventa essenziale. L’endpoint
/q/infofornisce un punto di riferimento affidabile per queste informazioni. - Deployment e Rollback controllati: durante i processi di deployment e rollback, puoi utilizzare i metadati esposti per verificare che la versione corretta del servizio sia stata distribuita in ogni ambiente. Puoi automatizzare controlli post-deployment che verificano la versione tramite l’endpoint
/q/infoprima di considerare un deployment completato.
Conclusioni
L’estensione quarkus-info è un piccolo ma potente strumento che semplifica enormemente l’esposizione dei metadati nei tuoi microservizi Quarkus. Aggiungendo una semplice dipendenza e senza richiedere configurazioni complesse, puoi abilitare un endpoint /q/info ricco di informazioni preziose per l’osservabilità, la gestione e la robustezza delle tue applicazioni.
Integrare l’estensione quarkus-info nei tuoi progetti Quarkus è un investimento a basso costo con un ritorno elevato in termini di gestione e comprensione del tuo ecosistema di microservizi. Inizia oggi stesso ad esporre i metadati e rendi i tuoi microservizi più intelligenti, gestibili e pronti per affrontare le sfide del mondo reale!
