Etiquetas de métricas basadas en registros

En esta página, se analizan las etiquetas predeterminadas de las métricas basadas en registros y se explica cómo crear y usar las etiquetas en las métricas basadas en registros.

Si ya estás familiarizado con las etiquetas, puedes ir directamente a Crea una etiqueta en esta página.

Descripción general

Las etiquetas permiten que las métricas basadas en registros contengan varias series temporales, una para cada valor de etiqueta. 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 Stackdriver Logging cómo extraer el valor de la etiqueta desde 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 más información sobre las expresiones regulares, consulta Sintaxis RE2.

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.

  • No se puede borrar una etiqueta después de crearla.

    • 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 los Precios de Stackdriver. Para obtener información sobre cuotas y límites relacionados con las métricas, consulta Cuotas y límites y Solución de problemas.

Etiquetas predeterminadas

Todas las métricas basadas en registros, incluidas las métricas basadas en registros del sistema, vienen con 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 Stackdriver 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.

Ejemplo

En la siguiente captura de pantalla de Metrics Explorer (Explorador de métricas), se muestran las etiquetas en una de las métricas del sistema basadas en registros. 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

  1. Cuando creas una métrica basada en registros, parte del panel Editor de métricas incluye una opción para agregar etiquetas:

    Menú de etiquetas

  2. Haz clic en Agregar elemento. Verás el siguiente formulario, que ya está completo, para describir tu etiqueta:

    Crear etiqueta

    Sugerencia: para ver todos los campos y valores dentro de tus entradas de registro, elige una entrada de registro, haz clic en el ícono de expandir que se encuentra al lado y haz clic en Expandir todo.

  3. Completa los siguientes campos en el formulario Label (Etiqueta):

    1. Nombre: elige 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. Extraction regular expression (Expresión regular de extracción): si el valor de la etiqueta consta del contenido completo del campo, puedes dejar este campo vacío. De lo contrario, especifica la expresión regular (regexp) que extrae el valor de la etiqueta del valor del campo. Por ejemplo, supongamos que el campo, por lo general, contiene un texto como el que se muestra a continuación:

      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. A continuación, te mostramos uno:

      The instance number is ([0-9]+); .*
      

      Los paréntesis, conocidos como grupo de captura de expresiones regulares, identifican la parte de coincidencia del texto que se extraerá. Para obtener más información sobre las expresiones regulares, consulta Sintaxis RE2.

  4. Haz clic en Done (Listo) para crear la etiqueta. Puedes agregar más etiquetas si repites estos pasos.

API de Logging

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. Uno de los 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.

gcloud

Para obtener instrucciones sobre cómo crear una métrica basada en registros con etiquetas mediante la herramienta de línea de comandos de gcloud, ingresa a gcloud beta logging metrics create.