Configura etiquetas en métricas basadas en registros

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

Si estás familiarizado con las etiquetas, puedes ir directamente a Cómo crear una etiqueta en esta página.

Descripción general de las etiquetas para 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 etiquetas. Todas las métricas basadas en registros vienen con 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.

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

No coloques información sensible en la expresión del extractor ni extraigas datos sensibles en 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 puedes 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 alrededor de 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 de métricas basadas en registros.

Etiquetas predeterminadas

Todas 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, balanceadores de cargas, etcétera.

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 solo se proporciona de forma predeterminada en las métricas basadas en registros del sistema.

Ejemplo: Usa el Explorador de métricas

En la siguiente captura de pantalla del Explorador de métricas, se muestran las etiquetas de una de las métricas basadas en registros del sistema. Obtendrás la lista de etiquetas si haces clic dentro del cuadro de texto Filtro:

Explorador de métricas

En la captura de pantalla, se muestra la siguiente información:

El Explorador de métricas usa series temporales de la métrica logging/log_entry_count y el tipo de recurso gce_instance: instancias de VM de Compute Engine.

Esta métrica también contiene series temporales de otros tipos de recursos, pero el Explorador de métricas te permite ver solo un tipo de recurso a la vez.
El gce_instance tipo de recurso tiene tres etiquetas de recursos: project_id, instance_id y zone.
La métrica tiene dos etiquetas de métrica: log y severity. Tus etiquetas definidas por el usuario también aparecen en esta sección.

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.

Console

Cuando creas una métrica basada en registros, el panel Crear métricas de registros incluye una opción para agregar etiquetas.
Haz clic en Agregar etiqueta.

Sugerencia: Para ver los campos y valores dentro de una entrada de registro, haz lo siguiente:
1. En la sección Selección de filtro, haz clic en Vista previa de registros.
2. En el panel Ver registros, elige una entrada de registro y haz clic en el expander que se encuentra a su lado.
3. Haz clic en Expand nested fields.
Configura los siguientes campos en la sección Etiquetas:
1. Nombre de la etiqueta: Ingresa un nombre para la etiqueta. Por ejemplo, ID
  
  El nombre debe cumplir los siguientes criterios:
  - No debe tener más de 100 caracteres de longitud.
  - Debe coincidir con la expresión regular [a-zA-Z][a-zA-Z0-9_]*.
  - Debe consistir en algo más que la string “log”.
2. Description (Descripción): describe la etiqueta. Intenta ser lo más específico posible sobre el formato de los valores de registros esperados. Por ejemplo, Instance number.
3. Tipo de etiqueta: elige string, booleano o número entero.
4. Field name (Nombre del campo): ingresa el nombre del campo de la entrada de registro que contiene el valor de la etiqueta. Se te sugieren opciones a medida que escribes. En esta muestra, el campo es el siguiente:
```
labels."compute.googleapis.com/resource_id"
```
5. Expresión regular: Si el valor de tu etiqueta consiste en todo el contenido del campo, puedes dejar este campo vacío. De lo contrario, especifica un grupo de captura de expresiones regulares que extraiga el valor de la etiqueta del valor del campo.
  
  Por ejemplo, supongamos que el campo suele contener texto como el siguiente:
```
The instance number is 0123456789; the ID is my-test-instance22
```
  Si deseas que el valor de la etiqueta sea el número de la instancia, existen varias expresiones regulares que extraerán el número correcto. Por ejemplo, en la siguiente expresión, los paréntesis son un grupo de capturas que identifica la parte del texto que se extraerá:
```
The instance number is ([0-9]+); .*
```
  Para obtener más información sobre las expresiones regulares, consulta Sintaxis RE2.
Haz clic en Done (Listo) para crear la etiqueta. Puedes agregar más etiquetas si repites estos pasos.
Para terminar de crear la métrica, haz clic en Crear métrica.

gcloud

Para crear una métrica basada en registros con etiquetas personalizadas, debes crear un archivo que contenga una representación de tu definición de LogMetric en formato JSON o YAML, incluidas las etiquetas personalizadas. Luego, llama al comando create con la marca --config-from-file para crear la métrica y reemplaza FILENAME por el nombre de tu archivo JSON o YAML:

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

Para obtener más información, consulta gcloud logging metrics create

API

Las etiquetas se especifican como parte del objeto LogMetric en el cuerpo de la solicitud de llamadas al método projects.metrics.create de la API de Logging. Para obtener información sobre las llamadas completas al método, consulta Crear métricas de contadores o Crea métricas de distribución.

Para cada etiqueta, debes agregar un segmento a los campos metricDescriptor y labelExtractors en LogMetric.

La sintaxis es la que se muestra a continuación:

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

Los elementos de sintaxis tienen el siguiente significado:

LABEL_NAME: es el nombre de la etiqueta como una string.
VALUE_TYPE: es el tipo de etiqueta: STRING, BOOL o INT64.
LABEL_DESCRIPTION: es una descripción de la etiqueta.
EXTRACTOR_EXPRESSION: es una string que combina el nombre del campo de la entrada de registro con una expresión regular opcional. La expresión del extractor puede ser una de las siguientes:
```
EXTRACT(FIELD)
```
```
REGEXP_EXTRACT(FIELD, REGEXP)
```

Para obtener más información sobre las expresiones regulares, consulta Sintaxis RE2.

A continuación, se muestra un ejemplo con dos etiquetas:

{
  ...
  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)",
  },
}

A fin de obtener más detalles, consulta el tipo LogMetric.