Collega e instrada i log a livello di organizzazione alle destinazioni supportate

Questo documento descrive come creare sink aggregati. Per informazioni sulla gestione dei sink esistenti, consulta Routing dei log alle destinazioni supportate: gestione dei sink.

Panoramica

I sink aggregati combinano e instradano le voci di log delle risorse Google Cloud contenute in un'organizzazione o una cartella. Ad esempio, puoi aggregare e indirizzare voci di log di controllo da tutte le cartelle contenute da un'organizzazione a un bucket Cloud Storage.

Senza la funzionalità aggregata dei sink, i sink sono limitati al routing delle voci di log dalla risorsa esatta in cui è stato creato il sink: un progetto, un'organizzazione, una cartella o un account di fatturazione Google Cloud.

Puoi creare sink aggregati per cartelle e organizzazioni Google Cloud. Poiché né i progetti Google Cloud né gli account di fatturazione contengono risorse figlio, non puoi creare sink aggregati.

Destinazioni supportate

Puoi utilizzare i sink aggregati per instradare i log all'interno o tra le stesse organizzazioni e cartelle verso le seguenti destinazioni:

  • Bucket di log di Cloud Logging: fornisce spazio di archiviazione in Cloud Logging. Un bucket di log può archiviare i log importati da più progetti Google Cloud. Puoi combinare i dati di Cloud Logging con altri dati eseguendo l'upgrade di un bucket di log per utilizzare l'analisi dei log e quindi creando un set di dati BigQuery collegato. Per informazioni sulla visualizzazione dei log archiviati nei bucket di log, consulta Panoramica e visualizza la panoramica dei log e Visualizza i log con routing ai bucket Cloud Logging.
  • Progetti Google Cloud: instrada le voci di log a un progetto Google Cloud diverso. Quando instrada i log a un altro progetto Google Cloud, il router dei log del progetto di destinazione riceve i log e li elabora. I sink nel progetto di destinazione determinano come vengono instradate le voci di log ricevute.
  • Argomenti Pub/Sub: fornisce supporto per le integrazioni di terze parti, come Splunk. Le voci di log vengono formattate in formato JSON e quindi indirizzate a un argomento Pub/Sub. Per informazioni sulla visualizzazione dei log con routing a Pub/Sub, consulta Visualizzare i log con routing a Pub/Sub.
  • Set di dati di BigQuery: fornisce l'archiviazione delle voci di log nei set di dati BigQuery. Puoi utilizzare le funzionalità di analisi dei big data nei log archiviati. Per combinare i dati Cloud Logging con altre origini dati, ti consigliamo di eseguire l'upgrade dei bucket di log per utilizzare Log Analytics e creare un set di dati BigQuery collegato. Per informazioni sulla visualizzazione dei log con routing a BigQuery, consulta Visualizzare i log con routing a BigQuery.
  • Bucket Cloud Storage: fornisce l'archiviazione dei dati di log in Cloud Storage. Le voci di log vengono archiviate come file JSON. Per informazioni sulla visualizzazione dei log con routing a Cloud Storage, consulta Visualizzare i log con routing a Cloud Storage.

Prima di iniziare

Prima di creare un sink, assicurati di quanto segue:

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

  • Hai uno dei seguenti ruoli IAM per l'organizzazione o la cartella Google Cloud da cui esegui il routing dei log.

    • Proprietario (roles/owner)
    • Amministratore Logging (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 degli accessi di Logging.

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

    La destinazione di routing deve essere creata prima del sink, tramite Google Cloud CLI, la console Google Cloud o le API Google Cloud. Puoi creare la destinazione in qualsiasi progetto Google Cloud in qualsiasi organizzazione, ma devi assicurarti che l'account di servizio dal sink disponga delle autorizzazioni per scrivere nella destinazione.

Crea un sink aggregato

Per utilizzare i sink aggregati, crea un sink in una cartella o un'organizzazione Google Cloud e imposta il parametro includeChildren del sink su True. Questo sink può quindi eseguire il routing delle voci di log dall'organizzazione o dalla cartella, oltre che ricorsivamente, da qualsiasi cartella, account di fatturazione o progetti Google Cloud contenuti. Imposta i filtri di inclusione ed esclusione del sink per specificare le voci di log che vuoi indirizzare alla tua destinazione.

Puoi creare fino a 200 sink per cartella o organizzazione.

Per creare un sink aggregato per la tua cartella o organizzazione, segui questi passaggi:

Console

  1. Nella console Google Cloud, seleziona Logging dal menu di navigazione, quindi fai clic su Log Router:
    Vai a Router Log

  2. Seleziona una cartella o un'organizzazione 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 rinominare il sink, ma puoi eliminarlo e crearne uno nuovo.

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

  5. Nel riquadro Destinazione sink, seleziona il servizio sink e la destinazione:

    • Seleziona servizio sink: seleziona il servizio in cui vuoi instradare i log.

    In base al servizio selezionato, puoi scegliere tra le seguenti destinazioni:

    • Bucket Cloud Logging: seleziona o crea un bucket di logging. Se crei un bucket di log, deve essere a livello di progetto. Non puoi creare un bucket di log a livello di cartella o organizzazione.
    • Tabella BigQuery: seleziona o crea il set di dati particolare per ricevere i log con routing. Puoi anche utilizzare le tabelle partizionate.
    • Bucket Cloud Storage: seleziona o crea il bucket Cloud Storage specifico per ricevere i log con routing.
    • Argomento Pub/Sub: seleziona o crea l'argomento specifico per ricevere i log con routing.

    • Splunk: seleziona l'argomento Pub/Sub per il servizio Splunk.

      Ad esempio, se la destinazione sink è un set di dati BigQuery, la destinazione sink sarebbe la seguente:

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

  6. Nel riquadro Scegli i log da includere nel sink, segui questi passaggi:

    1. Seleziona Includi log importati da questa risorsa e tutte le risorse figlio, per creare un sink aggregato.

    2. Nel campo Filtro di inclusione build, inserisci un'espressione di filtro che corrisponda alle voci di log che vuoi includere. Se non imposti un filtro, tutti i log della risorsa selezionata vengono instradati alla destinazione.

      Ad esempio, potresti voler creare un filtro per instradare tutti i log di accesso ai dati a un singolo bucket di logging. Questo filtro ha il seguente aspetto:

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

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

    3. Per verificare di aver inserito il filtro corretto, seleziona Visualizza l'anteprima dei log. Si apre Esplora log in una nuova scheda con il filtro precompilato.

  7. (Facoltativo) Nel riquadro Scegli i log da escludere dal sink, segui questi passaggi:

    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.

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

  8. Seleziona Crea sink.

API

Per creare un sink, utilizza organizations.sinks.create o folders.sinks.create nell'API Logging. Prepara gli argomenti nel metodo come descritto di seguito:

  1. Imposta il parametro parent come organizzazione o cartella Google Cloud in cui creare il sink. L'elemento principale deve essere uno dei seguenti:

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID

  2. Nell'oggetto LogSink nel corpo della richiesta del metodo, procedi nel seguente modo:

  3. Chiama organizations.sinks.create o folders.sinks.create per creare il sink.

  4. Recupera il nome dell'account di servizio dal campo writer_identity restituito dalla risposta dell'API.

  5. Autorizza l'account di servizio a scrivere nella destinazione del sink.

    Se non hai l'autorizzazione per apportare questa modifica alla destinazione sink, invia il nome dell'account di servizio a qualcuno che possa eseguire la modifica per te.

    Per ulteriori informazioni sulla concessione delle autorizzazioni per gli account di servizio per le risorse, consulta la sezione Impostare le autorizzazioni di destinazione.

gcloud

Per creare un sink, utilizza il comando logging sinks create.

  1. Fornisci il nome, la destinazione e il filtro del sink e l'ID della cartella o dell'organizzazione da cui vuoi eseguire il routing dei log:

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

    Ad esempio, se crei un sink aggregato a livello di cartella e la cui destinazione è un set di dati BigQuery, il tuo comando potrebbe avere il seguente aspetto:

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

    Note:

    • Per creare un sink a livello di organizzazione, sostituisci --folder=FOLDER_ID con --organization=ORGANIZATION_ID.

    • Affinché il sink includa tutte le risorse all'interno dell'organizzazione, deve essere impostato il flag --include-children, anche quando il flag --organization viene passato a create. Se impostato su false (valore predefinito), un sink instrada solo i log dalla risorsa host.

    • Per alcuni esempi di filtri utili, consulta Creare filtri per i sink aggregati.

  2. Recupera il nome dell'account di servizio utilizzato per creare il sink dall'output comando.

  3. Autorizza l'account di servizio a scrivere nella destinazione del sink.

    Se non hai l'autorizzazione per apportare questa modifica alla destinazione sink, invia il nome dell'account di servizio a qualcuno che possa eseguire la modifica per te.

    Per ulteriori informazioni sulla concessione delle autorizzazioni per gli account di servizio per le risorse, consulta la sezione Impostare le autorizzazioni di destinazione.

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

Crea filtri per i sink aggregati

Come ogni sink, il sink aggregato contiene un filtro che seleziona singole voci di log. Per esempi di filtri che potresti utilizzare per creare il tuo sink aggregato, consulta Query di esempio utilizzando Esplora log.

Di seguito sono riportati alcuni esempi di confronti di filtri utili quando si utilizza la funzionalità dei sink aggregati. 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.

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

Per maggiori dettagli sulla sintassi di filtro, consulta Logging del linguaggio di query.

Seleziona l'origine del log

Per eseguire il routing dei log da organizzazioni, cartelle o progetti Google Cloud specifici, utilizza uno dei seguenti confronti di esempio:

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 ...

Seleziona la risorsa monitorata

Per instradare i log solo da una risorsa monitorata specifica in un progetto Google Cloud, 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 la pagina Tipi di risorse monitorate.

Seleziona un campione di voci di log

Per eseguire il routing di 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 questa aggiunta:

sample(insertId, 0.10) AND ...

Per scoprire di più, consulta la funzione sample.

Per ulteriori informazioni sui filtri di Cloud Logging, consulta la pagina Logging query language.

Imposta autorizzazioni destinazione

Questa sezione descrive come concedere a Logging le autorizzazioni Identity and Access Management per scrivere i 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 instrada i log a qualsiasi destinazione diversa da un bucket di log nel progetto attuale, è necessario un account di servizio per tale sink. Logging crea e gestisce automaticamente l'account di servizio per te:

  • A partire dal 22 maggio 2023, quando crei un sink e non esiste un account di servizio per la risorsa sottostante, Logging crea l'account di servizio. Logging utilizza lo stesso account di servizio per tutti i sink nella risorsa sottostante. Le risorse possono essere un progetto Google Cloud, un'organizzazione, una cartella o un account di fatturazione.
  • Prima del 22 maggio 2023, Logging creava un account di servizio 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à del creatore di un sink è l'identificatore dell'account di servizio associato al sink. Tutti i sink hanno un'identità autore a meno che non scrivano in un bucket di log nel progetto Google Cloud attuale.

Per instradare i log a una risorsa protetta da un perimetro di servizio, devi aggiungere l'account di servizio per quel sink a un livello di accesso e 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 il sink verso la destinazione, segui questi passaggi:

Console

  1. Per ottenere informazioni sull'account di servizio per il tuo sink, procedi nel seguente modo:

    1. Nella console Google Cloud, seleziona Logging dal menu di navigazione, quindi fai clic su Log Router:
      Vai a Router Log

    2. Seleziona Menu Visualizza dettagli sink.

      Nel riquadro Dettagli sink, il campo writerIdentity contiene l'identità dell'account di servizio. La stringa serviceAccount: fa parte dell'identità dell'account di servizio. Ad esempio:

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

  2. Nel progetto di destinazione, concedi all'identità dell'autore il ruolo richiesto per consentire all'account di servizio di scrivere nella destinazione. Per concedere un ruolo a un'entità, devi avere il ruolo di Proprietario (roles/owner):

    • Per le destinazioni Cloud Storage, aggiungi l'identità del creatore del sink come entità utilizzando IAM, quindi assegnagli il ruolo Creatore di oggetti Storage (roles/storage.objectCreator).
    • Per le destinazioni BigQuery, aggiungi l'identità del creatore del sink come entità utilizzando IAM e quindi assegnagli il ruolo di Editor dati BigQuery (roles/bigquery.dataEditor).
    • Per le destinazioni Pub/Sub, incluso Splunk, aggiungi l'identità del creatore del sink come entità utilizzando IAM e poi concedi il ruolo Publisher di Pub/Sub (roles/pubsub.publisher).
    • Per le destinazioni dei bucket di logging in progetti Google Cloud diversi, aggiungi l'identità del creatore del sink come entità utilizzando IAM e quindi concedi il ruolo Writer bucket di log (roles/logging.bucketWriter).
    • (Anteprima) Per destinazioni di progetto Google Cloud diverse, aggiungi l'identità del creatore del sink come entità utilizzando IAM, quindi assegnagli il ruolo Writer log (roles/logging.logWriter). Nello specifico, un'entità richiede l'autorizzazione logging.logEntries.route.
    Se non hai accesso come Proprietario alla destinazione del sink, chiedi a un proprietario del progetto di aggiungere l'identità dell'autore come entità.

API

  1. Per ottenere informazioni sull'account di servizio per il sink, chiama il metodo API organizations.sinks.get o folders.sinks.get.

    Il campo writerIdentity contiene l'identità dell'account di servizio. La stringa serviceAccount: fa parte dell'identità dell'account di servizio. Ad esempio:

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

  2. Nel progetto di destinazione, concedi all'identità dell'autore il ruolo richiesto per consentire all'account di servizio di scrivere nella destinazione. Per concedere un ruolo a un'entità, devi avere il ruolo di Proprietario (roles/owner):

    • Per le destinazioni Cloud Storage, aggiungi l'identità del creatore del sink come entità utilizzando IAM, quindi assegnagli il ruolo Creatore di oggetti Storage (roles/storage.objectCreator).
    • Per le destinazioni BigQuery, aggiungi l'identità del creatore del sink come entità utilizzando IAM e quindi assegnagli il ruolo di Editor dati BigQuery (roles/bigquery.dataEditor).
    • Per le destinazioni Pub/Sub, incluso Splunk, aggiungi l'identità del creatore del sink come entità utilizzando IAM e poi concedi il ruolo Publisher di Pub/Sub (roles/pubsub.publisher).
    • Per le destinazioni dei bucket di logging in progetti Google Cloud diversi, aggiungi l'identità del creatore del sink come entità utilizzando IAM e quindi concedi il ruolo Writer bucket di log (roles/logging.bucketWriter).
    • (Anteprima) Per destinazioni di progetto Google Cloud diverse, aggiungi l'identità del creatore del sink come entità utilizzando IAM, quindi assegnagli il ruolo Writer log (roles/logging.logWriter). Nello specifico, un'entità richiede l'autorizzazione logging.logEntries.route.
    Se non hai accesso come Proprietario alla destinazione del sink, chiedi a un proprietario del progetto di aggiungere l'identità dell'autore come entità.

gcloud

  1. Per ottenere informazioni sull'account di servizio per il tuo sink, esegui questo comando:

    gcloud logging sinks describe SINK_NAME

    Il campo writerIdentity contiene l'identità dell'account di servizio. La stringa serviceAccount: fa parte dell'identità dell'account di servizio. Ad esempio:

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

  2. Nel progetto di destinazione, concedi all'identità dell'autore il ruolo richiesto per consentire all'account di servizio di scrivere nella destinazione. Per concedere un ruolo a un'entità, devi avere il ruolo di Proprietario (roles/owner):

    • Per le destinazioni Cloud Storage, aggiungi l'identità del creatore del sink come entità utilizzando IAM, quindi assegnagli il ruolo Creatore di oggetti Storage (roles/storage.objectCreator).
    • Per le destinazioni BigQuery, aggiungi l'identità del creatore del sink come entità utilizzando IAM e quindi assegnagli il ruolo di Editor dati BigQuery (roles/bigquery.dataEditor).
    • Per le destinazioni Pub/Sub, incluso Splunk, aggiungi l'identità del creatore del sink come entità utilizzando IAM e poi concedi il ruolo Publisher di Pub/Sub (roles/pubsub.publisher).
    • Per le destinazioni dei bucket di logging in progetti Google Cloud diversi, aggiungi l'identità del creatore del sink come entità utilizzando IAM e quindi concedi il ruolo Writer bucket di log (roles/logging.bucketWriter).
    • (Anteprima) Per destinazioni di progetto Google Cloud diverse, aggiungi l'identità del creatore del sink come entità utilizzando IAM, quindi assegnagli il ruolo Writer log (roles/logging.logWriter). Nello specifico, un'entità richiede l'autorizzazione logging.logEntries.route.
    Se non hai accesso come Proprietario alla destinazione del sink, chiedi a un proprietario del progetto di aggiungere l'identità dell'autore come entità.

    Ad esempio, se esegui il routing dei log tra bucket di logging in progetti Google Cloud diversi, devi aggiungere roles/logging.bucketWriter all'account di servizio come segue:

    1. Scarica il criterio Identity and Access Management per il progetto Google Cloud di destinazione e scrivilo in un file locale in formato JSON:

      gcloud projects get-iam-policy DESTINATION_PROJECT_ID --format json > output.json

    2. Aggiungi una condizione IAM che consenta all'account di servizio di scrivere solo nella destinazione che hai creato. Ad esempio:

      {
"bindings": [
 {
   "members": [
     "user:username@gmail.com"
   ],
   "role": "roles/owner"
 },
 {
   "members": [
     "SERVICE_ACCOUNT"
   ],
   "role": "roles/logging.bucketWriter",
   "condition": {
       "title": "Bucket writer condition example",
       "description": "Grants logging.bucketWriter role to service account SERVICE_ACCOUNT used by sink SINK_NAME",
       "expression":
         "resource.name.endsWith(\'locations/global/buckets/BUCKET_ID\')"
   }
 }
],
"etag": "BwWd_6eERR4=",
"version": 3
}

    3. Aggiorna il criterio IAM:

      gcloud projects set-iam-policy DESTINATION_PROJECT_ID output.json

Passaggi successivi