Raccogliere e instradare i log a livello di organizzazione e cartella alle destinazioni supportate

Questo documento descrive come creare sink aggregati. I sink aggregati consentono di combinare ed eseguire il routing dei log generati dalle Google Cloud risorse della tua organizzazione o cartella in una posizione centralizzata.

Prima di iniziare

Prima di creare un sink, assicurati di:

  • Hai familiarità con il comportamento dei sink aggregati. Per scoprire di più su questi sink, consulta Panoramica dei sink aggregati.

  • Hai una Google Cloud cartella o un'organizzazione con voci di log che puoi visualizzare in Esplora log.

  • Hai uno dei seguenti ruoli IAM per l'organizzazione o la cartellaGoogle Cloud da cui stai instradando le voci di log.

    • Proprietario (roles/owner)
    • Logging Admin (roles/logging.admin)
    • Writer configurazione log (roles/logging.configWriter)

    Le autorizzazioni contenute in questi ruoli consentono di creare, eliminare o modificare i sink. Per informazioni sull'impostazione dei ruoli IAM, consulta la guida al controllo dell'accesso di Logging.

  • La destinazione del sink aggregato esiste o hai la possibilità di crearla.

    Quando la destinazione è un progetto Google Cloud , il progetto può trovarsi in qualsiasi organizzazione. Tutte le altre destinazioni possono trovarsi in qualsiasi progetto di qualsiasi organizzazione.

  • 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 di API REST in questa pagina in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

        After installing the Google Cloud CLI, initialize it by running the following command: 

        gcloud init

        If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

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

Creare un sink aggregato

Per configurare un sink aggregato, crea il sink e poi concedi al sink le autorizzazioni per scrivere nella destinazione. Questa sezione descrive come creare un sink aggregato. Per informazioni sulla concessione delle autorizzazioni al sink, consulta la sezione di questa pagina intitolata Impostare le autorizzazioni di destinazione.

Puoi creare fino a 200 sink per cartella o organizzazione.

Console

Per creare un sink aggregato per la cartella o l'organizzazione:

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

    Vai a Router dei log

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

  2. Seleziona un'organizzazione o una cartella esistente.

  3. Seleziona Crea sink.

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

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

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

  5. Nel menu Seleziona servizio sink, seleziona il tipo di destinazione, quindi completa la finestra di dialogo per specificare la destinazione. Puoi selezionare una destinazione esistente o crearla.

    • Per un sink di intercettazione, seleziona progettoGoogle Cloud e poi inserisci il nome completo del progetto Google Cloud di destinazione:

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

    • Per un sink non intercettante, seleziona la destinazione, quindi inserisci il nome completo della destinazione. Sono supportate le seguenti destinazioni:

      • Google Cloud project

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • Bucket Cloud Logging

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

      • Set di dati BigQuery

        Devi inserire il nome completo di un set di dati con accesso in scrittura. Il set di dati può essere una tabella partizionata o suddivisa per data. Non inserire il nome di un set di dati collegato. I set di dati collegati sono di sola lettura.

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

      • Bucket Cloud Storage

        storage.googleapis.com/BUCKET_NAME

      • Argomento Pub/Sub

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

      • Splunk

        Inserisci l'argomento Pub/Sub per il servizio Splunk.

  6. Nel riquadro Scegli i log da includere nel sink, seleziona le risorse da includere nel sink.

    • Per un sink di intercettazione, seleziona Intercetta i log importati da questa organizzazione e da tutte le risorse secondarie.

    • Per un sink non intercettante, seleziona Includi i log importati da questa risorsa e da tutte le risorse secondarie.

  7. Nel campo Crea filtro di inclusione, inserisci un'espressione di filtro che corrisponda alle voci di log che vuoi includere. Se non imposti un filtro, tutte le voci di log della risorsa selezionata vengono indirizzate alla destinazione.

    Ad esempio, potresti voler creare un filtro per indirizzare tutti i log di controllo dell'accesso ai dati a un singolo bucket Logging. Questo filtro ha il seguente aspetto:

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

    Per esempi di filtri, consulta la sezione Creare filtri per sink aggregati di questa pagina.

    Tieni presente che la lunghezza di un filtro non può superare i 20.000 caratteri.

  8. (Facoltativo) Per verificare di aver inserito il filtro corretto, seleziona Anteprima dei log. Si apre Esplora log in una nuova scheda con il filtro precompilato.

  9. (Facoltativo) Nel riquadro Scegli i log da escludere dal sink, procedi nel seguente modo:

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

    2. Nel campo Crea un filtro di esclusione, inserisci un'espressione di 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.

      Ad esempio, per escludere le voci di log di un progetto specifico dall'instradamento alla destinazione, aggiungi il seguente filtro di esclusione:

      logName:projects/PROJECT_ID

      Per escludere le voci di log da più progetti, utilizza l'operatore OR logico per unire le clausole logName.

    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.

  10. Seleziona Crea sink.

  11. Per completare la configurazione del sink aggregato, concedi all'account di servizio del sink l'autorizzazione per scrivere le voci di log nella destinazione del sink. Per maggiori informazioni, vedi Impostare le autorizzazioni della destinazione.

gcloud

Per creare un sink aggregato, utilizza il comando logging sinks create:

  1. Per creare un lavello, chiama il comando gcloud logging sinks create e assicurati di includere l'opzione --include-children.

    Prima di utilizzare il comando seguente, esegui 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 indirizzare le voci di log. Per informazioni sul formato di queste destinazioni, consulta Formati dei percorsi di destinazione.
    • INCLUSION_FILTER: il filtro di inclusione per un sink. Per esempi di filtri, vedi Creare filtri per sink aggregati.
    • FOLDER_ID: l'ID della cartella. Se vuoi creare un sink a livello di organizzazione, sostituisci --folder=FOLDER_ID con -- organization=ORGANIZATION_ID.

    Esegui il comando gcloud logging sinks create:

    gcloud logging sinks create SINK_NAME \
  SINK_DESTINATION  --include-children \
  --folder=FOLDER_ID --log-filter="INCLUSION_FILTER"

    Puoi anche fornire le seguenti opzioni:

    • Per creare un sink di intercettazione, includi l'opzione --intercept-children.

    Ad esempio, se stai creando un sink aggregato a livello di cartella e la cui destinazione è un argomento Pub/Sub, il comando potrebbe essere simile al seguente:

    gcloud logging sinks create SINK_NAME \
  pubsub.googleapis.com/projects/PROJECT_ID/topics/TOPIC_ID --include-children \
  --folder=FOLDER_ID --log-filter="logName:activity"

  2. Concedi all'account di servizio per il sink l'autorizzazione di scrittura nella destinazione del sink. Per maggiori informazioni, vedi Impostare le autorizzazioni della destinazione.

REST

Per creare un sink aggregato, utilizza il metodo API Logging organizations.sinks.create o folders.sinks.create. Prepara gli argomenti per il metodo nel seguente modo:

  1. Imposta il campo parent in modo che corrisponda all'organizzazione o alla cartella in cui creare il sink. Google Cloud Il genitore deve essere uno dei seguenti:

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID

  2. Nell'oggetto LogSink nel corpo della richiesta del metodo, esegui una delle seguenti operazioni:

    • Imposta includeChildren su True.

    • Per creare un sink di intercettazione, imposta anche il campo interceptChildren su True.

  3. Imposta il campo filter in modo che corrisponda alle voci di log che vuoi includere.

    Per esempi di filtri, vedi Creare filtri per sink aggregati.

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

  4. Imposta i campi LogSink rimanenti come faresti per qualsiasi sink. Per ulteriori informazioni, consulta Inviare i log alle destinazioni supportate.

  5. Chiama il numero organizations.sinks.create o folders.sinks.create per creare il sink.

  6. Concedi all'account di servizio per il sink l'autorizzazione di scrittura nella destinazione del sink. Per maggiori informazioni, vedi Impostare le autorizzazioni della destinazione.

L'applicazione delle modifiche apportate a un sink potrebbe richiedere alcuni minuti.

Filtri per i sink aggregati

Questa sezione fornisce esempi di filtri che potresti utilizzare in un sink aggregato. Per altri esempi, vedi Query di esempio con Esplora log.

Alcuni esempi utilizzano la seguente notazione:

  • : è l'operatore di sottostringa. Non sostituire l'operatore =.
  • ... rappresenta eventuali confronti di filtri aggiuntivi.
  • Le variabili sono indicate da testo colorato. Sostituiscili con valori validi.

La lunghezza di un filtro è limitata a 20.000 caratteri.

Per maggiori dettagli sulla sintassi di filtro, consulta Linguaggio delle query di Logging.

Seleziona la sorgente log

Per eseguire il routing delle voci di log da tutte le risorse secondarie, non specificare un progetto, una cartella o un'organizzazione nei filtri di inclusione ed esclusione del sink. Ad esempio, supponiamo di configurare un sink aggregato per un'organizzazione con il seguente filtro:

resource.type="gce_instance"

Con il filtro precedente, le voci di log con un tipo di risorsa Istanze Compute Engine scritte in qualsiasi elemento secondario di questa organizzazione vengono indirizzate dal sink aggregato alla destinazione.

Tuttavia, potrebbero verificarsi situazioni in cui vuoi utilizzare un sink aggregato per indirizzare le voci di log solo da risorse secondarie specifiche. Ad esempio, per motivi di conformità, potresti voler archiviare i log di controllo di cartelle o progetti specifici nel proprio bucket Cloud Storage. In queste situazioni, configura il filtro di inclusione in modo da specificare ogni risorsa secondaria di cui vuoi instradare le voci di log. Se vuoi instradare le voci di log da una cartella e da tutti i progetti al suo interno, il filtro deve elencare la cartella e ciascuno dei progetti contenuti al suo interno e unire le istruzioni con una clausola OR.

I seguenti filtri limitano le voci di log a progetti, cartelle o organizzazioni specifici Google Cloud :

logName:"projects/PROJECT_ID/logs/" AND ... 
logName:("projects/PROJECT_A_ID/logs/" OR "projects/PROJECT_B_ID/logs/") AND ... 
logName:"folders/FOLDER_ID/logs/" AND ... 
logName:"organizations/ORGANIZATION_ID/logs/" AND ...

Ad esempio, per indirizzare solo le voci di log scritte nelle istanze Compute Engine che sono state scritte nella cartella my-folder, utilizza il seguente filtro:

logName:"folders/my-folder/logs/" AND resource.type="gce_instance"

Con il filtro precedente, le voci di log scritte in qualsiasi risorsa diversa da my-folder, incluse le voci di log scritte nei progetti Google Cloud figli di my-folder, non vengono indirizzate alla destinazione.

Seleziona la risorsa monitorata

Per indirizzare le voci di log solo da una risorsa monitorata specifica in un progettoGoogle Cloud , utilizza più confronti per specificare la risorsa esattamente:

logName:"projects/PROJECT_ID/logs" AND
resource.type=RESOURCE_TYPE AND
resource.labels.instance_id=INSTANCE_ID

Per un elenco dei tipi di risorse, consulta Tipi di risorse monitorate.

Seleziona un campione di voci di log

Per instradare un campione casuale di voci di log, aggiungi la funzione integrata sample. Ad esempio, per indirizzare solo il 10% delle voci di log corrispondenti al filtro attuale, utilizza questo componente aggiuntivo:

sample(insertId, 0.10) AND ...

Per saperne di più, consulta la funzione sample.

Per ulteriori informazioni sui filtri di Cloud Logging, consulta Linguaggio di query di Logging.

Impostare le autorizzazioni di destinazione

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

Quando crei o aggiorni un sink che esegue il routing delle voci di log a qualsiasi destinazione diversa da un bucket di log nel progetto corrente, è necessario unaccount di serviziot per quel sink. Logging crea e gestisce automaticamente il account di servizio per te:

  • A partire dal 22 maggio 2023, quando crei un sink e non esiste un service account per la risorsa sottostante, Logging crea il account di servizio. Logging utilizza lo stesso account di servizio per tutti i sink nella risorsa sottostante. Le risorse possono essere un Google Cloud progetto, un'organizzazione, una cartella o un account di fatturazione.
  • Prima del 22 maggio 2023, Logging creava un service account per ogni sink. A partire dal 22 maggio 2023, Logging utilizza un account di servizio condiviso per tutti i sink nella risorsa sottostante.

L'identità writer di un sink è l'identificatore dell'account di servizio associato a quel sink. Tutti i sink hanno un'identità writer, a meno che non scrivano in un bucket log nel progetto Google Cloud corrente. L'indirizzo email nell'identità del writer identifica l'entità che deve avere l'accesso per scrivere dati nella destinazione.

Per indirizzare le voci di log a una risorsa protetta da un perimetro di servizio, devi aggiungere il account di servizio per questo sink a un livello di accesso e poi assegnarlo al perimetro di servizio di destinazione. Non è necessario per i sink non aggregati. Per maggiori dettagli, vedi Controlli di servizio VPC: Cloud Logging.

Per impostare le autorizzazioni per la sink in modo che venga indirizzata alla destinazione, procedi nel seguente modo:

Console

  1. Per ottenere informazioni sull'account di servizio per il tuo sink, svolgi le seguenti operazioni:

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

      Vai a Router dei log

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

    2. Seleziona Menu e poi seleziona Visualizza dettagli del lavello. L'identità dell'autore viene visualizzata nel riquadro Dettagli sink.

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

    4. Copia l'identità del writer del sink negli appunti. Di seguito è riportato un esempio di identità writer:

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

  2. Concedi all'entità specificata dall'identità writer del sink l'autorizzazione a scrivere dati di log nella 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. Nella barra degli strumenti della console Google Cloud , seleziona il progetto in cui è archiviata la destinazione del sink aggregato. Se la destinazione è un progetto, selezionalo.

    3. Fai clic su Concedi l'accesso.

    4. Inserisci l'entità specificata dall'identità del writer del sink e poi concedi un ruolo IAM:

gcloud

  1. Assicurati di disporre dell'accesso Proprietario al progettoGoogle Cloud che contiene la destinazione. Se non disponi dell'accesso Proprietario alla destinazione del sink, chiedi a un proprietario del progetto di aggiungere l'identità del writer come entità.

  2. Per ottenere informazioni sul account di servizio per il sink, chiama il metodo gcloud logging sinks describe.

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

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

    Esegui il comando gcloud logging sinks describe:

    gcloud logging sinks describe SINK_NAME

  3. Se i dettagli del sink contengono un campo etichettato writerIdentity, vai al passaggio successivo. Quando i dettagli non includono un campo writerIdentity, non è necessario configurare le autorizzazioni di destinazione per il sink.

  4. Copia l'identità del writer del sink negli appunti. Di seguito è riportato un esempio di identità writer:

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

  5. Concedi all'identità writer del sink l'autorizzazione a scrivere i dati di log nella destinazione chiamando il comando gcloud projects add-iam-policy-binding.

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

    • PROJECT_ID: l'identificatore del progetto. Seleziona il progetto che archivia la destinazione del sink aggregato. Se la destinazione è un progetto, selezionalo.
    • PRINCIPAL: un identificatore per l'entità a cui vuoi concedere il ruolo. Gli identificatori dell'entità in genere hanno il seguente formato: 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. Concedi all'identità writer del sink un ruolo IAM in base alla destinazione del sink di log:

    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 Google Cloud CLI per concedere un ruolo al account di servizio.

Passaggi successivi