Instrada i log alle destinazioni supportate

Questo documento spiega come creare e gestire i sink, che indirizzano le voci di log generate in un progetto Google Cloud alle destinazioni supportate.

Quando la destinazione di un sink non è un bucket di log nel progetto Google Cloud da cui ha origine una voce di log, è necessario un account di servizio. Cloud Logging crea e gestisce automaticamente questo account di servizio. Tuttavia, potrebbe essere necessario modificare le autorizzazioni concesse all'account di servizio. Puoi creare e gestire un account di servizio utilizzato dagli sink in più progetti. Per ulteriori informazioni, consulta Configurare i canali di log con account di servizio gestiti dall'utente.

Panoramica

I sink determinano in che modo Cloud Logging instrada le voci di log. Utilizzando i canali, puoi inoltrare alcune o tutte le voci del log alle seguenti destinazioni:

  • Bucket Cloud Logging: fornisce spazio di archiviazione in Cloud Logging. Un bucket di log può memorizzare le voci di log ricevute da più progetti Google Cloud. Il bucket dei log può trovarsi nello stesso progetto in cui hanno origine le voci di log o in un progetto diverso. Per informazioni su come visualizzare le voci di log archiviate nei bucket di log, consulta Panoramica delle query e della visualizzazione dei log e Visualizzare i log inviati ai bucket di Cloud Logging.

    Puoi combinare i dati di Cloud Logging con altri dati eseguendo l'upgrade di un bucket di log per l'utilizzo di Log Analytics e poi creando un set di dati collegato, ovvero un set di dati di sola lettura su cui è possibile eseguire query dalle pagine BigQuery Studio e Looker Studio.

  • Set di dati BigQuery: fornisce lo spazio di archiviazione delle voci di log in un set di dati BigQuery scrivibile. Il set di dati BigQuery può trovarsi nello stesso progetto in cui hanno origine le voci di log o in un progetto diverso. Puoi utilizzare le funzionalità di analisi dei big data sulle voci di log archiviate. Per informazioni su come visualizzare le voci di log inviate a BigQuery, consulta Visualizzare i log inviati a BigQuery.

  • Bucket Cloud Storage: fornisce lo spazio di archiviazione delle voci di log in Cloud Storage. Il bucket Cloud Storage può trovarsi nello stesso progetto in cui hanno avuto origine le voci di log o in un progetto diverso. Le voci di log vengono archiviate come file JSON. Per informazioni su come visualizzare le voci di log inoltrate a Cloud Storage, consulta Visualizzare i log inoltrati a Cloud Storage.

  • Argomento Pub/Sub: fornisce il supporto per le integrazioni di terze parti. Le voci di log vengono formattate in JSON e poi inoltrate a un argomento Pub/Sub. L'argomento può trovarsi nello stesso progetto in cui hanno avuto origine le voci di log o in un progetto diverso. Per informazioni su come visualizzare le voci di log con routing a Pub/Sub, consulta Visualizzare i log con routing a Pub/Sub.

  • Progetto Google Cloud: inoltra le voci di log a un altro progetto Google Cloud. In questa configurazione, i sink nel progetto di destinazione elaborano le voci di log.

I canali appartengono a una determinata risorsa Google Cloud: un progetto Google Cloud, un account di fatturazione, una cartella o un'organizzazione. Quando la risorsa riceve una voce di log, ogni destinazione nella risorsa la elabora. Quando una voce di log corrisponde ai filtri del sink, viene inoltrata alla destinazione del sink.

In genere, i sink inoltrano solo le voci di log che hanno origine in una risorsa. Tuttavia, per le cartelle e le organizzazioni puoi creare sink aggregati, che indirizzano le voci di log dalla cartella o dall'organizzazione e dalle risorse che contengono. Questo documento non tratta i canali aggregati. Per ulteriori informazioni, consulta la sezione Raccogliere e instradare i log a livello di organizzazione verso le destinazioni supportate.

Per creare e gestire i canali di destinazione, puoi utilizzare la console Google Cloud, l'API Cloud Logging e Google Cloud CLI. Ti consigliamo di utilizzare la console Google Cloud:

  • La pagina Router dei log elenca tutti i sink e fornisce opzioni per gestirli.
  • Quando crei un sink, puoi visualizzare l'anteprima delle voci di log corrispondenti ai filtri del sink.
  • Puoi configurare le destinazioni del sink quando ne crei uno.
  • Alcuni passaggi di autorizzazione sono stati completati per tuo conto.

Prima di iniziare

Le istruzioni riportate in questo documento descrivono la creazione e la gestione dei sink a livello di progetto Google Cloud. Puoi utilizzare la stessa procedura per creare un sink che indirizzi le voci di log originate in un'organizzazione, una cartella o un account di fatturazione.

Per iniziare:

  1. Enable the Cloud Logging API.

    Enable the API

  2. Assicurati che il tuo progetto Google Cloud contenga voci di log che puoi visualizzare in Esplora log.

  3. Per ottenere le autorizzazioni necessarie per creare, modificare o eliminare un'area di destinazione, chiedi all'amministratore di concederti il ruolo IAM Editor di configurazione dei log (roles/logging.configWriter) nel progetto. Per saperne di più sulla concessione dei ruoli, consulta Gestire l'accesso a progetti, cartelle e organizzazioni.

    Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

    Per informazioni sulla concessione dei ruoli IAM, consulta la guida al controllo dell'accesso di Logging.

  4. Hai una risorsa in una destinazione supportata o hai la possibilità di crearne una.

    Per instradare le voci di log a una destinazione, la destinazione deve esistere prima di creare il sink. Puoi creare la destinazione in qualsiasi progetto Google Cloud di qualsiasi organizzazione.

  5. Prima di creare un sink, esamina le limitazioni che si applicano alla destinazione del sink. Per ulteriori informazioni, consulta la sezione Limitazioni per le destinazioni di questo documento.

  6. Select the tab for how you plan to use the samples on this page:

    Console

    When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

    gcloud

    In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

    REST

    Per utilizzare gli esempi dell'API REST in questa pagina in un ambiente di sviluppo locale, utilizza le credenziali fornite a gcloud CLI.

      Install the Google Cloud CLI, then initialize it by running the following command: 

      gcloud init

    Per saperne di più, consulta Eseguire l'autenticazione per l'utilizzo di REST nella documentazione sull'autenticazione di Google Cloud.

Creazione di un sink

Di seguito sono riportate le istruzioni per creare un sink in un progetto Google Cloud. Puoi utilizzare la stessa procedura per instradare le voci di log che hanno origine in un'organizzazione, una cartella o un account di fatturazione:

  • Puoi creare fino a 200 sink per progetto Google Cloud.
  • Non inserire informazioni sensibili nei filtri di destinazione. I filtri di destinazione vengono trattati come dati di servizio.
  • Potrebbero essere necessarie diverse ore per iniziare a instradare le voci di log dei nuovi sink per i bucket Cloud Storage. I sink per Cloud Storage vengono elaborati ogni ora, mentre gli altri tipi di destinazione vengono elaborati in tempo reale.

  • I sink non possono inoltrare le voci di log ai set di dati BigQuery collegati, che sono di sola lettura. Se vuoi instradare le voci di log in BigQuery, il set di dati di destinazione deve essere abilitato alla scrittura.

  • I sink non definiscono lo schema per i set di dati BigQuery. La prima voce di log ricevuta da BigQuery determina invece lo schema della tabella di destinazione. Per ulteriori informazioni, consulta Schema di BigQuery per i log instradati.

  • Per informazioni su come visualizzare le voci di log nella destinazione di un sink, consulta Visualizzare i log instradati ai bucket Cloud Logging.

  • Per visualizzare il numero e il volume delle voci di log instradate, consulta le metriche logging.googleapis.com/exports/.

  • Quando una query contiene più istruzioni, puoi specificare come vengono unite o fare affidamento su Cloud Logging aggiungendo implicitamente la restrizione congiuntiva AND tra le istruzioni. Ad esempio, supponiamo che una finestra di dialogo di query o filtro contenga due istruzioni, resource.type = "gce_instance" e severity >= "ERROR". La query effettiva è resource.type = "gce_instance" AND severity >= "ERROR". Cloud Logging supporta sia le limitazioni disgiuntive, OR, sia quelle congiuntive, AND. Quando utilizzi le istruzioni OR, ti consigliamo di agrupare le clausole con le parentesi. Per ulteriori informazioni, consulta il linguaggio delle query di Logging.

Per creare un sink:

Console

  1. Nella console Google Cloud, vai alla pagina Log Router:

    Vai a Router dei log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Seleziona il progetto Google Cloud in cui hanno origine le voci di log che vuoi instradare.

    Ad esempio, se vuoi instradare le voci di log di accesso ai dati dal progetto Project-A a un bucket di log nel progetto Project-B, seleziona Project-A.

  3. Seleziona Crea sink.

  4. Nel riquadro Dettagli sink, inserisci i seguenti dettagli:

    • Nome del canale: fornisci un identificatore per il canale. Tieni presente che, dopo aver creato il canale, non puoi rinominarlo, ma puoi eliminarlo e crearne uno nuovo.

    • (Facoltativo) Descrizione della destinazione: descrivi lo scopo o il caso d'uso della destinazione.

  5. Nel riquadro Destinazione sink, seleziona il servizio sink e la destinazione utilizzando il menu Seleziona il servizio sink. Esegui una delle seguenti operazioni:

    • Per inoltrare le voci di log a un servizio nello stesso progetto Google Cloud, seleziona una delle seguenti opzioni:

      • Set di dati BigQuery: seleziona o crea il set di dati scrivibile per ricevere le voci di log instradate. Hai anche la possibilità di utilizzare le tabelle partizionate.
      • Bucket Cloud Storage: seleziona o crea il bucket Cloud Storage specifico per ricevere le voci di log instradate.
      • Argomento Pub/Sub: seleziona o crea l'argomento specifico per ricevere le voci di log instradate.
      • Splunk: seleziona l'argomento Pub/Sub per il servizio Splunk.

    • Per instradare le voci di log a un altro progetto Google Cloud, selezionate Progetto Google Cloud e poi inserite il nome completo della destinazione. Per informazioni sulla sintassi, consulta la sezione Formati dei percorsi di destinazione.

    • Per instradare le voci di log a un servizio in un altro progetto Google Cloud, procedi nel seguente modo:

      1. Seleziona Altra risorsa.
      2. Inserisci il nome completo della destinazione. Per informazioni sulla sintassi, consulta la sezione Formati dei percorsi di destinazione.

  6. Specifica le voci di log da includere:

    1. Vai al riquadro Scegli i log da includere nel sink.

    2. Nel campo Crea filtro di inclusione, inserisci un'espressione di filtro corrispondente alle voci di log da includere. Per scoprire di più sulla sintassi per la scrittura dei filtri, consulta Linguaggio delle query di logging.

      Se non imposti un filtro, tutte le voci di log della risorsa selezionata vengono inoltrate alla destinazione.

      Ad esempio, per inoltrare tutte le voci di log di accesso ai dati a un bucket di logging, puoi utilizzare il seguente filtro:

      log_id("cloudaudit.googleapis.com/data_access") OR log_id("externalaudit.googleapis.com/data_access")

      La lunghezza di un filtro non può superare i 20.000 caratteri.

    3. Per verificare di aver inserito il filtro corretto, seleziona Anteprima dei log. Esplora log si apre in una nuova scheda con il filtro precompilato.

  7. (Facoltativo) Configura un filtro di esclusione per eliminare alcune delle voci di log incluse:

    1. Vai al riquadro Scegli i log da escludere dal sink.

    2. Nel campo Nome filtro di esclusione, inserisci un nome.

    3. Nel campo Crea un filtro di esclusione, inserisci un'espressione filtro che corrisponda alle voci di log che vuoi escludere. Puoi anche utilizzare la funzione sample per selezionare una parte delle voci di log da escludere.

    Puoi creare fino a 50 filtri di esclusione per sink. Tieni presente che la lunghezza di un filtro non può superare i 20.000 caratteri.

  8. Seleziona Crea sink.

  9. Concedi all'account di servizio del sink l'autorizzazione per scrivere voci di log nella destinazione del sink. Per ulteriori informazioni, consulta Impostare le autorizzazioni di destinazione.

gcloud

Per creare un sink:

  1. Esegui il seguente comando gcloud logging sinks create:

    gcloud logging sinks create SINK_NAME SINK_DESTINATION

    Prima di eseguire il comando, effettua le seguenti sostituzioni:

    • SINK_NAME: il nome del sink di log. Non puoi modificare il nome di un sink dopo averlo creato.

    • SINK_DESTINATION: il servizio o il progetto a cui vuoi inoltrare le voci di log. Imposta SINK_DESTINATION con il percorso appropriato, come descritto in Formati dei percorsi di destinazione.

      Ad esempio, se la destinazione di destinazione è un argomento Pub/Sub, SINK_DESTINATION ha il seguente aspetto:

      pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

    Puoi anche fornire le seguenti opzioni:

    • --log-filter : utilizza questa opzione per impostare un filtro che corrisponda alle voci di log che vuoi includere nel tuo sink. Se non fornisci un valore per il filtro di inclusione, questo filtro corrisponde a tutte le voci di log.
    • --exclusion: utilizza questa opzione per impostare un filtro di esclusione per le voci di log da cui vuoi escludere il routing del sink. Puoi anche utilizzare la funzione sample per selezionare una parte delle voci di log da escludere. Questa opzione può essere ripetuta; puoi creare fino a 50 filtri di esclusione per destinazione.
    • --description: utilizza questa opzione per descrivere lo scopo o il caso d'uso per la destinazione.

    Ad esempio, per creare un sink in un bucket Logging, il comando potrebbe avere il seguente aspetto:

    gcloud logging sinks create my-sink logging.googleapis.com/projects/myproject123/locations/global/buckets/my-bucket \
 --log-filter='logName="projects/myproject123/logs/matched"' --description="My first sink"

    Per ulteriori informazioni sulla creazione di sink utilizzando Google Cloud CLI, consulta la documentazione di riferimento gcloud logging sinks.

  2. Se la risposta del comando contiene una chiave JSON etichettata come "writerIdentity", concedi all'account di servizio della destinazione l'autorizzazione di scrittura per la destinazione. Per ulteriori informazioni, consulta Impostare le autorizzazioni di destinazione.

    Non è necessario impostare le autorizzazioni di destinazione quando la risposta non contiene una chiave JSON etichettata "writerIdentity".

REST

  1. Per creare un'area di destinazione per i log nel tuo progetto Google Cloud, utilizza projects.sinks.create nell'API Logging. Nell'oggetto LogSink, fornisci i valori obbligatori appropriati nel corpo della richiesta del metodo:

    • name: un identificatore per la destinazione. Tieni presente che, una volta creato il canale, non puoi rinominarlo, ma puoi eliminarlo e crearne uno nuovo.

    • destination: il servizio e la destinazione a cui vuoi inoltrare le voci del log. Per instradare le voci di log a un progetto diverso o a una destinazione che si trova in un altro progetto, imposta il campo destination con il percorso appropriato, come descritto in Formati dei percorsi di destinazione.

      Ad esempio, se la destinazione di destinazione è un argomento Pub/Sub, destination ha il seguente aspetto:

      pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

  2. Nell'oggetto LogSink, fornisci le informazioni facoltative appropriate:

    • filter : imposta il campo filter in modo che corrisponda alle voci di log che vuoi includere nel sink. Se non imposti un filtro, tutte le voci di log del tuo progetto Google Cloud vengono indirizzate alla destinazione. Tieni presente che la lunghezza di un filtro non può superare i 20.000 caratteri.
    • exclusions: imposta questo campo in modo che corrisponda alle voci di log da escludere dal sink. Puoi anche utilizzare la funzione sample per selezionare una parte delle voci di log da escludere. Puoi creare fino a 50 filtri di esclusione per destinazione.
    • description: imposta questo campo per descrivere lo scopo o il caso d'uso del canale.

  3. Chiama projects.sinks.create per creare il sink.

  4. Se la risposta dell'API contiene una chiave JSON etichettata come "writerIdentity", concedi all'account di servizio della destinazione l'autorizzazione di scrittura nella destinazione. Per ulteriori informazioni, consulta Impostare le autorizzazioni di destinazione.

    Non è necessario impostare le autorizzazioni di destinazione quando la risposta dell'API non contiene una chiave JSON etichettata come "writerIdentity".

Per ulteriori informazioni sulla creazione di sink utilizzando l'API Logging, consulta la pagina di riferimento LogSink.

Se ricevi notifiche di errore, consulta Risolvere i problemi relativi a routing e sink.

Formati dei percorsi di destinazione

Se inoltri le voci di log a un servizio in un altro progetto, devi fornire all'obiettivo il nome completo del servizio. Analogamente, se indirizzi le voci di log a un altro progetto Google Cloud, devi fornire all'obiettivo il nome completo del progetto di destinazione:

  • Bucket dei log di Cloud Logging:

    logging.googleapis.com/projects/DESTINATION_PROJECT_ID/locations/LOCATION/buckets/BUCKET_NAME

  • Un altro progetto Google Cloud:

    logging.googleapis.com/projects/DESTINATION_PROJECT_ID

  • Set di dati BigQuery:

    bigquery.googleapis.com/projects/PROJECT_ID/datasets/DATASET_ID

  • Cloud Storage:

    storage.googleapis.com/BUCKET_NAME

  • Argomento Pub/Sub:

    pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID

Gestire i sink

Dopo aver creato i canali, puoi eseguire le seguenti azioni. L'applicazione di eventuali modifiche apportate a un sink potrebbe richiedere alcuni minuti:

  • Visualizza dettagli
  • Aggiorna

  • Disattiva

    • Non puoi disattivare il sink _Required.
    • Puoi disattivare il sink _Default per impedire il routing delle voci di log al _Default bucket Logging.
    • Se vuoi disattivare l'esegui migrazione _Default per i nuovi progetti o le nuove cartelle Google Cloud creati nella tua organizzazione, valuta la possibilità di configurare le impostazioni predefinite delle risorse.

  • Elimina

    • Non puoi eliminare i sink _Default o _Required.
    • Quando elimini un'area di destinazione, questa non inoltra più le voci di log.
    • Se la destinazione ha un account di servizio dedicato, l'eliminazione della destinazione comporta anche l'eliminazione dell'account di servizio. I canali creati prima del 22 maggio 2023 hanno account di servizio dedicati. I canali di destinazione creati il 22 maggio 2023 o successivamente hanno un account di servizio condiviso. L'eliminazione della destinazione non comporta l'eliminazione dell'account di servizio condiviso.

  • Risolvere i problemi di errore

  • Visualizza il volume di log e i tassi di errore

Di seguito sono riportate le istruzioni per gestire un sink in un progetto Google Cloud. Anziché un progetto Google Cloud, puoi specificare un account di fatturazione, una cartella o un'organizzazione:

Console

  1. Nella console Google Cloud, vai alla pagina Log Router:

    Vai a Router dei log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Nella barra degli strumenti, seleziona la risorsa che contiene l'eseguitore sink. La risorsa può essere un progetto, una cartella, un'organizzazione o un account di fatturazione.

La pagina Router dei log mostra i sink nella risorsa selezionata. Ogni riga della tabella contiene informazioni sulle proprietà di un'area di destinazione:

  • Abilitato: indica se lo stato della destinazione è attivo o disattivato.
  • Tipo: il servizio di destinazione del sink, ad esempio Cloud Logging bucket.
  • Nome: l'identificatore della destinazione, fornito al momento della creazione; ad esempio _Default.
  • Descrizione: la descrizione del sink, fornita al momento della sua creazione.
  • Destinazione: nome completo della destinazione a cui vengono inviate le voci del log indirizzate.
  • Created: la data e l'ora di creazione dell'eseguitore di importazione.
  • Ultimo aggiornamento: la data e l'ora dell'ultima modifica dell'eseguitore di importazione.

Per ogni riga della tabella, il menu Altre azioni offre le seguenti opzioni:

  • Visualizza i dettagli della destinazione: vengono visualizzati il nome, la descrizione, il servizio di destinazione, la destinazione e i filtri di inclusione ed esclusione della destinazione. Se selezioni Modifica, si apre il riquadro Modifica sink.
  • Modifica sink: apre il riquadro Modifica sink in cui puoi aggiornare i parametri del sink.
  • Disattiva sink: consente di disattivare il sink e interrompere il routing delle voci di log alla destinazione del sink. Per ulteriori informazioni sull'esclusione dei sink, consulta Interrompere l'archiviazione dei log nei bucket dei log.
  • Attiva sink: ti consente di attivare un sink disattivato e di riavviare il routing delle voci di log alla destinazione del sink.
  • Elimina destinazione: consente di eliminare la destinazione e interrompere il routing delle voci di log alla destinazione.
  • Risolvi i problemi relativi al sink: apre Esplora log, dove puoi risolvere i problemi relativi al sink.
  • Visualizza volume di log e tassi di errore del sink: apre Metrics Explorer, dove puoi visualizzare e analizzare i dati del sink.

Per ordinare la tabella in base a una colonna, seleziona il nome della colonna.

gcloud

  • Per visualizzare l'elenco dei canali per il tuo progetto Google Cloud, utilizza il comando gcloud logging sinks list che corrisponde al metodo dell'API Logging projects.sinks.list:

    gcloud logging sinks list

    Per visualizzare l'elenco dei sink aggregati, utilizza l'opzione appropriata per specificare la risorsa che contiene il sink. Ad esempio, se hai creato il canale a livello di organizzazione, utilizza l'opzione --organization=ORGANIZATION_ID per elencare i canali per l'organizzazione.

  • Per descrivere un'area di destinazione, utilizza il comando gcloud logging sinks describe, che corrisponde al metodo dell'API Logging projects.sinks.get:

    gcloud logging sinks describe SINK_NAME

  • Per aggiornare un sink, utilizza il comando gcloud logging sinks update che corrisponde al metodo API projects.sink.update.

    Puoi aggiornare un sink per modificare la destinazione, i filtri e la descrizione oppure per disattivarlo o riattivarlo:

    gcloud logging sinks update SINK_NAME NEW_DESTINATION --log-filter=NEW_FILTER

    Ometti NEW_DESTINATION o --log-filter se queste parti non cambiano.

    Ad esempio, per aggiornare la destinazione dell'emissario my-project-sink con una nuova destinazione del bucket Cloud Storage my-second-gcs-bucket, il comando sarà il seguente:

    gcloud logging sinks update  my-project-sink storage.googleapis.com/my-second-gcs-bucket

  • Per disattivare un canale di destinazione, utilizza il comando gcloud logging sinks update che corrisponde al metodo dell'API projects.sink.update e includi l'opzione --disabled:

    gcloud logging sinks update SINK_NAME --disabled

    Per riattivare il canale, utilizza il comando gcloud logging sinks update rimuovi l'opzione --disabled e includi l'opzione --no-disabled:

    gcloud logging sinks update SINK_NAME --no-disabled

  • Per eliminare un sink, utilizza il comando gcloud logging sinks delete che corrisponde al metodo dell'API projects.sinks.delete:

    gcloud logging sinks delete SINK_NAME

    Per ulteriori informazioni sulla gestione degli scoli utilizzando Google Cloud CLI, consulta la documentazione di riferimento gcloud logging sinks.

REST

  • Per visualizzare i canali per il tuo progetto Google Cloud, chiama projects.sinks.list.

  • Per visualizzare i dettagli di un'area di destinazione, chiama projects.sinks.get.

  • Per aggiornare un sink, chiama projects.sink.update.

    Puoi aggiornare la destinazione, i filtri e la descrizione di un sink. Puoi anche disabilitare o riattivare il sink.

  • Per disattivare un'area di destinazione, imposta il campo disabled nell'oggetto LogSink su true e poi chiama projects.sink.update.

    Per riattivare l'emissario, imposta il campo disabled nell'oggetto LogSink su false e poi chiama projects.sink.update.

  • Per eliminare un'area di destinazione, chiama projects.sinks.delete.

    Per ulteriori informazioni sulla gestione degli sink tramite l'API Logging, consulta la documentazione di riferimento LogSink.

Interrompi l'archiviazione delle voci di log nei bucket di log

Puoi disattivare l'emissario _Default e qualsiasi altro emissario definito dall'utente. Quando disattivi un sink, questo smette di inoltrare le voci di log alla destinazione. Ad esempio, se disattivi il sink _Default, nessuna voce di log viene indirizzata al bucket _Default. Il _Default bucket diventa vuoto quando tutte le voci di log memorizzate in precedenza hanno soddisfatto il periodo di conservazione del bucket.

Le istruzioni riportate di seguito illustrano come disabilitare i sink del progetto Google Cloud che indirizzano le voci di log ai bucket di log _Default:

Console

  1. Nella console Google Cloud, vai alla pagina Log Router:

    Vai a Router dei log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Per trovare tutti i sink che instradano le voci di log al bucket di log _Default, filtra i sink per destinazione e inserisci _Default.

  3. Per ogni canale di destinazione, seleziona Menu e poi Disattiva canale di destinazione.

    I sink sono ora disattivati e i sink del progetto Google Cloud non indirizzano più le voci di log al bucket _Default.

Per riattivare un sink disattivato e riavviare il routing delle voci di log alla destinazione del sink, procedi nel seguente modo:

  1. Nella console Google Cloud, vai alla pagina Log Router:

    Vai a Router dei log

    Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

  2. Per trovare tutti i sink che instradano le voci di log al bucket di log _Default, filtra i sink per destinazione e inserisci _Default.
  3. Per ogni canale di destinazione, seleziona Menu e poi Attiva canale di destinazione.

gcloud

  1. Per visualizzare l'elenco dei canali per il tuo progetto Google Cloud, utilizza il comando gcloud logging sinks list che corrisponde al metodo dell'API Logging projects.sinks.list:

    gcloud logging sinks list

  2. Identifica eventuali sink che indirizzano i dati al bucket dei log _Default. Per descrivere un'area di destinazione, incluso il nome della destinazione, utilizza il comando gcloud logging sinks describe, che corrisponde al metodo dell'API Logging projects.sinks.get:

    gcloud logging sinks describe SINK_NAME

  3. Esegui il comando gcloud logging sinks update e includi l'opzione --disabled. Ad esempio, per disattivare il sink _Default, utilizza il seguente comando:

    gcloud logging sinks update _Default  --disabled

    Il canale di destinazione _Default è ora disattivato e non inoltra più le voci di log al bucket dei log _Default.

Per disattivare gli altri sink nel progetto Google Cloud che indirizzano i dati al bucket _Default, ripeti i passaggi precedenti.

Per riattivare un'area di destinazione, utilizza il comando gcloud logging sinks update rimuovi l'opzione --disabled e includi l'opzione --no-disabled:

gcloud logging sinks update _Default  --no-disabled

REST

  1. Per visualizzare i canali di destinazione per il tuo progetto Google Cloud, chiama il metodo projects.sinks.list dell'API Logging.

    Identifica eventuali sink che indirizzano i dati al bucket _Default.

  2. Ad esempio, per disattivare l'emissario _Default, imposta il campo disabled nell'oggetto LogSink su true e poi chiama projects.sink.update.

    Il sink _Default è ora disattivato e non inoltra più le voci di log al bucket _Default.

Per disattivare gli altri sink nel progetto Google Cloud che indirizzano i dati al bucket _Default, ripeti i passaggi precedenti.

Per riattivare un sink, imposta il campo disabled nell'oggetto LogSink su false e poi chiama projects.sink.update.

Impostare le autorizzazioni di destinazione

Questa sezione descrive come concedere a Logging le autorizzazioni Identity and Access Management per scrivere le voci di log nella destinazione dell'eseguibile sink. Per l'elenco completo dei ruoli e delle autorizzazioni di Logging, consulta Controllo dell'accesso.

Cloud Logging crea un account di servizio condiviso per una risorsa quando viene creato un flusso, a meno che l'account di servizio richiesto non esista già. L'account di servizio potrebbe esistere perché lo stesso account di servizio viene utilizzato per tutti i canali nella risorsa sottostante. Le risorse possono essere un progetto Google Cloud, un'organizzazione, una cartella o un account di fatturazione.

L'identità autore di un sink è l'identificatore dell'account di servizio associato al sink. Tutti i canali di destinazione hanno un'identità di autore, ad eccezione di quelli che scrivono in un bucket di log nello stesso progetto Google Cloud in cui ha origine la voce di log. Per quest'ultima configurazione, non è richiesto un account di servizio, pertanto il campo identità autore del sink è indicato come None nella console. L'API e i comandi Google Cloud CLI non riportano l'identità dell'autore.

Le seguenti istruzioni si applicano a progetti, cartelle, organizzazioni e account di fatturazione:

Console

  1. Assicurati di disporre dell'accesso Proprietario al progetto Google Cloud che contiene la destinazione. Se non disponi dell'accesso Proprietario alla destinazione dell'eseguitore, chiedi a un proprietario del progetto di aggiungere l'identità dell'autore come principale.

  2. Per ottenere l'identità dello scrittore dell'area di destinazione, ovvero un indirizzo email, dal nuovo flusso:

    1. Nella console Google Cloud, vai alla pagina Log Router:

      Vai a Router dei log

      Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo Logging.

    2. Nella barra degli strumenti, seleziona il progetto che contiene l'emissario.
    3. Seleziona Menu e poi Visualizza dettagli della canalizzazione. L'identità dell'autore viene visualizzata nel riquadro Dettagli destinazione.

  3. Se il valore del campo writerIdentity contiene un indirizzo email, vai al passaggio successivo. Se il valore è None, non è necessario configurare le autorizzazioni di destinazione per l'emissario.

  4. Copia l'identità dello scrittore della destinazione negli appunti.

  5. Se la destinazione è un servizio in un progetto diverso o se si tratta di un altro progetto, seleziona il progetto di destinazione nella barra degli strumenti.

  6. Aggiungi l'account di servizio come entità IAM nel progetto di destinazione:

    1. Nella console Google Cloud, vai alla pagina IAM:

      Vai a IAM

      Se utilizzi la barra di ricerca per trovare questa pagina, seleziona il risultato con il sottotitolo IAM e amministrazione.

    2. Seleziona il progetto di destinazione.

    3. Fai clic su Concedi accesso.

    4. Concedi all'account di servizio il ruolo IAM richiesto:

      • Per le destinazioni Cloud Storage, aggiungi l'identità dello scrittore del canale come entità utilizzando IAM, quindi concedi il ruolo Creatore oggetti Storage (roles/storage.objectCreator).
      • Per le destinazioni BigQuery, aggiungi l'identità autore del canale come principale utilizzando IAM e poi concedi il ruolo Editor dati BigQuery (roles/bigquery.dataEditor).
      • Per le destinazioni Pub/Sub, tra cui Splunk, aggiungi l'identità dello scrittore del sink come entità utilizzando IAM e poi concedile il ruolo Publisher Pub/Sub (roles/pubsub.publisher).
      • Per le destinazioni dei bucket di log in diversi progetti Google Cloud, aggiungi l'identità dello scrittore della destinazione come entità utilizzando IAM e poi concedile il ruolo Scrittore del bucket di log (roles/logging.bucketWriter).
      • Per le destinazioni dei progetti Google Cloud, aggiungi l'identità dello scrittore del canale come entità utilizzando IAM e poi concedile il ruolo Scrittore di log (roles/logging.logWriter). Nello specifico, un'entità deve disporre dell'autorizzazione logging.logEntries.route.

gcloud

  1. Assicurati di disporre dell'accesso Proprietario al progetto Google Cloud che contiene la destinazione. Se non disponi dell'accesso Proprietario alla destinazione dell'eseguitore, chiedi a un proprietario del progetto di aggiungere l'identità dell'autore come principale.

  2. Recupera l'account di servizio dal campo writerIdentity nel tuo sink:

    gcloud logging sinks describe SINK_NAME

  3. Individua il sink di cui vuoi modificare le autorizzazioni e, se i dettagli del sink contengono una riga con writerIdentity, vai al passaggio successivo. Se i dettagli non includono un campo writerIdentity, non è necessario configurare le autorizzazioni di destinazione per il sink.

    L'identità dell'autore per l'account di servizio è simile alla seguente:

    serviceAccount:service-123456789012@gcp-sa-logging.iam.gserviceaccount.com

  4. Aggiungi l'account di servizio come entità IAM nel progetto di destinazione:

    Prima di utilizzare il seguente comando, effettua le seguenti sostituzioni:

    • PROJECT_ID: l'identificatore del progetto.
    • PRINCIPAL: un identificatore per l'entità a cui vuoi concedere il ruolo. Gli identificatori principali hanno in genere la seguente forma: PRINCIPAL-TYPE:ID. Ad esempio: user:my-user@example.com. Per un elenco completo dei formati che PRINCIPAL può avere, consulta Identificatori principali.

    • ROLE: un ruolo IAM.

      • Per le destinazioni Cloud Storage, aggiungi l'identità dello scrittore del canale come entità utilizzando IAM, quindi concedi il ruolo Creatore oggetti Storage (roles/storage.objectCreator).
      • Per le destinazioni BigQuery, aggiungi l'identità dello scrittore del canale come principale utilizzando IAM e poi concedi il ruolo Editor dati BigQuery (roles/bigquery.dataEditor).
      • Per le destinazioni Pub/Sub, tra cui Splunk, aggiungi l'identità dello scrittore del sink come entità utilizzando IAM e poi concedile il ruolo Publisher Pub/Sub (roles/pubsub.publisher).
      • Per le destinazioni dei bucket di log in diversi progetti Google Cloud, aggiungi l'identità dello scrittore della destinazione come entità utilizzando IAM e poi concedile il ruolo Scrittore del bucket di log (roles/logging.bucketWriter).
      • Per le destinazioni dei progetti Google Cloud, aggiungi l'identità dello scrittore del canale come entità utilizzando IAM e poi concedile il ruolo Scrittore di log (roles/logging.logWriter). Nello specifico, un'entità deve disporre dell'autorizzazione logging.logEntries.route.

    Esegui il comando gcloud projects add-iam-policy-binding:

    gcloud projects add-iam-policy-binding PROJECT_ID --member=PRINCIPAL --role=ROLE

REST

Ti consigliamo di utilizzare la console Google Cloud o l'Google Cloud CLI per concedere un ruolo all'account di servizio.

Limitazioni delle destinazioni

Questa sezione descrive le limitazioni specifiche per la destinazione:

  • Se indirizzi le voci di log a un bucket di log in un altro progetto Google Cloud, Error Reporting non le analizza. Per ulteriori informazioni, consulta la Panoramica di Error Reporting.
  • Se inoltri le voci di log a BigQuery, il set di dati BigQuery deve essere abilitato alla scrittura. Non puoi instradare le voci di log ai set di dati collegati, che sono di sola lettura.

  • Quando inoltri le voci di log a diversi progetti Google Cloud, si applicano le seguenti limitazioni:

    • Esiste un limite di un hop.

      Ad esempio, se indirizzi le voci di log dal progetto A al progetto B, non puoi indirizzarle dal progetto B a un altro progetto.

    • I log di controllo non vengono instradati al bucket di log _Required nel progetto di destinazione.

      Ad esempio, se indirizzi le voci di log dal progetto A al progetto B, il bucket dei log _Required nel progetto A contiene i log di controllo per il progetto A. I log di controllo per il progetto A non vengono indirizzati al progetto B. Per instradare queste voci di log, crea un sink la cui destinazione è un bucket di log.

    • Quando il progetto di destinazione si trova in una cartella o un'organizzazione diversa, i canali di destinazione aggregati in quella cartella o organizzazione non indirizzano la voce di log.

      Ad esempio, supponiamo che il progetto A si trovi nella cartella X. Quando una voce di log proviene dal progetto A, viene elaborata dagli scollamenti aggregati nella cartella X e dagli scollamenti nel progetto A. Ora supponiamo che il progetto A contenga un sink che instrada le relative voci di log al progetto B, che si trova nella cartella Y. Le voci di log del progetto A passano attraverso gli sink nel progetto B, ma non passano attraverso gli sink aggregati nella cartella Y.

  • Per utilizzare Esplora log per visualizzare le voci di log inviate a un progetto utilizzando un'area di destinazione aggregata, imposta il campo Perfeziona ambito sull'ambito di archiviazione e poi seleziona una visualizzazione di log che fornisca l'accesso a queste voci.

Esempi di codice

Per utilizzare il codice della libreria client per configurare i sink nelle lingue scelte, consulta Librerie client di logging: sink di log.

Esempi di filtro

Di seguito sono riportati alcuni esempi di filtri particolarmente utili per la creazione di canali. Per ulteriori esempi che potrebbero essere utili durante la creazione dei filtri di inclusione e di esclusione, consulta Query di esempio.

Ripristina il filtro di destinazione _Default

Se hai modificato il filtro per l'emissario _Default, ti consigliamo di ripristinarne la configurazione originale. Una volta creato, l'emissario _Default viene configurato con il seguente filtro di inclusione e un filtro di esclusione vuoto:

  NOT log_id("cloudaudit.googleapis.com/activity") AND NOT \
  log_id("externalaudit.googleapis.com/activity") AND NOT \
  log_id("cloudaudit.googleapis.com/system_event") AND NOT \
  log_id("externalaudit.googleapis.com/system_event") AND NOT \
  log_id("cloudaudit.googleapis.com/access_transparency") AND NOT \
  log_id("externalaudit.googleapis.com/access_transparency")

Escludere i log dei container e dei pod di Google Kubernetes Engine

Per escludere le voci dei log dei container e dei pod di Google Kubernetes Engine per il sistema GKE namespaces, utilizza il seguente filtro:

resource.type = ("k8s_container" OR "k8s_pod")
resource.labels.namespace_name = (
"cnrm-system" OR
"config-management-system" OR
"gatekeeper-system" OR
"gke-connect" OR
"gke-system" OR
"istio-system" OR
"knative-serving" OR
"monitoring-system" OR
"kube-system")

Per escludere le voci di log dei nodi di Google Kubernetes Engine per il sistema GKE logNames, utilizza il seguente filtro:

resource.type = "k8s_node"
logName:( "logs/container-runtime" OR
"logs/docker" OR
"logs/kube-container-runtime-monitor" OR
"logs/kube-logrotate" OR
"logs/kube-node-configuration" OR
"logs/kube-node-installation" OR
"logs/kubelet" OR
"logs/kubelet-monitor" OR
"logs/node-journal" OR
"logs/node-problem-detector")

Per visualizzare il volume di voci di log di nodi, pod e container di Google Kubernetes Engine memorizzate nei bucket di log, utilizza Metrics Explorer:

Escludi i log di Dataflow non necessari per la supportabilità

Per escludere le voci di log di Dataflow non necessarie per la supportabilità, utilizza il seguente filtro:

resource.type="dataflow_step"
labels."dataflow.googleapis.com/log_type"!="system" AND labels."dataflow.googleapis.com/log_type"!="supportability"

Per visualizzare il volume dei log di Dataflow archiviati nei bucket di log, utilizza Metrics Explorer.

Supportabilità

Sebbene Cloud Logging ti consenta di escludere le voci di log e di impedirne la memorizzazione in un bucket di log, potresti prendere in considerazione la possibilità di conservare le voci di log utili per la supportabilità. L'utilizzo di queste voci di log può aiutarti a risolvere e identificare i problemi con le tue applicazioni.

Ad esempio, le voci dei log di sistema GKE sono utili per risolvere i problemi delle applicazioni e dei cluster GKE perché vengono generate per gli eventi che si verificano nel cluster. Queste voci di log possono aiutarti a determinare se il codice dell'applicazione o il cluster GKE sottostante sta causando l'errore dell'applicazione. I log di sistema GKE includono anche il logging di controllo Kubernetes generato dal componente del server API Kubernetes, che include le modifiche apportate utilizzando il comando kubectl e gli eventi Kubernetes.

Per Dataflow, ti consigliamo di scrivere almeno i log di sistema (labels."dataflow.googleapis.com/log_type"="system") e di supportabilità (labels."dataflow.googleapis.com/log_type"="supportability") nei bucket di log. Questi log sono essenziali per consentire agli sviluppatori di osservare e risolvere i problemi delle pipeline Dataflow. Inoltre, gli utenti potrebbero non essere in grado di utilizzare la pagina Dataflow Dettagli job per visualizzare i log dei job.

Passaggi successivi