Recopilar y enrutar registros a nivel de organización y de carpeta a destinos admitidos

En este documento se describe cómo crear sinks agregados. Los sumideros agregados te permiten combinar y enrutar los registros que generan los Google Cloud recursos de tu organización o carpeta a una ubicación centralizada.

Antes de empezar

Antes de crear un receptor, asegúrate de que se cumplen los siguientes requisitos:

  • Conoces el comportamiento de los receptores agregados. Para obtener información sobre estos receptores, consulta Introducción a los receptores agregados.

  • Tienes una Google Cloud carpeta u organización con entradas de registro que puedes ver en el Explorador de registros.

  • Tienes uno de los siguientes roles de gestión de identidades y accesos en la organización o carpetaGoogle Cloud desde la que estás enrutando las entradas de registro.

    • Propietario (roles/owner)
    • Administrador de registro (roles/logging.admin)
    • Editor de configuración de registros (roles/logging.configWriter)

    Los permisos incluidos en estos roles te permiten crear, eliminar o modificar sinks. Para obtener información sobre cómo definir roles de gestión de identidades y accesos, consulta la guía de control de acceso de Logging.

  • El destino del receptor agregado existe o tienes permiso para crearlo.

    Si el destino es un proyecto, este puede estar en cualquier organización. Google Cloud El resto de los destinos pueden estar en cualquier proyecto de cualquier organización.

  • 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

    Para usar las muestras de la API REST de esta página en un entorno de desarrollo local, debes usar las credenciales que proporciones a la CLI de gcloud.

      Instala Google Cloud CLI. Después de la instalación, inicializa la CLI de Google Cloud ejecutando el siguiente comando: 

      gcloud init

      Si utilizas un proveedor de identidades (IdP) externo, primero debes iniciar sesión en la CLI de gcloud con tu identidad federada.

    Para obtener más información, consulta el artículo Autenticarse para usar REST de la documentación sobre autenticación de Google Cloud .

Crear un sumidero agregado

Para configurar un receptor agregado, cree el receptor y, a continuación, concédale los permisos para escribir en el destino. En esta sección se describe cómo crear un receptor agregado. Para obtener información sobre cómo conceder permisos al receptor, consulta la sección de esta página titulada Definir permisos de destino.

Puedes crear hasta 200 sinks por carpeta u organización.

Consola

Para crear un receptor agregado para tu carpeta u organización, sigue estos pasos:

  1. En la Google Cloud consola, ve a la página Enrutador de registros:

    Ve a Enrutador de registros.

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.

  2. Selecciona una carpeta o una organización.

  3. Selecciona Crear sumidero.

  4. En el panel Detalles del receptor, introduce los siguientes datos:

    • Nombre del receptor: proporciona un identificador para el receptor. Ten en cuenta que, una vez que lo hayas creado, no podrás cambiarle el nombre, pero sí eliminarlo y crear uno nuevo.

    • Descripción del receptor (opcional): describe el objetivo o el caso práctico del receptor.

  5. En el menú Seleccionar servicio de sumidero, elija el tipo de destino y, a continuación, complete el cuadro de diálogo para especificar el destino. Puede seleccionar un destino que ya tenga o crear uno.

    • En el caso de un sumidero interceptor, selecciona Google Cloud proyecto y, a continuación, introduce el nombre completo del proyecto de destino: Google Cloud 

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

    • En el caso de un receptor que no intercepte, selecciona el destino y, a continuación, introduce el nombre completo del destino. Se admiten los siguientes destinos:

      • Google Cloud proyecto

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • Cubeta de Cloud Logging

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

      • Conjunto de datos de BigQuery

        Debes introducir el nombre completo de un conjunto de datos con permiso de escritura. El conjunto de datos puede ser una tabla con particiones por fecha o con particiones al uso. No introduzcas el nombre de un conjunto de datos vinculado. Los conjuntos de datos vinculados son de solo lectura.

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

      • Contenedor de Cloud Storage

        storage.googleapis.com/BUCKET_NAME

      • Tema de Pub/Sub

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

      • Splunk

        Introduce el tema de Pub/Sub de tu servicio Splunk.

  6. En el panel Seleccionar los registros que se incluirán en el sumidero, selecciona los recursos que quieras incluir en el sumidero.

    • En el caso de un receptor de intercepción, selecciona Interceptar los registros insertados por esta organización y todos los recursos secundarios.

    • En el caso de un receptor que no intercepte, selecciona Incluir registros insertados por este recurso y todos los recursos secundarios.

  7. En el campo Crear filtro de inclusión, introduce una expresión de filtro que coincida con las entradas de registro que quieras incluir. Si no define ningún filtro, todas las entradas de registro del recurso seleccionado se dirigirán al destino.

    Por ejemplo, puede crear un filtro para enrutar todos los registros de auditoría de acceso a datos a un solo bucket de Logging. Este filtro tiene el siguiente aspecto:

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

    Para ver ejemplos de filtros, consulta la sección Crear filtros para receptores agregados de esta página.

    Ten en cuenta que la longitud de un filtro no puede superar los 20.000 caracteres.

  8. Opcional: Para comprobar que has introducido el filtro correcto, selecciona Vista previa de los registros. Se abrirá el Explorador de registros en una nueva pestaña con el filtro rellenado automáticamente.

  9. Opcional: En el panel Seleccionar los registros que se excluirán del sumidero, haz lo siguiente:

    1. En el campo Nombre del filtro de exclusión, introduce un nombre.

    2. En el campo Crear filtro de exclusión, introduce una expresión de filtro que coincida con las entradas de registro que quieras excluir. También puedes usar la función sample para seleccionar una parte de las entradas de registro que quieras excluir.

      Por ejemplo, para evitar que las entradas de registro de un proyecto específico se enruten al destino, añade el siguiente filtro de exclusión:

      logName:projects/PROJECT_ID

      Para excluir entradas de registro de varios proyectos, usa el operador lógico OR para unir cláusulas logName.

    Puede crear hasta 50 filtros de exclusión por receptor. Ten en cuenta que la longitud de un filtro no puede superar los 20.000 caracteres.

  10. Selecciona Crear sumidero.

  11. Para completar la configuración del sumidero agregado, concede a la cuenta de servicio del sumidero el permiso para escribir entradas de registro en el destino del sumidero. Para obtener más información, consulta Definir permisos de destino.

gcloud

Para crear un receptor agregado, usa el comando logging sinks create:

  1. Para crear un receptor, llama al comando gcloud logging sinks create y asegúrate de incluir la opción --include-children.

    Antes de usar el siguiente comando, haz las sustituciones que se indican a continuación:

    • SINK_NAME: el nombre del sumidero de registros. No puedes cambiar el nombre de un receptor después de crearlo.
    • SINK_DESTINATION: el servicio o proyecto al que quieres dirigir las entradas de registro. Para obtener información sobre el formato de estos destinos, consulta Formatos de ruta de destino.
    • INCLUSION_FILTER: el filtro de inclusión de un sumidero. Para ver ejemplos de filtros, consulte Crear filtros para sinks agregados.
    • FOLDER_ID: el ID de la carpeta. Si quieres crear un receptor a nivel de organización, sustituye --folder=FOLDER_ID por -- organization=ORGANIZATION_ID.

    Ejecuta el comando gcloud logging sinks create:

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

    También puedes proporcionar las siguientes opciones:

    • Para crear un receptor interceptor, incluye la opción --intercept-children.

    Por ejemplo, si crea un receptor agregado a nivel de carpeta y cuyo destino es un tema de Pub/Sub, el comando podría tener el siguiente aspecto:

    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. Concede a la cuenta de servicio del sumidero permiso para escribir en el destino del sumidero. Para obtener más información, consulta Definir permisos de destino.

REST

Para crear un receptor agregado, usa el método de la API Logging organizations.sinks.create o folders.sinks.create. Prepara los argumentos del método de la siguiente manera:

  1. Asigna al campo parent el valor de la organización o la carpeta en la que se creará el receptor. Google Cloud El elemento principal debe ser uno de los siguientes:

    • organizations/ORGANIZATION_ID
    • folders/FOLDER_ID

  2. En el objeto LogSink del cuerpo de la solicitud del método, haga una de las siguientes acciones:

    • Asigna el valor True a includeChildren.

    • Para crear un receptor interceptor, también debes asignar el valor True al campo interceptChildren.

  3. Defina el campo filter para que coincida con las entradas de registro que quiera incluir.

    Para ver ejemplos de filtros, consulte Crear filtros para sinks agregados.

    La longitud de un filtro no puede superar los 20.000 caracteres.

  4. Define los campos restantes de LogSink como lo harías con cualquier otro receptor. Para obtener más información, consulta el artículo sobre enrutar registros a destinos admitidos.

  5. Llama al organizations.sinks.create o al folders.sinks.create para crear el receptor.

  6. Concede a la cuenta de servicio del sumidero permiso para escribir en el destino del sumidero. Para obtener más información, consulta Definir permisos de destino.

Los cambios que se hagan en un receptor pueden tardar unos minutos en aplicarse.

Filtros de sumideros agregados

En esta sección se proporcionan ejemplos de filtros que puede usar en un receptor agregado. Para ver más ejemplos, consulta Consultas de ejemplo con el Explorador de registros.

En algunos ejemplos se utiliza la siguiente notación:

  • : es el operador de subcadena. No sustituyas el operador =.
  • ... representa cualquier otra comparación de filtros.
  • Las variables se indican con texto de color. Sustitúyelos por valores válidos.

La longitud de un filtro está limitada a 20.000 caracteres.

Para obtener más información sobre la sintaxis de los filtros, consulta el artículo Lenguaje de consultas de registro.

Seleccionar el origen del archivo de registro

Para enrutar entradas de registro de todos los recursos secundarios, no especifiques ningún proyecto, carpeta u organización en los filtros de inclusión y exclusión del receptor. Por ejemplo, supongamos que configura un receptor agregado para una organización con el siguiente filtro:

resource.type="gce_instance"

Con el filtro anterior, las entradas de registro con un tipo de recurso de instancias de Compute Engine que se escriben en cualquier elemento secundario de esa organización se enrutan mediante el receptor agregado al destino.

Sin embargo, puede que haya situaciones en las que quieras usar un receptor agregado para enrutar entradas de registro solo de recursos secundarios específicos. Por ejemplo, por motivos de cumplimiento, puede que quieras almacenar los registros de auditoría de carpetas o proyectos específicos en su propio segmento de Cloud Storage. En estos casos, configura el filtro de inclusión para especificar cada recurso secundario cuyas entradas de registro quieras enrutar. Si quieres enrutar las entradas de registro de una carpeta y de todos los proyectos que contiene, el filtro debe incluir la carpeta y cada uno de los proyectos que contiene, así como unir las instrucciones con una cláusula OR.

Los siguientes filtros restringen las entradas de registro a proyectos Google Cloud , carpetas u organizaciones específicos:

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

Por ejemplo, para enrutar solo las entradas de registro escritas en instancias de Compute Engine que se hayan escrito en la carpeta my-folder, usa el siguiente filtro:

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

Con el filtro anterior, las entradas de registro escritas en cualquier recurso que no sea my-folder, incluidas las entradas de registro escritas en proyectos Google Cloud que sean elementos secundarios de my-folder, no se enrutan al destino.

Seleccione el recurso monitorizado.

Para enrutar entradas de registro de un recurso monitorizado específico de unGoogle Cloud proyecto, usa varias comparaciones para especificar el recurso exactamente:

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

Para ver una lista de los tipos de recursos, consulta Tipos de recursos monitorizados.

Seleccionar una muestra de entradas de registro

Para enrutar una muestra aleatoria de entradas de registro, añade la función integrada sample. Por ejemplo, para enrutar solo el diez por ciento de las entradas de registro que coincidan con el filtro actual, añade lo siguiente:

sample(insertId, 0.10) AND ...

Para obtener más información, consulta la función sample.

Para obtener más información sobre los filtros de Cloud Logging, consulta el lenguaje de consultas de registro.

Definir permisos de destino

En esta sección se describe cómo conceder a Logging los permisos de gestión de identidades y accesos para escribir entradas de registro en el destino de tu receptor. Para ver la lista completa de roles y permisos de Logging, consulta Control de acceso.

Cuando creas o actualizas un receptor que dirige entradas de registro a cualquier destino que no sea un segmento de registro del proyecto actual, se necesita una cuenta de servicio para ese receptor. Logging crea y gestiona automáticamente la cuenta de servicio:

  • Desde el 22 de mayo del 2023, cuando creas un receptor y no existe ninguna cuenta de servicio para el recurso subyacente, Logging crea la cuenta de servicio. El registro usa la misma cuenta de servicio para todos los receptores del recurso subyacente. Los recursos pueden ser un Google Cloud proyecto, una organización, una carpeta o una cuenta de facturación.
  • Antes del 22 de mayo del 2023, Logging creaba una cuenta de servicio para cada receptor. Desde el 22 de mayo del 2023, Logging usa una cuenta de servicio compartida para todos los receptores del recurso subyacente.

La identidad de escritura de un receptor es el identificador de la cuenta de servicio asociada a ese receptor. Todos los receptores tienen una identidad de escritura, a menos que escriban en un contenedor de registro del proyecto actual. Google Cloud La dirección de correo de la identidad del escritor identifica la entidad principal que debe tener acceso para escribir datos en el destino.

Para enrutar entradas de registro a un recurso protegido por un perímetro de servicio, debes añadir la cuenta de servicio de ese receptor a un nivel de acceso y, a continuación, asignarla al perímetro de servicio de destino. No es necesario para los receptores no agregados. Para obtener más información, consulta Controles de Servicio de VPC: Cloud Logging.

Para definir los permisos de tu receptor para que se dirija a su destino, haz lo siguiente:

Consola

  1. Para obtener información sobre la cuenta de servicio de tu receptor, haz lo siguiente:

    1. En la Google Cloud consola, ve a la página Enrutador de registros:

      Ve a Enrutador de registros.

      Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Registro.

    2. Selecciona Menú y, a continuación, Ver detalles del receptor. La identidad del escritor aparece en el panel Detalles del receptor.

    3. Si el valor del campo writerIdentity contiene una dirección de correo electrónico, vaya al paso siguiente. Si el valor es None, no es necesario configurar los permisos de destino.

    4. Copia la identidad de escritura del receptor en el portapapeles. A continuación, se muestra un ejemplo de identidad de escritor:

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

  2. Concede al principal especificado por la identidad de escritor del sumidero el permiso para escribir datos de registro en el destino:

    1. En la Google Cloud consola, ve a la página Gestión de identidades y accesos:

      Ve a Gestión de identidades y accesos.

      Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo sea IAM y administrador.

    2. En la barra de herramientas de la consola Google Cloud , selecciona el proyecto que almacena el destino del receptor agregado. Si el destino es un proyecto, selecciónalo.

    3. Haz clic en Conceder acceso.

    4. Introduce la entidad principal especificada por la identidad de escritura del receptor y, a continuación, asigna un rol de gestión de identidades y accesos:

gcloud

  1. Asegúrate de que tienes acceso de propietario alGoogle Cloud proyecto que contiene el destino. Si no tienes acceso de propietario al destino del receptor, pide a un propietario del proyecto que añada la identidad de escritura como principal.

  2. Para obtener información sobre la cuenta de servicio de tu receptor, llama al método gcloud logging sinks describe.

    Antes de usar el siguiente comando, haz las sustituciones que se indican a continuación:

    • SINK_NAME: el nombre del sumidero de registros. No puedes cambiar el nombre de un receptor después de crearlo.

    Ejecuta el comando gcloud logging sinks describe:

    gcloud logging sinks describe SINK_NAME

  3. Si los detalles del receptor contienen un campo etiquetado como writerIdentity, vaya al paso siguiente. Si los detalles no incluyen el campo writerIdentity, no es necesario que configures los permisos de destino del receptor.

  4. Copia la identidad de escritura del receptor en el portapapeles. A continuación, se muestra un ejemplo de identidad de escritor:

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

  5. Concede a la identidad de escritura del sumidero el permiso para escribir datos de registro en el destino llamando al comando gcloud projects add-iam-policy-binding.

    Antes de usar el siguiente comando, haz las sustituciones que se indican a continuación:

    • PROJECT_ID: identificador del proyecto. Selecciona el proyecto que almacena el destino del receptor agregado. Si el destino es un proyecto, selecciónalo.
    • PRINCIPAL: identificador de la cuenta principal a la que quieres asignar el rol. Los identificadores principales suelen tener el siguiente formato: PRINCIPAL-TYPE:ID. Por ejemplo, user:my-user@example.com. Para ver una lista completa de los formatos que puede tener PRINCIPAL, consulta Identificadores principales.

    • ROLE: un rol de gestión de identidades y accesos. Concede a la identidad de escritura del sumidero un rol de gestión de identidades y accesos en función del destino del sumidero de registro:

    Ejecuta el comando gcloud projects add-iam-policy-binding:

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

REST

Te recomendamos que uses la Google Cloud consola o la CLI de Google Cloud para asignar un rol a la cuenta de servicio.

Siguientes pasos