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

Questo documento descrive come creare sink aggregati. I sink aggregati ti consentono di combinare e instradare i log generati dalle Google Cloud risorse nella tua organizzazione o cartella in una posizione centralizzata.

Prima di iniziare

Prima di creare un sink, assicurati di quanto segue:

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

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

  • Devi disporre di uno dei seguenti ruoli IAM per l'Google Cloud organizzazione o la cartella da cui stai instradando le voci di log.

    • Proprietario (roles/owner)
    • Amministratore di Log (roles/logging.admin)
    • Logs Configuration Writer (roles/logging.configWriter)

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

  • La destinazione dell'emissario aggregato esista o tu abbia la possibilità di crearla.

    Quando la destinazione è un Google Cloud progetto, 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 dell'API REST in questa pagina in un ambiente di sviluppo locale, utilizza le credenziali fornite all'interfaccia alla 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 ulteriori informazioni, consulta Eseguire l'autenticazione per l'utilizzo di REST nella Google Cloud documentazione sull'autenticazione.

Creare un sink aggregato

Per configurare un sink aggregato, crealo e poi concedigli le autorizzazioni per scrivere nella destinazione. Questa sezione descrive come creare un sink aggregato. Per informazioni su come concedere le 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 canale aggregato per la cartella o l'organizzazione:

  1. Nella Google Cloud console, 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 una cartella o un'organizzazione esistente.

  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 menu Seleziona servizio sink, seleziona il tipo di destinazione, quindi completa la finestra di dialogo per specificarla. Puoi selezionare una destinazione esistente o crearne una.

    • Per un sink di intercettazione, seleziona ProgettoGoogle Cloud , quindi inserisci il nome completo del progetto Google Cloud di destinazione:

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

    • Per un collettore non di intercettazione, 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 abilitato alla scrittura. Il set di dati può essere una tabella partizionata o suddivisa in partizioni 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'area di destinazione di intercettazione, seleziona Intercetta i log importati da questa organizzazione e da tutte le risorse secondarie.

    • Per un sink che non intercetta, seleziona Includi i log importati da questa risorsa e da tutte le risorse figlio.

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

    Ad esempio, potresti creare un filtro per inoltrare tutti i log di controllo dell'accesso ai dati a un unico bucket di log. 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 i canali 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 filtro corrispondente 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 l'inoltro delle voci di log di un progetto specifico 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 destinazione. 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 ulteriori informazioni, consulta Impostare le autorizzazioni di destinazione.

gcloud

Per creare un'area di destinazione aggregata, utilizza il comando logging sinks create:

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

    Prima di utilizzare il seguente 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. 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, consulta Creare filtri per i canali 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'area di destinazione di intercettazione, includi l'opzione --intercept-children.

    Ad esempio, se stai creando un sink aggregato a livello di cartella e la 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 del sink l'autorizzazione di scrittura nella destinazione del sink. Per ulteriori informazioni, consulta Impostare le autorizzazioni di destinazione.

REST

Per creare un'area di destinazione aggregata, utilizza il metodo organizations.sinks.create o folders.sinks.create dell'API Logging. Prepara gli argomenti del metodo come segue:

  1. Imposta il campo parent in modo che corrisponda all' Google Cloud organizzazione o alla cartella in cui creare il sink. Il tag principale 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'area di destinazione 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, consulta Creare filtri per i canali aggregati.

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

  4. Imposta i restanti campi LogSink come faresti per qualsiasi destinazione. Per ulteriori informazioni, consulta Indirizzare i log alle destinazioni supportate.

  5. Chiama organizations.sinks.create o folders.sinks.create per creare il canale.

  6. Concedi all'account di servizio del sink l'autorizzazione di scrittura nella destinazione del sink. Per ulteriori informazioni, consulta Impostare le autorizzazioni di destinazione.

L'applicazione di eventuali 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 accumulo aggregato. Per altri esempi, consulta Query di esempio con Esplora log.

Alcuni esempi utilizzano la seguente notazione:

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

La lunghezza di un filtro è limitata a 20.000 caratteri.

Per ulteriori dettagli sulla sintassi di filtro, consulta Lingua delle query di logging.

Seleziona la sorgente log

Per instradare le voci di log da tutte le risorse secondarie, non specificare un progetto, una cartella o un'organizzazione nei filtri di inclusione ed esclusione della destinazione. Ad esempio, supponiamo di configurare un'area di destinazione aggregata per un'organizzazione con il seguente filtro:

resource.type="gce_instance"

Con il filtro precedente, le voci di log con un tipo di risorsa di istanza Compute Engine scritte in qualsiasi organizzazione secondaria vengono inoltrate dall'emissario aggregato alla destinazione.

Tuttavia, potrebbero verificarsi situazioni in cui vuoi utilizzare un'area di destinazione aggregata per instradare le voci di log solo da risorse secondarie specifiche. Ad esempio, per motivi di conformità, potresti voler archiviare gli audit log di cartelle o progetti specifici nel relativo bucket Cloud Storage. In questi casi, configura il filtro di inclusione in modo da specificare ogni risorsa secondaria di cui vuoi indirizzare 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, nonché 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 instradare 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 in Google Cloud progetti che sono figli di my-folder, non vengono instradate alla destinazione.

Seleziona la risorsa monitorata

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

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 esempio di voci di log

Per instradare un campione casuale di voci di log, aggiungi la funzione interna sample. Ad esempio, per instradare solo il 10% delle voci di log corrispondenti al tuo filtro corrente, utilizza questa aggiunta:

sample(insertId, 0.10) AND ...

Per ulteriori informazioni, consulta la funzione sample.

Per ulteriori informazioni sui filtri di Cloud Logging, consulta Linguaggio delle 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 dell'eseguiamo. Per l'elenco completo dei ruoli e delle autorizzazioni di Logging, consulta Controllo dell'accesso.

Quando crei o aggiorni un'area di destinazione che inoltra le voci di log a una destinazione diversa da un bucket di log nel progetto corrente, è necessario un account di servizio per l'area di destinazione. Logging crea e gestisce automaticamente il account di servizio per te:

  • A partire dal 22 maggio 2023, quando crei un canale di destinazione e non esiste un account di servizio per la risorsa sottostante, Logging crea l'account di servizio. Il logging utilizza lo stesso account di servizio per tutti gli 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 account di servizio per ogni destinazione. A partire dal 22 maggio 2023, Logging utilizza un account di servizio condiviso per tutti gli sink nella risorsa di base.

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, a meno che non scrivano in un bucket di log nel progetto Google Cloud corrente. L'indirizzo email nell'identità autore identifica l'entità che deve avere accesso per scrivere dati nella destinazione.

Per instradare le voci di log a una risorsa protetta da un perimetro di servizio, devi aggiungere l'account di servizio per quell'incanalamento a un livello di accesso e poi assegnarlo al perimetro di servizio di destinazione. Questo non è necessario per i sink non aggregati. Per maggiori dettagli, consulta Controlli di servizio VPC: Cloud Logging.

Per impostare le autorizzazioni per l'inoltro del sink alla destinazione, svolgi i seguenti passaggi:

Console

  1. Per informazioni sull'account di servizio per il tuo sink, esegui i seguenti passaggi:

    1. Nella Google Cloud console, 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 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.

    4. Copia l'identità dello scrittore della destinazione negli appunti. Di seguito è riportata un'identità autore:

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

  2. Concedi all'entità specificata dall'identità autore del sink l'autorizzazione per scrivere i dati dei log nella destinazione:

    1. Nella Google Cloud console, 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 Google Cloud console, seleziona il progetto che memorizza la destinazione dell'emissario aggregato. Se la destinazione è un progetto, selezionalo.

    3. Fai clic su Concedi l'accesso.

    4. Inserisci l'entità specificata dall'identità dello scrittore della destinazione 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 dell'eseguitore, chiedi a un proprietario del progetto di aggiungere l'identità dell'autore come principale.

  2. Per ottenere informazioni sull'account di servizio per la destinazione, chiama il metodo gcloud logging sinks describe.

    Prima di utilizzare il seguente comando, effettua 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 della destinazione contengono un campo denominato writerIdentity, vai al passaggio successivo. Se i dettagli non includono un campo writerIdentity, non è necessario configurare le autorizzazioni di destinazione per l'emissario.

  4. Copia l'identità dello scrittore della destinazione negli appunti. Di seguito è riportata un'identità autore:

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

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

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

    • PROJECT_ID: l'identificatore del progetto. Seleziona il progetto in cui è archiviata la destinazione del canale aggregato. Quando la destinazione è un progetto, selezionalo.
    • 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. Concedi all'identità autore 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 Google Cloud console o Google Cloud CLI per concedere un ruolo all'account di servizio.

Passaggi successivi