Logging e Tracing in GraphQL: Monitoraggio e Debug delle API

Codegrind Team•Sep 03 2024

Il logging e il tracing sono componenti essenziali per il monitoraggio e il debugging delle API, inclusi quelli basati su GraphQL. Poiché GraphQL è flessibile e consente query complesse, è importante avere una visibilità chiara su quali richieste vengono effettuate, quanto tempo richiedono e dove potrebbero verificarsi eventuali errori o colli di bottiglia. In questo articolo esploreremo come implementare logging e tracing nelle API GraphQL, e come queste tecniche possono aiutarti a monitorare e ottimizzare le performance.

Differenza tra Logging e Tracing

Logging: Si riferisce alla registrazione di informazioni utili su ciò che sta accadendo all’interno dell’applicazione. Questi log possono contenere dettagli sulle richieste in arrivo, sugli errori e su eventi specifici che si verificano durante l’esecuzione di query o mutazioni.
Tracing: Riguarda il tracciamento delle performance e dei tempi di esecuzione di varie operazioni all’interno dell’API, permettendo di capire dove si trovano i colli di bottiglia. Con il tracing, puoi monitorare il tempo di esecuzione di query e risolutori specifici.

Logging in GraphQL

Il logging è utile per tenere traccia delle query in arrivo, registrare gli errori e avere una panoramica di ciò che sta accadendo nel server GraphQL. Il logging può essere integrato utilizzando librerie come Winston o semplicemente implementando funzioni personalizzate.

Step 1: Installazione di una Libreria di Logging

Iniziamo installando Winston, una delle librerie più popolari per il logging in Node.js.

npm install winston

Step 2: Configurazione del Logger

Configura Winston per registrare i log su file o sulla console:

const winston = require("winston");

const logger = winston.createLogger({
  level: "info",
  format: winston.format.combine(
    winston.format.timestamp(),
    winston.format.json()
  ),
  transports: [
    new winston.transports.Console(),
    new winston.transports.File({ filename: "graphql.log" }),
  ],
});

module.exports = logger;

Step 3: Logging nelle Richieste GraphQL

Aggiungi il logging nel contesto di Apollo Server, in modo da poter registrare ogni richiesta GraphQL in arrivo.

const { ApolloServer, gql } = require("apollo-server");
const logger = require("./logger");

// Definisci lo schema GraphQL
const typeDefs = gql`
  type Query {
    hello: String
  }
`;

// Definisci i resolver
const resolvers = {
  Query: {
    hello: () => "Hello World",
  },
};

// Configura Apollo Server
const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => {
    const startTime = Date.now();
    logger.info(`Query ricevuta: ${req.body.query}`);

    return {
      logger,
      startTime,
    };
  },
  formatResponse: (response, { context }) => {
    const endTime = Date.now();
    const executionTime = endTime - context.startTime;
    logger.info(`Query eseguita in: ${executionTime}ms`);
    return response;
  },
  formatError: (error) => {
    logger.error(`Errore GraphQL: ${error.message}`);
    return error;
  },
});

// Avvia il server
server.listen().then(({ url }) => {
  logger.info(`Server GraphQL in esecuzione su ${url}`);
});

Logging degli Errori

Grazie alla configurazione di formatError, ogni errore che si verifica nel server GraphQL viene registrato nei log. Questo è particolarmente utile per il debugging, poiché fornisce informazioni dettagliate sugli errori che si verificano durante l’esecuzione di una query o una mutazione.

Logging delle Prestazioni

Utilizzando il context e formatResponse, puoi registrare il tempo di esecuzione di ogni query o mutazione, utile per identificare query che richiedono troppo tempo e per ottimizzare le prestazioni del server.

Tracing in GraphQL

Il tracing consente di monitorare in modo dettagliato il tempo impiegato da ogni risolutore per eseguire le operazioni. Questo è essenziale per identificare colli di bottiglia nelle query complesse, dove più risolutori sono coinvolti.

Step 1: Abilitare il Tracing con Apollo Server

Apollo Server offre il supporto integrato per il tracing. Puoi abilitarlo facilmente aggiungendo la configurazione tracing: true:

const server = new ApolloServer({
  typeDefs,
  resolvers,
  tracing: true, // Abilita il tracing
});

Step 2: Visualizzare i Dati di Tracing

Una volta abilitato il tracing, Apollo Server fornisce informazioni dettagliate sul tempo di esecuzione di ciascun risolutore. Eseguendo una query, riceverai un oggetto extensions nella risposta che contiene i dati di tracing:

{
  "data": {
    "hello": "Hello World"
  },
  "extensions": {
    "tracing": {
      "version": 1,
      "startTime": "2024-09-03T12:00:00.000Z",
      "endTime": "2024-09-03T12:00:01.000Z",
      "duration": 1000000,
      "execution": {
        "resolvers": [
          {
            "path": ["hello"],
            "parentType": "Query",
            "fieldName": "hello",
            "returnType": "String",
            "startOffset": 1000,
            "duration": 500000
          }
        ]
      }
    }
  }
}

Questo oggetto ti permette di analizzare quanto tempo impiega ogni risolutore a completare la propria operazione, aiutandoti a identificare eventuali rallentamenti.

Step 3: Monitoraggio del Tracing

Oltre alla configurazione nativa di Apollo Server, puoi utilizzare strumenti esterni come Apollo Studio per monitorare il tracing delle query. Apollo Studio ti offre una dashboard grafica che visualizza i tempi di esecuzione, rendendo più facile identificare e risolvere i problemi di performance.

Logging e Tracing Avanzato con strumenti esterni

Se hai bisogno di un livello di logging e tracing ancora più avanzato, puoi integrare strumenti come Datadog, Prometheus o Grafana per raccogliere e visualizzare i log e i dati di tracing in modo centralizzato. Questi strumenti ti permettono di:

Monitorare le metriche delle performance dell’API in tempo reale.
Ottenere avvisi quando le query superano determinati tempi di esecuzione.
Analizzare i log per identificare pattern o errori ricorrenti.

Esempio con Datadog

Con Datadog, puoi inviare metriche di tracing e logging per visualizzarle in una dashboard personalizzata. Per farlo, puoi usare l’integrazione con il package Datadog:

npm install dd-trace

E configurare Datadog nel tuo server GraphQL:

const tracer = require("dd-trace").init();

const server = new ApolloServer({
  typeDefs,
  resolvers,
  context: ({ req }) => {
    tracer.trace("graphql.query", {
      resource: req.body.query,
    });

    return {
      logger,
    };
  },
});

Best Practices per il Logging e il Tracing in GraphQL

Livelli di Logging: Usa livelli di logging appropriati (info, warn, error) per classificare le informazioni che registri. Ad esempio, usa info per le query ricevute, warn per le query lente e error per gli errori critici.
Tracing delle Query Lente: Utilizza il tracing per monitorare query che richiedono troppo tempo, specialmente nelle applicazioni con query complesse o molte relazioni tra i dati.
Integrazione con Dashboard di Monitoraggio: Integra strumenti come Apollo Studio o Datadog per raccogliere, analizzare e visualizzare le metriche di logging e tracing.
Ridurre i Log Inutili: Evita di registrare eccessivamente le query, soprattutto in ambienti di produzione, per non generare grandi quantità di log difficili da analizzare.
Gestione degli Errori: Registra sempre gli errori delle query e delle mutazioni. Assicurati di restituire messaggi di errore dettagliati nei log, ma evita di esporre troppe informazioni sensibili al client.

Conclusione

Logging e tracing sono strumenti fondamentali per monitorare, ottimizzare e mantenere

le API GraphQL performanti e affidabili. Con una corretta implementazione del logging, puoi ottenere una visione chiara delle richieste, degli errori e delle performance della tua API. Il tracing ti aiuta a identificare i colli di bottiglia, specialmente nelle query complesse che coinvolgono più risolutori.

Integrando questi strumenti, puoi assicurarti che la tua API GraphQL sia pronta per la produzione, facilmente manutenibile e ottimizzata per le migliori performance.