Administra alertas basadas en registros

Puedes usar alertas basadas en registros para recibir notificaciones cada vez que aparezca un mensaje específico en tus registros incluidos. En este documento, se describe cómo hacer lo siguiente:

  • Crea y prueba una alerta basada en registros.
  • Edita una alerta basada en registros.
  • Borra una alerta basada en registros.

Antes de comenzar

Revisa la Comparación de alertas a fin de determinar si las alertas basadas en registros son una buena opción para los datos en tus registros. Por ejemplo:

  • Las alertas basadas en registros no funcionan en registros excluidos.

  • No puedes usar alertas basadas en registros para derivar recuentos de tus registros. Para derivar los recuentos, debe usar las métricas basadas en registros.

Para crear y administrar alertas basadas en registros, debes tener la autorización descrita en Permisos de alertas basadas en registros.

Crear una alerta basada en registros (Explorador de registros)

Puedes crear alertas basadas en registros desde la página Explorador de registros en Google Cloud Console o mediante la API de Cloud Monitoring. En esta sección, se describe cómo crear alertas basadas en registros mediante el Explorador de registros. Si deseas crear alertas basadas en registros mediante la API de Cloud Monitoring, consulta Crea una alerta basada en registros (API de Monitoring).

La interfaz del Explorador de registros para crear y editar alertas basadas en registros te guía a través de los siguientes pasos:

  • Proporciona un nombre y una descripción para la alerta.
  • Elige los registros para los que quieres recibir notificaciones.
  • Establece el tiempo entre notificaciones.
  • Especifica a quién notificar.

Por ejemplo, supongamos que tienes una aplicación que escribe una entrada de registro syslog con gravedad NOTICE cuando la aplicación cambia una dirección de red. En las entradas de registro de los cambios de dirección de red, se incluye una carga útil JSON similar a la siguiente:

"jsonPayload": {
  "type": "Configuration change",
  "action": "Set network address",
  "result": "IP_ADDRESS",
}

Deseas crear una alerta basada en registros que te notifique cuando aparezca una dirección IPv4 no válida en el campo jsonPayload.result de entradas de registro en syslog con gravedad NOTICE.

Para crear la alerta basada en registros, haz lo siguiente:

  1. En Cloud Console, selecciona Logging y, luego, Explorador de registros:

    Ir al Explorador de registros.

  2. Usa el panel Consulta para compilar una consulta que coincida con el mensaje que deseas usar en tu alerta basada en registros.

    Por ejemplo, para encontrar entradas de registro con un nivel de gravedad NOTICE en el registro syslog que tengan direcciones IP no válidas en la carga útil JSON, puedes usar la siguiente consulta:

    log_id("syslog")
    severity = "NOTICE"
    jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
    

    Usa Ejecutar consulta en el panel Resultados de la consulta para validar la consulta.

  3. En el panel Resultados de la consulta, busca el menú Acciones y selecciona Crear alerta de registro.

  4. En el panel Detalles de la alerta, asigne un nombre y una descripción a la alerta:

    1. Ingrese un nombre para su alerta en el campo Nombre de la alerta. Por ejemplo: “Dirección de red: valor de IPv4 no válido”.

    2. Ingresa una descripción de esta alerta. También puedes incluir información que pueda ayudar al destinatario de una notificación a diagnosticar el problema.

      Para obtener información sobre cómo puedes formatear y adaptar el contenido de este campo, consulta Usa Markdown y variables en plantillas de documentación.

  5. Haz clic en Siguiente para avanzar al paso siguiente.

  6. En el panel Elegir registros para incluir en el alerta, haz clic en Obtener vista previa de los registros para verificar la consulta y los resultados.

    Recomendamos compilar la consulta en el panel Consulta del Explorador de registros. La consulta que compilaste en el panel Consulta también se muestra en este panel, por ejemplo:

    log_id("syslog")
    severity = "NOTICE"
    jsonPayload.result !~ "^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\.|$)){4}$"
    

    Puedes editar la consulta en este panel, si es necesario. Si editas la consulta, haz clic en Obtener vista previa de los registros para verificar los resultados.

  7. Haz clic en Siguiente para avanzar al paso siguiente.

  8. Selecciona el tiempo mínimo entre notificaciones. Este valor te permite controlar la cantidad de notificaciones que recibes de esta alerta si se activa varias veces. En este ejemplo, selecciona 5 min en las opciones.

  9. Haz clic en Siguiente para avanzar al paso siguiente.

  10. Selecciona uno o más canales de notificaciones para la alerta. Para este ejemplo, selecciona un canal de notificaciones por correo electrónico.

    Si ya tienes un canal de notificaciones por correo electrónico configurado, puedes seleccionarlo en la lista. De lo contrario, haz clic en Administrar canales de notificaciones y agrega un canal de correo electrónico. Para obtener información sobre cómo crear canales de notificación, consulta Administra canales de notificación.

  11. Haz clic en Guardar.

Su alerta basada en registros ya está lista para probar.

Prueba el ejemplo de alerta basada en registros

Para probar la alerta que creaste, puedes escribir de forma manual una entrada de registro que coincida con la consulta mediante los pasos siguientes:

  1. Ve a la página de referencia logEntries.write o haz clic en el siguiente botón:

    Ir a logEntries.write

  2. En el panel Try this API, haz lo siguiente:

    1. En la siguiente entrada de registro, cambia la variable PROJECT_ID por el ID del proyecto:

      {
        "entries": [
        {
          "logName": "projects/PROJECT_ID/logs/syslog",
          "jsonPayload": {
            "type": "Configuration change",
            "action": "Set network address",
            "result": "999.027.405.1",
          },
          "severity": "NOTICE",
          "resource": {
            "type": "generic_task",
            "labels" : {
              "project_id": "PROJECT_ID",
              "location": "us-east1",
              "namespace": "fake-task",
              "job": "write-log-entry",
              "task_id": "1",
            },
          },
        ],
      }
      
    2. Copia la entrada de registro y reemplaza el contenido del campo Cuerpo de la solicitud en el Explorador de API con la entrada de registro copiada.

    3. Haz clic en Ejecutar.

      Si la llamada a logEntries.write se ejecuta correctamente, obtendrás un código de respuesta HTTP 200 y un cuerpo de respuesta vacío, {}. Para obtener más información sobre el Explorador de API, consulta Usa el Explorador de API en la documentación de Monitoring. el Explorador de API funciona de la misma manera que la API de Logging.

La entrada de registro coincide con el filtro especificado para la alerta de las siguientes maneras:

  • El valor logName especifica el registro syslog en tu proyecto de Cloud.
  • El valor severity de esta entrada de registro es NOTICE.
  • El valor jsonPayload.result no es una dirección IPv4 válida.

Después de escribir la entrada de registro, ocurre la siguiente secuencia:

  • La nueva entrada de registro aparecerá en el Explorador de registros y activará la alerta.
  • Se abre un incidente en Cloud Monitoring.
  • Recibes una notificación sobre el incidente. Si configuraste un canal de notificaciones por correo electrónico, la notificación se verá como la siguiente captura de pantalla:

    La alerta de ejemplo basada en registros genera una notificación por correo electrónico.

Puedes hacer clic en Ver incidente en el correo electrónico para ver el incidente en Cloud Monitoring. Si deseas obtener más información sobre los incidentes, consulta Administra incidentes para alertas basadas en registros.

Otros casos: Alertas de registros de auditoría

El ejemplo de Crea una alerta basada en registros es artificial. Por lo general, no se crea una alerta y, luego, se escribe manualmente una entrada de registro para probarla. En la mayoría de los casos, las aplicaciones o cualquier otro servicio escriben entradas de registro. Pero la única diferencia en la creación de la alerta basada en registros es la consulta que usas para seleccionar las entradas de registro.

En las siguientes secciones, se describen situaciones realistas para las alertas basadas en registros en función del contenido de los registros de auditoría y se muestra cómo crear consultas para aislar las entradas de registro deseadas en los registros de auditoría. De lo contrario, el procedimiento para crear las alertas basadas en registros es el mismo que se muestra en Crea una alerta basada en registros.

Alertas de acceso humano a secretos

Supongamos que tu proyecto almacena secretos en Secret Manager y que algunos de estos solo se diseñaron para que los usen las cuentas de servicio. Excepto en circunstancias inusuales, ningún usuario humano puede acceder a estos secretos.

Si habilitaste el registro de auditoría para Secret Manager, cada intento exitoso de acceder a un secreto crea una entrada de registro de auditoría. Cada entrada incluye el nombre del secreto y la identidad del emisor.

Puedes crear una alerta basada en registros que te notifique si un usuario humano accede a un secreto.

A continuación, se muestra un extracto de una entrada de registro de auditoría escrita por Secret Manager. El extracto muestra los campos que son útiles para crear la consulta de una alerta basada en registros:

{
  "protoPayload": {
    "@type": "type.googleapis.com/google.cloud.audit.AuditLog",
    "serviceName": "secretmanager.googleapis.com",
    "methodName": "google.cloud.secretmanager.v1.SecretManagerService.AccessSecretVersion",
    "authenticationInfo": {
      "principalEmail": "my-svc-account@PROJECT_ID.iam.gserviceaccount.com",
      "serviceAccountDelegationInfo": [],
      "principalSubject": "serviceAccount:my-svc-account@PROJECT_ID.iam.gserviceaccount.com"
    },
    ...
  },
  ...
}

Los siguientes subcampos de protoPayload son de particular interés:

  • @type: Indica que esta entrada de registro es una entrada de registro de auditoría.
  • serviceName: Registra el servicio que escribió la entrada de registro de auditoría. Usa este campo para identificar las entradas escritas con Secret Manager.
  • methodName: Identifica el método para el que se escribió esta entrada de registro de auditoría. Usa este campo para identificar la acción que creó esta entrada. En este ejemplo, es el método AccessSecretVersion.
  • authenticationInfo.principalEmail: Registra la cuenta que invocó el método en el campo methodName. El valor esperado para este campo es una cuenta de servicio que termina con gserviceaccount.com.

Si deseas encontrar entradas de registro para el acceso secreto de un usuario humano, busca entradas de registro de auditoría escritas por Secret Manager. Debes buscar las entradas de registro en las que un principal que no termina con gserviceaccount.com invocó el método AccessSecretVersion. En la siguiente consulta, se aíslan estas entradas de registro:

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "secretmanager.googleapis.com"
protoPayload.methodName =~ "AccessSecretVersion$"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

A fin de crear una alerta basada en registros para el acceso humano de los secretos, usa esta consulta en el panel Choose logs to include in the alert.

Alertas sobre eventos de desencriptación

El análisis del ejemplo anterior se puede adaptar a otros servicios. Por ejemplo, si usas Cloud Key Management Service para encriptar y desencriptar datos sensibles, puedes usar los registros de auditoría generados por Cloud KMS. determinar si un usuario humano desencripta un valor

A fin de encontrar entradas de registro para la desencriptación que realice un usuario humano, busca las entradas de registro de auditoría escritas por Cloud KMS. Debes encontrar las entradas de registro en las que un principal que no termina con gserviceaccount.com, que indica una cuenta de servicio, invocó el método Decrypt. En la siguiente consulta, se aíslan estas entradas de registro:

protoPayload.@type = "type.googleapis.com/google.cloud.audit.AuditLog"
protoPayload.serviceName = "cloudkms.googleapis.com"
protoPayload.methodName = "Decrypt"
protoPayload.authenticationInfo.principalEmail !~ "gserviceaccount.com$"

A fin de crear una alerta basada en registros para la desencriptación que realice un usuario humano, usa esta consulta en el panel Choose logs to include in the alert.

Administra alertas basadas en registros en Monitoring

Puedes ver, editar y borrar alertas basadas en registros en Cloud Monitoring. Ten en cuenta que no puedes crear alertas basadas en registros en Google Cloud Console para Monitoring. Las alertas basadas en registros se deben crear mediante el Explorador de registros o la API de Monitoring.

Para ver una lista de todas las políticas de alertas en el proyecto de Google Cloud, realiza una de las siguientes acciones:

  • Para navegar desde Logging, sigue estos pasos:

    1. En Cloud Console, selecciona Logging y, luego, Explorador de registros:

      Ir al Explorador de registros.

    2. En el panel Resultados de la consulta, busca el menú Acciones y selecciona Administrar alertas.

  • Para navegar desde Monitoring, haz lo siguiente:

    1. En Cloud Console, selecciona Monitoring:

      Ir a Monitoring

    2. Selecciona Alertas.

    3. En el panel Políticas (Policies), se muestra una lista parcial de las políticas. Para ver todas las políticas y habilitar el filtrado, haz clic en Ver todas las políticas.

Ambas acciones te llevan a la página Políticas de Monitoring, que enumera todas las políticas de alertas en el proyecto de Cloud.

A fin de restringir las políticas de alertas que se enumeran, agrega filtros. Cada filtro se compone de un nombre y un valor. Puedes establecer que el valor sea una coincidencia exacta para un nombre de política o una coincidencia parcial. Las coincidencias no distinguen mayúsculas de minúsculas. Si tienes varios filtros, estos se unen de manera automática con un AND lógico, a menos que insertes un filtro OR. En la siguiente captura de pantalla, se enumeran las políticas de alertas habilitadas que se crearon después del 1 de enero de 2021:

Lista de políticas de alertas habilitadas creadas después del 1 de enero de 2021.

Desde la página Políticas, puedes editar, borrar, copiar, habilitar o inhabilitar una política de alertas:

  • Para editar o copiar una política, haz clic en Más opciones y selecciona la opción deseada. Editar y copiar una política es similar al procedimiento descrito en Crea una alerta basada en registros . Puedes cambiar y, en algunos casos, borrar los valores de los campos. Cuando termines, haz clic en Guardar.

    También puedes editar una política de alertas basada en registros si haces clic en su nombre en la lista de políticas.

  • Para borrar una política, haz clic en Más opciones y selecciona Borrar. En el diálogo de confirmación, selecciona Borrar.

  • Para habilitar o inhabilitar la política de alertas, haz clic en el botón de activación ubicado debajo del encabezado Habilitado.

Cree una alerta basada en registros (API de Monitoring)

Puedes crear alertas basadas en registros mediante la API de Cloud Monitoring. Proporciona la misma información a la API de Monitoring que proporcionas cuando usas el Explorador de registros en Google Cloud Console:

  • Un nombre y una descripción para la alerta.
  • Los registros para los que quieres recibir notificaciones.
  • El tiempo que transcurre entre las notificaciones.
  • A quién notificar.

Para crear políticas de alertas mediante la API de Monitoring, crea un objeto AlertPolicy y envíalo al método alertPolicies.create.

Antes de poder usar la API de Monitoring, debes habilitar la API y tener autorización para usarla. Para obtener más información, consulta la siguiente documentación:

Estructura de las políticas de alertas

La API de Cloud Monitoring representa una política de alertas mediante la estructura AlertPolicy. La estructura AlertPolicy tiene varias estructuras incorporadas, incluida una descripción de la condición que activa la alerta. Las políticas de alertas basadas en registros difieren de las políticas de alertas basadas en métricas de las siguientes maneras:

  • Para describir la condición, usa el tipo de condición LogMatch. Las políticas de alertas basadas en métricas usan diferentes tipos de condiciones.
  • Una política de alertas basada en registros puede tener solo una condición.
  • Para especificar el tiempo entre notificaciones, incluye una estructura AlertStrategy. Las políticas de alertas basadas en métricas no incluyen un tiempo entre las notificaciones.

En Administra las políticas de alertas mediante la API, se describe cómo crear, enumerar, editar y borrar la política de alertas mediante la API de Monitoring. En esta sección, se describe cómo crear una política de alertas basada en registros. Estas políticas difieren de las políticas de alertas basadas en métricas en el tipo de condición que usas. Para las alertas basadas en registros, el tipo de condición es LogMatch.. Cuando usas la API de Monitoring para administrar las políticas de alertas basadas en registros, no hay diferencias en la forma en que enumeras, editas o borras las políticas.

Diseña la política de alertas

En Crea una alerta basada en registros (Explorador de registros), crea una alerta basada en registros que te notifique cuando una dirección IPv4 no válida aparezca en el campo jsonPayload.result de entradas de registro en syslog con gravedad NOTICE.

Para crear la misma alerta basada en registros mediante la API de Monitoring, crea un objeto AlertPolicy que se vea como la siguiente estructura de JSON:

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "A network address has been set to an invalid value for IPv4.",
    "mimeType": "text/markdown"
  },

  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\") severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",

  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    }
  },

  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

Este código JSON especifica la misma información que especificas cuando creas una alerta basada en registros mediante el Explorador de registros. En las siguientes secciones, se mapea el contenido de esta estructura AlertPolicy a los pasos que sigues cuando usas el Explorador de registros para crear una alerta basada en registros. El valor del campo conditionMatchedLog es una estructura LogMatch.

Proporciona un nombre y una descripción

Una política de alertas tiene un nombre visible y documentación asociada que se proporciona con notificaciones para ayudar a los encargados de ofrecer respuestas. En el Explorador de registros, estos se llaman Nombre de alerta y Descripción de alerta. Estos valores se representan en una estructura AlertPolicy de la siguiente manera:

{
  "displayName": "Network address: invalid IPv4 value (API)",
  "documentation": {
    "content": "A network address has been set to an invalid value for IPv4.",
    "mimeType": "text/markdown"
  },
  ...
}

El valor de displayName en este ejemplo agrega “(API)” al nombre proporcionado al Explorador de registros para que puedas distinguir entre las dos políticas cuando visualizas la lista de políticas en Cloud Console. En la página Políticas de Monitoring, se enumeran las políticas por nombre visible y se indica si la política se basa en métricas o registros. Para obtener más información, consulta Administra alertas basadas en registros en Monitoring.

El campo documentation incluye, en el subcampo content, la descripción que puedes proporcionar cuando usas el Explorador de registros. El segundo subcampo, mimeType, es obligatorio si especificas un valor para el campo documentation. El único valor válido es "text/markdown".

Elige los registros para los que quieres recibir notificaciones

Una política de alertas basada en registros tiene una sola condición. En el Explorador de registros, debes especificar la condición cuando proporciones una consulta en el campo Definir entradas de registro para alertar. Estos valores se representan en una estructura AlertPolicy de la siguiente manera:

{ ...
  "conditions": [
    {
      "displayName": "Log match condition: invalid IP addr",
      "conditionMatchedLog": {
        "filter": "log_id(\"syslog\" severity = \"NOTICE\" jsonPayload.result !~ \"^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)(\\.|$)){4}$\"",
      },
    }
  ],
  "combiner": "OR",
  ...
}

El campo conditions toma una lista de estructuras Condition, aunque una política de alertas basada en registros debe tener solo una condición. Cada Condition tiene un nombre visible y una descripción de la condición.

  • El valor del campo displayName es una descripción breve de la condición. Cuando usas el Explorador de registros para crear alertas basadas en registros, el nombre visible siempre es “Condición de coincidencia de registros”. Cuando usas la API de Monitoring, puedes proporcionar un nombre visible más preciso. Es obligatorio ingresar un valor.

  • El valor del campo conditionMatchedLog es una estructura LogMatch y el valor del campo filter es la consulta que especificas en el Explorador de registros. Debido a que esta consulta se proporciona como el valor de un campo JSON, toda la consulta aparece entre comillas, y cualquier comilla en la consulta debe escaparse con el carácter \ (barra invertida).

El valor del campo combiner especifica cómo combinar los resultados de varias condiciones en las políticas de alertas basadas en métricas. Solo puedes usar una condición en las alertas basadas en registros y debes especificar el campo combiner con el valor "OR". No puedes crear alertas basadas en registros con varias condiciones.

Establece el tiempo entre notificaciones

Una política de alertas para una alerta basada en registros especifica el tiempo mínimo entre notificaciones. En el Explorador de registros, selecciona un valor del menú Tiempo entre notificaciones. Representas este valor de formaAlertPolicy mediante la especificación de un valor, en segundos, para elperiod campo de unNotificationRateLimit estructura incorporada en un elementoAlertStrategy:

{ ...
  "alertStrategy": {
    "notificationRateLimit": {
      "period": "300s"
    }
  },
  ...
}

El valor del campo period en este ejemplo, 300s, es equivalente a cinco minutos.

Especifica a quién notificar

Una política de alertas puede incluir una lista de canales de notificaciones. En el Explorador de registros, selecciona canales de un menú. Estos valores se representan en una estructura AlertPolicy mediante una lista de uno o más nombres de recursos para objetos NotificationChannel configurados:

{ ...
  "notificationChannels": [
    "projects/PROJECT_ID/notificationChannels/CHANNEL_ID"
  ]
}

Cuando creas un canal de notificaciones, se le asigna un nombre de recurso. Para obtener información sobre cómo recuperar la lista de canales de notificaciones disponibles, que incluye sus nombres de recursos, consulta Recupera canales en la documentación de Monitoring. No puedes obtener los ID de los canales mediante Cloud Console.

Envía tu política de alertas a la API de Cloud Monitoring

Para crear una política de alertas con la API de Monitoring, crea un objeto AlertPolicy y envíalo al método alertPolicies.create. Puedes invocar el alertPolicies.create mediante la herramienta de línea de comandos de gcloud y una llamada a la API de Monitoring.

También puedes crear alertas basadas en registros mediante las bibliotecas cliente de C#, Go, Java, Python y Ruby. Es posible que también puedas usar otras bibliotecas cliente. la biblioteca de tu lenguaje debe incluir el tipo de condición LogMatch.

Para crear una política de alertas con la herramienta de gcloud, haz lo siguiente:

  1. Coloca la representación JSON de tu política de alertas en un archivo de texto, por ejemplo, en un archivo llamado alert-invalid-ip.json.

  2. Pasa este archivo JSON a la herramienta de gcloud mediante el siguiente comando:

    gcloud alpha monitoring policies create --policy-from-file="alert-invalid-ip.json"
    
  3. Si funciona, este comando mostrará el nombre de la política nueva, por ejemplo:

    Created alert policy [projects/PROJECT_ID/alertPolicies/POLICY_ID].
    

Para crear una política de alertas mediante una llamada directa a alertPolicies.create, puedes usar el Explorador de API de la siguiente manera:

  1. Ve a la página de referencia de alertPolicies.create.

  2. En el panel Try this API, haz lo siguiente:

    1. En el campo name, ingresa el siguiente valor:

      projects/PROJECT_ID
      
    2. Copia la representación JSON de tu política de alertas y reemplaza el contenido del campo Cuerpo de la solicitud en el Explorador de API con la política de alertas copiadas.

    3. Haz clic en Ejecutar.

      Si la llamada a alertPolicies.create se ejecuta correctamente, obtendrás un código de respuesta HTTP 200 y un cuerpo de respuesta vacío, {}. Para obtener más información sobre el Explorador de API, consulta Usa el Explorador de API en la documentación de Monitoring.

Para obtener más información sobre cómo crear políticas de alertas con la API de Monitoring, consulta Crea políticas. En los ejemplos de esa página, se usan tipos de condiciones para las políticas de alertas basadas en métricas, pero los principios son los mismos.

Prueba la política de alertas

Para probar la política de alertas nueva, puedes usar el mismo procedimiento que se describe en Prueba la alerta basada en registros de ejemplo.