Configurar etiquetas en métricas basadas en registros

En este documento se describen las etiquetas de métricas basadas en registros y se explica cómo crear y usar etiquetas en métricas de registro.

Si ya conoces las etiquetas, puedes ir directamente a la sección Crear una etiqueta de esta página.

Información general sobre las etiquetas de las métricas basadas en registros

Las etiquetas permiten que las métricas basadas en registros contengan varias series temporales, una por cada combinación de valores de etiqueta. Todas las métricas basadas en registros incluyen algunas etiquetas predeterminadas.

Puede crear etiquetas definidas por el usuario adicionales en métricas de tipo contador y de tipo distribución especificando expresiones de extractor. Una expresión de extractor indica a Cloud Logging cómo extraer el valor de la etiqueta de las entradas de registro. Puedes especificar el valor de la etiqueta de una de las siguientes formas:

• Todo el contenido de un campo con nombre del objeto LogEntry.
• Parte de un campo con nombre que coincide con una expresión regular (regexp).

Puedes extraer etiquetas de los campos integrados de LogEntry, como httpRequest.status, o de uno de los campos de carga útil textPayload, jsonPayload o protoPayload. Sin embargo, no puedes extraer el ID de un grupo de errores del campo errorGroups.

Para obtener información sobre las expresiones regulares, consulta la sintaxis RE2.

No incluyas información sensible en la expresión del extractor ni extraigas datos sensibles en etiquetas. Se tratan como datos del servicio.

Limitaciones de las etiquetas definidas por el usuario

Las etiquetas definidas por el usuario están sujetas a las siguientes limitaciones:

• Puede crear hasta 10 etiquetas definidas por el usuario por métrica.

• Una vez que hayas creado una etiqueta, no podrás eliminarla.

  • Puedes modificar la expresión del extractor y la descripción de la etiqueta que ya hayas creado.

  • No puedes cambiar el nombre ni el tipo de valor de una etiqueta que ya hayas creado.

• Solo se conservan los primeros 1024 caracteres de un valor de etiqueta.

• Cada métrica basada en registros tiene un límite de unas 30.000 series temporales activas, que depende del número de valores posibles de cada etiqueta, incluidas las etiquetas predeterminadas.

  Por ejemplo, si las entradas de registro proceden de 100 recursos, como instancias de VM, y define una etiqueta con 20 valores posibles,puede tener hasta 2000 series temporales para su métrica.

Si tienes demasiadas series temporales o demasiados puntos de datos, tus costes aumentarán y tu actividad podría limitarse. Para obtener más información sobre el coste de las métricas basadas en registros, consulta Métricas facturables. Para obtener información sobre los límites que se aplican a las métricas basadas en registros, consulta Cuotas y límites: métricas basadas en registros y Solucionar problemas con métricas basadas en registros.

Etiquetas predeterminadas

La mayoría de las métricas basadas en registros incluyen algunas etiquetas predefinidas:

• Etiquetas de recursos: todas las métricas usan un objeto de recurso monitorizado para identificar la fuente de los datos de series temporales. Cada tipo de recurso incluye un nombre de tipo y una o varias etiquetas. Algunos ejemplos de tipos de recursos son las instancias de VM, las bases de datos de Cloud SQL y los balanceadores de carga.

  El recurso y sus etiquetas se muestran por separado de otras etiquetas de métricas en Cloud Monitoring, pero tienen el mismo efecto: crean series temporales adicionales en la métrica. Para obtener más información, consulta Métricas, series temporales y recursos.

• log: esta etiqueta contiene el valor de la parte LOG_ID del campo logName de las entradas de registro.

• severity: esta etiqueta contiene el valor del campo severity de las entradas de registro. La etiqueta de gravedad se proporciona de forma predeterminada solo en las métricas basadas en registros del sistema.

Ver etiquetas con el explorador de métricas

Para ver las etiquetas de una serie temporal generada para una métrica basada en registros, haz lo siguiente:

1. En la Google Cloud consola, ve a la página Métricas basadas en registros:

   Ve a Métricas basadas en registros.

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

2. Busca la métrica que quieras ver y, a continuación, selecciona Ver en Explorador de métricas en el menú more_vert Más de la métrica.

   Antes de continuar, espera a que el gráfico muestre datos, lo que puede tardar varios minutos si has creado una métrica basada en registros.

3. Para ver las etiquetas disponibles, despliega el campo Filtrar. Puede que veas etiquetas de recursos y etiquetas de métricas. La lista de etiquetas es específica del tipo de recurso y del tipo de métrica. Por ejemplo:

   • El tipo de recurso gce_instance tiene tres etiquetas de recurso: project_id, instance_id y zone.

   • El tipo de métrica logging/log_entry_count tiene dos etiquetas de métrica: log y severity. Las etiquetas definidas por el usuario también aparecen en esta sección.

4. Para verificar que una etiqueta definida por el usuario extrae los datos correctos de las entradas de registro, haga lo siguiente:

   1. Cambia el elemento Agregación a Sin agregar.

   2. En el gráfico, selecciona Tabla o Ambos.

   3. En la barra de herramientas, selecciona view_column Menú de visualización de columnas y, a continuación, elige las etiquetas. En este menú se muestran todas las etiquetas de las que hay datos.

      Si no ves una etiqueta que has creado, comprueba el nombre del campo y la expresión del extractor.

Crear una etiqueta

Las etiquetas definidas por el usuario se crean al crear la métrica. Tanto las métricas de contador como las de distribución pueden tener etiquetas. No se pueden añadir etiquetas a las métricas basadas en registros del sistema.

Para crear una etiqueta, especifica el campo de la entrada de registro y, a continuación, defines una expresión que extrae un valor del campo especificado.

gcloud logging metrics create METRIC_NAME --config-from-file FILENAME

{
  ...
  metricDescriptor: {
      labels: [
        { key: LABEL_NAME, valueType: LABEL_TYPE,
          description: LABEL_DESCRIPTION },
        ...
      ]
  },
  labelExtractors: {
    LABEL_NAME: EXTRACTOR_EXPRESSION,
    ...
  },
}

{
  ...
  metricDescriptor: {
      labels: [
        { key: "label_name_a", valueType: STRING },
        { key: "label_name_b", valueType: INT64 },
      ]
  },
  labelExtractors: {
    "label_name_a":
      "REGEXP_EXTRACT(jsonPayload.field_a, \"before ([a-zA-Z ]+) after\")",
    "label_name_b": "EXTRACT(jsonPayload.field_b)",
  },
}

Ejemplos

En esta sección se ofrecen algunos ejemplos que pueden ayudarte a empezar a crear etiquetas en tus métricas basadas en registros definidas por el usuario. Después de crear una etiqueta, te recomendamos que verifiques las etiquetas con el explorador de métricas.

Notas:

• Debes usar un grupo de captura cuando especifiques una expresión de extractor.
• Si no especifica una expresión de extractor, se extraerá todo el valor del campo.

• Asegúrese de que el conjunto de valores posibles de cualquier etiqueta esté restringido. Es preferible usar un pequeño conjunto de valores discretos (como "rojo", "verde" y "azul"). Por ejemplo, si extrae los valores RGB de 8 bits de una etiqueta de color, puede obtener más de 16 millones de valores diferentes. Esto significa que podrías tener más de 16 millones de series temporales.

  No extraiga valores de alta resolución, como marcas de tiempo, ningún tipo de identificador único, IDs de usuario, direcciones IP, URLs sin parámetros, etc.

Extraer el código de estado de un registro de auditoría

Si un campo no contiene ningún carácter especial, puede usar el nombre del campo en la etiqueta de la métrica basada en registros.

Por ejemplo, en los registros de auditoría, el campo protoPayload sigue la estructura AuditLog. Por lo tanto, para extraer el campo status de un registro de auditoría, puedes asignar el nombre de campo protoPayload.status.code y dejar vacía la expresión del extractor.

Si solo quiere extraer el primer dígito del código de error, puede definir la expresión del extractor como (\d)\d\d.

Extraer el valor de un campo con caracteres especiales

Si un campo de una entrada de registro contiene caracteres especiales, encierra el campo entre comillas dobles.

Por ejemplo, para extraer todo el valor de la etiqueta k8s-pod/k8s-app, defina el nombre del campo como labels."k8s-pod/k8s-app" y deje la expresión vacía.

Extraer un valor de una carga útil de texto

Supongamos que tienes una entrada de registro con el siguiente formato:

textPayload: "unfinished_task_instance_count.py:61 Unfinished task instance count metric value 0 for state: deferred"

Para extraer el valor del estado, como deferred, de las entradas de registro con el formato anterior, puedes hacer algo parecido a lo siguiente:

• Nombre del campo: textPayload
• Expresión del extractor: ^unfinished.*state: ([a-z]+)

Extraer valores de un campo repetido

Una entrada de registro puede contener un campo con campos repetidos. En JSON, estos campos se muestran entre corchetes ([]). Desde el punto de vista de las etiquetas, considera los campos repetidos como un conjunto y el extractor de etiquetas como un iterador. Usted proporciona los criterios de la coincidencia al definir la etiqueta y el extractor itera sobre el conjunto hasta que se encuentra una coincidencia. Siempre se devuelve la primera coincidencia, aunque varios miembros del conjunto cumplan los criterios.

Decides crear una métrica basada en registros que cuente los registros de auditoría. Antes de configurar la etiqueta, revisas varios registros de auditoría y observas que el formato de protoPayload se ajusta a la estructura AuditLog. A continuación se muestra una parte de una entrada de registro de auditoría.

{
  ...
  protoPayload: {
    @type: "type.googleapis.com/google.cloud.audit.AuditLog"
    authenticationInfo: {1}
    authorizationInfo: [
      0: {
        granted: true
        permission: "io.k8s.coordination.v1.leases.get"
        resource: "coordination.k8s.io/v1/namespaces/kube-system/leases/maintenance-controller"
      }
    ]
    requestMetadata: {2}
    status: {1}
    ...
  }
  ...
}

Decides crear una etiqueta para tu métrica basada en registros que almacene información del campo permission. Verás que estos campos tienen el formato io.k8s.xyz, donde xyz es una cadena que proporciona más detalles sobre la solicitud. Esta cadena puede tener un valor como get o un formato más complejo, como io.k8s.coordination.v1.leases.get.

Para minimizar el número de valores de etiqueta, no debe extraer la información detallada. Solo quieres almacenar valores como get o coordination en la etiqueta. Además, decides que no quieres incluir el prefijo común, io.k8s., en el valor de la etiqueta.

A continuación, configura la etiqueta. Como el campo permission es un campo repetido y su elemento superior es el campo authorizationInfo, el nombre del campo se define de la siguiente manera:

protoPayload.authorizationInfo.permission

Por último, crea la siguiente expresión regular:

io.k8s.([a-z]+).*