Recopila y enruta registros a nivel de la organización y de la carpeta a destinos compatibles

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

Antes de comenzar

Antes de crear un receptor, asegúrate de lo siguiente:

  • Debes conocer el comportamiento de los receptores agregados. Para obtener más información sobre estos receptores, consulta la Descripción general de los receptores agregados.

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

  • Tienes uno de los siguientes roles de IAM para la organización o la carpetaGoogle Cloud desde la que enrutas entradas de registro.

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

    Los permisos contenidos en estos roles te permiten crear, borrar o modificar receptores. Para obtener información sobre cómo configurar roles de IAM, consulta la Guía de control de acceso de Logging.

  • El destino del receptor agregado existe o tienes la capacidad de crearlo.

    Cuando el destino es un proyecto de Google Cloud , este puede estar en cualquier organización. Todos los demás 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 de REST en esta página en un entorno de desarrollo local, debes usar las credenciales que proporcionas a gcloud CLI.

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

      gcloud init

      Si usas un proveedor de identidad externo (IdP), primero debes acceder a gcloud CLI con tu identidad federada.

    Si deseas obtener más información, consulta Autentica para usar REST en la Google Cloud documentación de autenticación.

Crea un receptor agregado

Para configurar un receptor agregado, crea el receptor y, luego, otórgale 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 otorgar permisos al receptor, consulta la sección de esta página titulada Cómo establecer permisos de destino.

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

Console

Para crear un receptor agregado para tu carpeta u organización, haz lo siguiente:

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

    Ir a Enrutador de registros

    Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

  2. Selecciona una carpeta o una organización existente.

  3. Selecciona Crear receptor.

  4. En el panel Detalles del receptor, ingresa los siguientes detalles:

    • Nombre del receptor: Proporciona un identificador para el receptor. Ten en cuenta que, después de crear el receptor, no podrás cambiarle el nombre, pero sí podrás borrarlo y crear uno nuevo.

    • Descripción del receptor (opcional): Describe el propósito o el caso de uso del receptor.

  5. En el menú Selecciona el servicio del receptor, selecciona el tipo de destino y, luego, completa el diálogo para especificar el destino. Puedes seleccionar un destino existente o crear uno.

    • Para un receptor de interceptación, selecciona Google Cloud proyecto y, luego, ingresa el nombre completo del proyecto de destino Google Cloud :

      logging.googleapis.com/projects/DESTINATION_PROJECT_ID

    • Para un receptor que no intercepta, selecciona el destino y, luego, ingresa el nombre completo del destino. Se admiten los siguientes destinos:

      • Google Cloud project

        logging.googleapis.com/projects/DESTINATION_PROJECT_ID

      • Bucket de Cloud Logging

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

      • Conjunto de datos de BigQuery

        Debes ingresar el nombre completo de un conjunto de datos habilitado para escritura. El conjunto de datos puede ser una tabla particionada o fragmentada por fecha. No ingreses 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

      • Bucket de Cloud Storage

        storage.googleapis.com/BUCKET_NAME

      • Tema de Pub/Sub

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

      • Splunk

        Ingresa el tema de Pub/Sub para tu servicio de Splunk.

  6. En el panel Elige registros para incluirlos en el receptor, selecciona los recursos que deseas incluir en el receptor.

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

    • Para un receptor que no intercepta, selecciona Incluir los registros transferidos por este recurso y todos los recursos secundarios.

  7. En el campo Crear filtro de inclusión, ingresa una expresión de filtro que coincida con las entradas de registro que deseas incluir. Si no configuras un filtro, todas las entradas de registro del recurso seleccionado se enrutan al destino.

    Por ejemplo, puedes compilar un filtro para enrutar todos los registros de auditoría de acceso a los datos a un solo bucket de Logging. Este filtro se verá de la siguiente manera:

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

    Para ver ejemplos de filtros, consulta la sección Crea 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 verificar que ingresaste el filtro correcto, selecciona Obtener vista previa de los registros. Se abrirá el Explorador de registros en una pestaña nueva con el filtro prepropagado.

  9. Opcional: En el panel Elige registros para excluir del receptor, haz lo siguiente:

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

    2. En el campo Crea un filtro de exclusión, ingresa una expresión de filtro que coincida con las entradas de registro que deseas excluir. También puedes usar la función sample para seleccionar una parte de las entradas de registro que se excluirán.

      Por ejemplo, para excluir las entradas de registro de un proyecto específico del enrutamiento al destino, agrega el siguiente filtro de exclusión:

      logName:projects/PROJECT_ID

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

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

  11. Para completar la configuración de tu receptor agregado, otorga a la cuenta de servicio del receptor el permiso para escribir entradas de registro en el destino del receptor. Para obtener más información, consulta Cómo establecer 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, realiza los siguientes reemplazos:

    • SINK_NAME: Es el nombre del receptor de registros. No puedes cambiar el nombre de un receptor después de crearlo.
    • SINK_DESTINATION: Es el servicio o proyecto al que deseas enrutar tus entradas de registro. Para obtener información sobre el formato de estos destinos, consulta Formatos de rutas de destino.
    • INCLUSION_FILTER: Es el filtro de inclusión para un receptor. Para ver ejemplos de filtros, consulta Crea filtros para receptores agregados.
    • FOLDER_ID: Es el ID de la carpeta. Si quieres crear un receptor a nivel de la organización, reemplaza --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 de interceptación, incluye la opción --intercept-children.

    Por ejemplo, si creas un receptor agregado a nivel de la carpeta y cuyo destino es un tema de Pub/Sub, tu comando podría verse de la siguiente manera:

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

REST

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

  1. Establece el campo parent para que sea la organización o la carpeta en la que se creará el receptor. Google Cloud El elemento superior 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, haz una de las siguientes acciones:

    • Establece includeChildren en True.

    • Para crear un receptor de interceptación, también debes establecer el campo interceptChildren en True.

  3. Establece el campo filter para que coincida con las entradas de registro que deseas incluir.

    Para ver ejemplos de filtros, consulta Crea filtros para receptores agregados.

    La longitud de un filtro no puede superar los 20,000 caracteres.

  4. Establece los campos LogSink restantes como lo harías para cualquier otro receptor. Para obtener más información, consulta Enruta registros a destinos compatibles.

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

  6. Otorga permiso a la cuenta de servicio del receptor para escribir en el destino del receptor. Para obtener más información, consulta Cómo establecer permisos de destino.

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

Filtros para receptores agregados

En esta sección, se proporcionan ejemplos de filtros que puedes usar en un receptor agregado. Para obtener más ejemplos, consulta Ejemplos de consultas con el Explorador de registros.

Algunos ejemplos usan la siguiente notación:

  • : es el operador de la substring. No sustituyas el operador =.
  • ...… representa cualquier comparación de filtro adicional.
  • Las variables se indican con texto de color. Reemplázalos por valores válidos.

La longitud de un filtro está restringida a 20,000 caracteres.

Para obtener más detalles sobre la sintaxis de filtrado, consulta Lenguaje de consulta de Logging.

Selecciona la fuente del archivo de registro

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

resource.type="gce_instance"

Con el filtro anterior, el receptor agregado enruta 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 al destino.

Sin embargo, puede haber situaciones en las que desees usar un receptor agregado para enrutar entradas de registro solo desde recursos secundarios específicos. Por ejemplo, por motivos de cumplimiento, es posible que desees almacenar los registros de auditoría de carpetas o proyectos específicos en su propio bucket de Cloud Storage. En estas situaciones, configura tu filtro de inclusión para especificar cada recurso secundario cuyas entradas de registro deseas que se enruten. Si deseas enrutar las entradas de registro de una carpeta y todos los proyectos que contiene, el filtro debe enumerar la carpeta y cada uno de los proyectos que contiene, y también unir las instrucciones con una cláusula OR.

Los siguientes filtros restringen las entradas de registro a proyectos, carpetas u organizaciones específicos: 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 ...

Por ejemplo, para enrutar solo las entradas de registro escritas en instancias de Compute Engine que se escribieron 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 son secundarios de my-folder, no se enrutan al destino.

Selecciona el recurso supervisado

Para enrutar entradas de registro solo desde un recurso supervisado específico en un proyecto deGoogle Cloud , usa múltiples comparaciones para especificar el recurso de manera exacta:

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

Para obtener una lista de tipos de recursos, consulta Tipos de recursos supervisados.

Selecciona una muestra de entradas de registro

Para enrutar una muestra aleatoria de entradas de registro, agrega la función integrada sample. Por ejemplo, para enrutar solo el diez por ciento de las entradas de registro que coinciden con tu filtro actual, usa esta adición:

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 Lenguaje de consulta de Logging.

Cómo configurar los permisos de destino

En esta sección, se describe cómo otorgar a Logging los permisos de Identity and Access Management para escribir entradas de registro en el destino de tu receptor. Para obtener la lista completa de las funciones y los permisos de Logging, consulta Control de acceso.

Cuando creas o actualizas un receptor que enruta entradas de registro a cualquier destino que no sea un bucket de registros en el proyecto actual, se requiere una cuenta de servicio para ese receptor. Logging crea y administra automáticamente la cuenta de servicio por ti:

  • A partir del 22 de mayo de 2023, cuando creas un receptor y no existe una 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 de 2023, Logging creaba una cuenta de servicio para cada receptor. Desde el 22 de mayo de 2023, Logging usa una cuenta de servicio compartida para todos los receptores del recurso subyacente.

La identidad del escritor de un receptor es el identificador de la cuenta de servicio asociada a ese receptor. Todos los receptores tienen una identidad de escritor, a menos que escriban en un bucket de registros en el proyecto Google Cloud actual. La dirección de correo electrónico en la identidad de escritor identifica al 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 agregar la cuenta de servicio para ese receptor a un nivel de acceso y, luego, asignarla al perímetro de servicio de destino. Esto no es necesario para los receptores no agregados. Para obtener más detalles, consulta Controles del servicio de VPC: Cloud Logging.

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

Console

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

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

      Ir a Enrutador de registros

      Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuyo subtítulo es Logging.

    2. Selecciona Menú y, luego, Ver detalles del receptor. La identidad de escritor aparece en el panel Detalles del receptor.

    3. Si el valor del campo writerIdentity contiene una dirección de correo electrónico, continúa con el siguiente paso. Cuando el valor es None, no es necesario que configures los permisos de destino.

    4. Copia la identidad de escritor del receptor en el portapapeles. En la siguiente imagen, se ilustra una identidad de escritor:

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

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

    1. En la Google Cloud consola, ve a la página IAM:

      Ir a IAM

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

    2. En la barra de herramientas de la consola de Google Cloud , selecciona el proyecto que almacena el destino del receptor agregado. Cuando el destino sea un proyecto, selecciona ese proyecto.

    3. Haz clic en Grant access.

    4. Ingresa la principal especificada por la identidad del escritor del receptor y, luego, otorga un rol de IAM:

gcloud

  1. Asegúrate de tener acceso de propietario al proyectoGoogle Cloud que contiene el destino. Si no tienes acceso de Propietario al destino del receptor, pídele a un propietario del proyecto que agregue la identidad de escritor 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, realiza los siguientes reemplazos:

    • SINK_NAME: Es el nombre del receptor 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, continúa con el siguiente paso. Cuando los detalles no incluyen un campo writerIdentity, no es necesario que configures los permisos de destino para el receptor.

  4. Copia la identidad de escritor del receptor en el portapapeles. En la siguiente imagen, se ilustra una identidad de escritor:

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

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

    Antes de usar el siguiente comando, realiza los siguientes reemplazos:

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

    • ROLE: Es un rol de IAM. Otorga a la identidad de escritor del receptor un rol de IAM según el destino del receptor de registros:

    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 consola de Google Cloud o Google Cloud CLI para otorgar un rol a la cuenta de servicio.

¿Qué sigue?