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

I sink aggregati in Cloud Logging consentono di combinare e instradare le voci di log da tutte le risorse di una cartella o di un'organizzazione a una destinazione centrale. Puoi configurare un sink aggregato come intercettante o non intercettante, definire filtri per controllare quali voci di log vengono indirizzate e concedere al sink l'autorizzazione a scrivere nella destinazione.

Limitazioni

Quando configuri un sink aggregato, si applicano le seguenti limitazioni:

  • Un percorso di destinazione può includere solo un endpoint di servizio globale, ad esempio pubsub.googleapis.com. Non puoi includere un endpoint di servizio regionale (REP) come pubsub.LOCATION.rep.googleapis.com. Per un elenco dei percorsi di destinazione supportati, consulta Formati dei percorsi di destinazione.

  • Il routing dei dati di log agli argomenti Pub/Sub con limitazioni in transito non è supportato. Se configuri un sink di log in un argomento Pub/Sub con limitazioni in transito, potresti visualizzare errori di configurazione topic_region_not_allowed e log ignorati.

  • Il routing delle voci di log a una risorsa protetta da un perimetro di servizio richiede l'aggiunta di una regola in entrata al perimetro che consenta l'accesso dal account di servizio del sink:

    Se utilizzi un sink di log aggregato per indirizzare le voci di log a un bucket Cloud Storage che si trova in un perimetro, utilizza ANY_IDENTITY come tipo di identità nella regola di traffico in entrata. Non puoi utilizzare ANY_SERVICE_ACCOUNT o ANY_USER_ACCOUNT come tipo di identità per questa destinazione.

    Non è necessario configurare una regola in entrata per i sink non aggregati.

Prima di iniziare

Prima di creare un sink, assicurati di quanto segue:

  • Hai familiarità con il comportamento dei sink aggregati. Per saperne di più, consulta la panoramica dei sink aggregati.

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

  • Disponi di uno dei seguenti ruoli Identity and Access Management per l'organizzazioneGoogle Cloud o la cartella da cui esegui il routing delle voci di log:

    • Owner (roles/owner)
    • Logging Admin (roles/logging.admin)
    • Logs Configuration Writer (roles/logging.configWriter)

    Le autorizzazioni contenute in questi ruoli ti consentono di creare, eliminare o modificare 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. La destinazione può trovarsi in qualsiasi progetto Google Cloud e in qualsiasi organizzazione. Per un elenco delle destinazioni supportate e delle relative limitazioni, consulta Destinazioni supportate.

  • Seleziona l'interfaccia che intendi utilizzare:

    Console

    Quando utilizzi la console Google Cloud per accedere ai servizi e alle API Google Cloud , non devi configurare l'autenticazione.

    gcloud

    Nella console Google Cloud , attiva Cloud Shell.

    Attiva Cloud Shell

    Nella parte inferiore della console Google Cloud viene avviata una sessione di Cloud Shell e viene visualizzato un prompt della riga di comando. Cloud Shell è un ambiente shell con Google Cloud CLI già installata e con valori già impostati per il progetto corrente. L'inizializzazione della sessione può richiedere alcuni secondi.

    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.

      Installa Google Cloud CLI.

      Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

    Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Crea un sink aggregato

Per configurare un sink aggregato, crea il sink e poi concedigli le autorizzazioni per scrivere nella destinazione. Questa sezione descrive come creare un sink aggregato. Per informazioni sulla concessione delle autorizzazioni al sink, consulta Imposta le autorizzazioni della destinazione.

Puoi creare fino a 200 sink per cartella o organizzazione.

Console

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

  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 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. Dopo aver creato il sink, non puoi rinominarlo, ma puoi eliminarlo e crearne uno nuovo.

    • (Facoltativo) Descrizione 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 Google Cloud progetto e poi inserisci il nome completo del progetto di destinazioneGoogle Cloud :

      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:

      • progettoGoogle Cloud 

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • Bucket di Logging

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

      • Set di dati BigQuery

        Inserisci il nome di un set di dati abilitato alla scrittura. Non inserire il nome di un set di dati BigQuery collegato, in quanto questi set di dati sono di sola lettura. Puoi utilizzare le tabelle partizionate.

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

      • Bucket Cloud Storage

        storage.googleapis.com/BUCKET_NAME

      • Argomento Pub/Sub

        Non inserire il nome di un argomento Pub/Sub che applica limitazioni in transito.

        pubsub.googleapis.com/projects/DESTINATION_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 figlio.

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

  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 è simile al seguente:

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

    Per esempi, consulta Filtri per i sink aggregati.

    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 dal routing alla destinazione, aggiungi il seguente filtro di esclusione:

      logName:projects/PROJECT_ID

      Per escludere le voci di log da più progetti, utilizza l'operatore logico OR 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 al account di servizio del sink l'autorizzazione per scrivere voci di log nella destinazione del sink. Per saperne di più, consulta Imposta le autorizzazioni della destinazione.

gcloud

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

  1. Per creare un sink, esegui il comando gcloud logging sinks create e includi il flag --include-children.

    Prima di utilizzare il comando seguente, apporta 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, consulta Filtri per i 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"

    Per creare un sink di intercettazione, includi anche il flag --intercept-children.

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

    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 saperne di più, consulta Imposta le autorizzazioni della destinazione.

REST

Per creare un sink aggregato, utilizza il metodo dell'API Logging organizations.sinks.create o folders.sinks.create. Prepara gli argomenti per il metodo come segue:

  1. Imposta il campo parent sull'organizzazione o sulla cartella Google Cloud in cui creare il sink. Il valore parent 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, consulta Filtri per i 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 saperne di più, consulta Instrada i log verso destinazioni supportate.

  5. Chiama 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 saperne di più, consulta Imposta le autorizzazioni della destinazione.

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

Imposta le autorizzazioni di destinazione

Questa sezione descrive come concedere all'identità writer di un sink di log le autorizzazioni IAM necessarie affinché il sink possa scrivere le voci di log nella destinazione del sink. L'identità writer è l'ID del account di servizio associato al sink. Questa identità include un indirizzo email che identifica l'entità che deve avere accesso per scrivere dati nella destinazione.

Non è necessario impostare le autorizzazioni di destinazione quando un sink di log indirizza le voci di log a un bucket di log nello stesso progetto. Per questa configurazione, non è richiesto un account di servizio. Per tutte le altre configurazioni, Logging crea e gestisce automaticamente il account di servizio per un sink di log e devi impostare le autorizzazioni di destinazione:

  • A partire dal 22 maggio 2023, Logging utilizza lo stesso account di servizio per tutti i sink nella risorsa sottostante. Le risorse possono essere un progetto, un'organizzazione, una cartella o un account di fatturazioneGoogle Cloud .
  • Prima del 22 maggio 2023, Logging creava un service account per ogni sink.

Se la destinazione del sink è protetta da un perimetro di servizio dei Controlli di servizio VPC, devi anche aggiungere al perimetro di destinazione una regola in entrata che consenta l'accesso dall'identità writer del sink. Per ulteriori informazioni, vedi Limiti.

Per impostare le autorizzazioni per la destinazione del sink, procedi nel seguente modo:

Console

  1. Per ottenere informazioni sul account di servizio del sink, segui questi passaggi:

    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, quindi seleziona Visualizza dettagli sink. L'identità writer viene visualizzata nel riquadro Dettagli sink.

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

    4. Copia l'identità del writer del sink negli appunti. Le identità dell'autore potrebbero avere un aspetto diverso a seconda della risorsa a cui appartiene il sink, ma sono sempre precedute da serviceAccount:. Di seguito è riportato un esempio di identità del writer:

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

  2. Concedi all'entità specificata dall'identità writer del sink l'autorizzazione per scrivere i 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 che archivia la destinazione del sink aggregato. Se la destinazione è un progetto, seleziona il progetto.

    3. Fai clic su Concedi l'accesso.

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

      • Per tutte le destinazioni, concedi il ruolo Writer log (roles/logging.logWriter). In particolare, un'entità deve disporre dell'autorizzazione logging.logEntries.route.
      • Concedi uno dei seguenti ruoli in base alla destinazione:

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 Project Owner di aggiungere l'identità del writer come entità.

  2. Per ottenere informazioni sul account di servizio del sink, esegui il comando gcloud logging sinks describe.

    Prima di utilizzare il comando seguente, apporta 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 con l'etichetta writerIdentity, vai al passaggio successivo. Se 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 per scrivere i dati di log nella destinazione eseguendo il comando gcloud projects add-iam-policy-binding.

    Prima di utilizzare il comando seguente, apporta 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 entità hanno in genere 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 delle entità.

    • ROLE: un ruolo IAM. Concedi all'identità writer del sink un ruolo IAM in base alla destinazione del sink di log:

      • Per tutte le destinazioni, concedi il ruolo Writer log (roles/logging.logWriter). In particolare, un'entità deve disporre dell'autorizzazione logging.logEntries.route.
      • Concedi uno dei seguenti ruoli in base alla destinazione:

      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.

Filtri per i sink aggregati

Questa sezione fornisce esempi di filtri che potresti utilizzare in un sink 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 =.
  • ... rappresenta eventuali confronti di filtri aggiuntivi.
  • Le variabili sono indicate da un testo colorato. Sostituiscili con valori validi.

La lunghezza di un filtro è limitata a 20.000 caratteri.

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

Seleziona la sorgente log

Per instradare le voci di log da tutte le risorse figlio, 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 questo filtro, il sink aggregato indirizza le voci di log delle istanze di Compute Engine in qualsiasi risorsa secondaria di quell'organizzazione alla destinazione.

Tuttavia, in alcune situazioni potresti voler utilizzare un sink aggregato 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 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, 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 generate dalle istanze Compute Engine e provenienti dalla cartella my-folder, utilizza il seguente filtro:

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

Con questo filtro, le voci di log provenienti da qualsiasi risorsa diversa damy-folder, incluse le voci di log provenienti da progetti Google Cloud figli di my-folder, non vengono indirizzate alla destinazione.

Seleziona la risorsa monitorata

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

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 instradare solo il 10% delle voci di log corrispondenti al filtro corrente, utilizza questa aggiunta:

sample(insertId, 0.10) AND ...

Per saperne di più, consulta la funzione sample.

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

Passaggi successivi