Configura etiquetas en las métricas basadas en registros

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

Si ya conoces las etiquetas, puedes ir directamente a Crea una etiqueta en esta página.

Descripción general de las etiquetas para las métricas basadas en registros

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

Puedes crear etiquetas adicionales definidas por el usuario en las métricas de contador y de distribución mediante la especificación de las expresiones de extractor. Una expresión de extractor le indica a Cloud Logging cómo extraer el valor de la etiqueta de las entradas de registro. Puedes especificar el valor de la etiqueta como cualquiera de las siguientes opciones:

• Todo el contenido de un campo con nombre en el objeto LogEntry
• Una 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 más información sobre las expresiones regulares, consulta Sintaxis RE2.

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

Limitaciones de las etiquetas definidas por el usuario

Las siguientes limitaciones se aplican a las etiquetas definidas por el usuario:

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

• Después de crear una etiqueta, no podrás borrarla.

  • Puedes modificar la expresión de extractor y la descripción de la etiqueta que ya creaste.

  • No puedes cambiar el nombre o el tipo de valor de una etiqueta que ya creaste.

• Solo se conservan los primeros 1,024 caracteres del valor de una etiqueta.

• Cada métrica basada en registros se limita a casi 30,000 series temporales activas, que depende de la cantidad de valores posibles para cada etiqueta, incluidas las etiquetas predeterminadas.

  Por ejemplo, si tus entradas de registro provienen de 100 recursos, como las instancias de VM, y defines una etiqueta con 20 valores posibles, puedes tener hasta 2,000 series temporales para tu métrica.

Si tienes demasiadas series temporales o demasiados datos, tus costos aumentarán y puede que tu actividad se limite. Para obtener más información sobre el costo de las métricas basadas en registros, consulta Precios de Cloud Monitoring: Métricas cobrables. 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 Soluciona problemas relacionados con las 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 supervisado para identificar la fuente de los datos de series temporales. Cada tipo de recurso incluye un nombre de tipo y una o más etiquetas. Entre los ejemplos de tipos de recursos, se incluyen instancias de VM, bases de datos de Cloud SQL y balanceadores de cargas.

  El recurso y sus etiquetas se enumeran por separado desde 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 en las entradas de registro.

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

Visualiza etiquetas con el Explorador de métricas

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

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

   Ir a Métricas basadas en registros

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

2. Busca la métrica que deseas ver y, luego, selecciona Ver en el 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 creaste una métrica basada en registros.

3. Para ver las etiquetas disponibles, expande el campo Filtro. Es posible 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 recursos: project_id, instance_id y zone.

   • El tipo de métrica logging/log_entry_count tiene dos etiquetas de métrica: log y severity. Tus 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 tus entradas de registro, haz 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, luego, selecciona tus etiquetas. En este menú, se muestran todas las etiquetas para las que hay datos.

      Si no ves una etiqueta que creaste, verifica el nombre del campo y la expresión del extractor.

Crea una etiqueta

Cuando creas la métrica, creas etiquetas definidas por el usuario. Las métricas de contadores y de distribución pueden tener etiquetas. No puedes agregar etiquetas a las métricas basadas en registros del sistema.

Para crear una etiqueta, debes especificar el campo en la entrada de registro y, luego, definir una expresión que extraiga 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 proporcionan algunos ejemplos que pueden ayudarte a comenzar 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.

Sugerencias:

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

• Asegúrate de que el conjunto de valores posibles para cualquier etiqueta esté restringido. Se prefiere un conjunto pequeño de valores discretos (como “rojo”, “verde” y “azul”). Por ejemplo, si extraes los valores RGB de 8 bits para una etiqueta de color, puedes tener más de 16 millones de valores diferentes. Esto significa que podrías tener más de 16 millones de series temporales.

  No extraigas valores de alta resolución, como marcas de tiempo, identificadores únicos de cualquier tipo, IDs de usuario, direcciones IP, URLs sin parámetros, etcétera.

Cómo extraer el código de estado de un registro de auditoría

Si un campo no contiene caracteres especiales, puedes usar el nombre del campo en la etiqueta de la métrica basada en registros.

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

Si solo deseas extraer el primer dígito del código de error, puedes establecer la expresión del extractor en (\d)\d\d.

Cómo extraer valores 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, establece el nombre del campo en labels."k8s-pod/k8s-app" y deja la expresión vacía.

Cómo extraer un valor de una carga útil de texto

Considera una entrada de registro que tenga 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 como lo siguiente:

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

Cómo extraer un valor de un campo repetido

Una entrada de registro puede contener un campo con campos repetidos. En JSON, estos campos se muestran con corchetes ([]). Desde la perspectiva de las etiquetas, considera los campos repetidos como un conjunto y el extractor de etiquetas como un iterador. Cuando defines la etiqueta, proporcionas los criterios para la coincidencia, y el extractor itera sobre el conjunto hasta que se encuentra una coincidencia. Siempre se devuelve la primera coincidencia, incluso cuando varios miembros del conjunto cumplen con los criterios.

Decides crear una métrica basada en registros que cuente los registros de auditoría. Antes de configurar tu etiqueta, revisas varios registros de auditoría y observas que el formato de protoPayload se ajusta a la estructura de AuditLog. En la siguiente ilustració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. Observa que estos campos tienen el formato io.k8s.xyz, en el que 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 la cantidad de valores de etiquetas, no debes extraer la información detallada. Solo deseas 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. Dado que el campo permission es un campo repetido, con el campo authorizationInfo como principal, debes establecer el nombre del campo de la siguiente manera:

protoPayload.authorizationInfo.permission

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

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