Crea métricas de distribución

En esta página, se explica cómo crear métricas basadas en registros mediante GCP Console y la API de Stackdriver Logging.

Descripción general

Las métricas de distribución requieren un filtro para seleccionar las entradas de registro relevantes y un extractor de valores a fin de capturar el valor numérico para la distribución. El extractor de valores es del mismo tipo que se usa para las etiquetas definidas por el usuario.

Una métrica de distribución registra la distribución estadística de los valores extraídos en depósitos de histogramas. Los valores extraídos no se registran de forma individual, pero se registra su distribución a través de los depósitos configurados, junto con el recuento, la media y la suma de la desviación al cuadrado de los valores. Puedes usar el diseño predeterminado de los depósitos de histogramas en tu distribución o puedes ajustar los límites de los depósitos para capturar los valores de manera aproximada.

Crea una métrica de distribución

Consola de Logging

Sigue estos pasos para crear una métrica basada en registros en GCP Console:

  1. Haz clic en Stackdriver Logging > Métricas basadas en registros en la lista de navegación del lado izquierdo en GCP Console o haz clic en el siguiente botón:

    Ir al visor de registros

  2. Usa el menú desplegable en la parte superior de la página para seleccionar un proyecto.

  3. Haz clic en Create Metric (Crear métrica) en la parte superior de la página. Verás el Metric Editor (Editor de métricas) del lado derecho de la página y el panel del visor que muestra tus registros en el lado izquierdo:

    Crea una métrica de distribución

  4. En el panel del visor, crea un filtro que muestre solo las entradas de registro que deseas contar en tu métrica.

    El filtro básico está disponible en los menús desplegables sobre las entradas del registro. De manera alternativa, puedes acceder a la interfaz del filtro avanzado si haces clic en el menú desplegable del lado derecho de la barra de búsqueda y seleccionas Convert to advanced filter (Convertir en filtro avanzado).

    Para obtener más información, consulta Las interfaces de usuario.

  5. En el panel Editor de métricas (Editor de métricas), configura los siguientes campos:

    • Name (Nombre): Elige un nombre que sea único entre las métricas basadas en registros de tu proyecto. Se aplican algunas restricciones de denominación; para obtener más detalles, consulta la sección Solución de problemas.
    • Description (Descripción): Describe la métrica.
    • Labels (Etiquetas): Este campo es opcional; si quieres agregar etiquetas, haz clic en Agregar elemento para cada etiqueta. A fin de obtener detalles sobre la definición de etiquetas, consulta Etiquetas de métricas basadas en registros.
    • Units (Unidades): Este campo es opcional; para las métricas de distribución, puedes ingresar unidades como s, ms, etc. A fin de obtener más información, consulta el campo unit del MetricDescriptor.
    • Type (Tipo): Distribución.
    • Field name (Nombre del campo): Ingresa el campo de entrada de registro que contiene el valor de la distribución. Se te sugieren opciones a medida que escribes. Por ejemplo:

      jsonPayload.latency
      
    • Extraction expression (Expresión de extracción): Si Field name (Nombre del campo) siempre contiene un valor numérico convertible al tipo double, entonces puedes dejar este campo vacío. Este campo es opcional. De lo contrario, especifica una expresión regular que extraiga el valor de distribución numérico del valor del campo. El menú Compilación se puede usar para compilar y verificar de manera interactiva la expresión regular.

      Ejemplo. Supongamos que tu campo de entrada de registro latency contiene un número seguido de ms, por milisegundos. La siguiente expresión regular elige el número sin el sufijo de la unidad:

      ([0-9.]+)ms
      

      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.

    • More (Histogram buckets) [Más (Depósitos de histogramas)]: Cuando haces clic en More (Más), se abre una sección del formulario que puedes usar para especificar diseños de depósitos personalizados. Este campo es opcional. Si no especificas tus diseños de depósito, se proporciona un diseño de depósito predeterminado. Para obtener más información, consulta los depósitos de histogramas en esta página.

  6. Haz clic en Crear Métrica.

API de Logging

Para crear una métrica de distribución, usa el método projects.metrics.create de la API de Stackdriver Logging. Puedes probar el método en [APIs Explorer][apis-explorer-create]. Prepara los argumentos del método de la siguiente manera:

  1. Establece el campo Superior en el proyecto en el que se creará la métrica:

    projects/[PROJECT_ID]
    
  2. Establece el cuerpo de la solicitud como un objeto LogMetric. A continuación, se muestra un ejemplo del objeto para una métrica de distribución:

    {
      name:        "my-metric"
      description: "Description of my-metric."
      filter:      "resource.type=gce_instance AND logName:\"logs/syslog\"",
      valueExtractor: "REGEX_EXTRACT(jsonPayload.latencyField, \"([0-9.]+)ms\")",
    
      labelExtractors: {
        "my-label-1":
          "REGEXP_EXTRACT(jsonPayload.someField, \"before ([[:word:]]+) after\")",
        "my-label-2":
          "EXTRACT(jsonPayload.anotherField, \"before ([0-9]+) after\")",
      },
      bucketOptions: { [SEE_BELOW] },
    
      metricDescriptor: {
          metricKind: DELTA,
          valueType: DISTRIBUTION,
          unit: "ms",
    
          labels: [
            {
              key: "my-label-1",
              valueType: STRING,
              description: "Description of string my-label-1.",
            },
            {
              key: "my-label-2",
              valueType: INT64,
              description: "Description of integer my-label-2.",
            }
          ]
      },
    }
    

Notas de las métricas de distribución:

  • Se aplican algunas restricciones de denominación; para obtener más detalles, consulta la sección Solución de problemas.

  • metricDescriptor: un objeto MetricDescriptor. metricKind debe ser DELTA. valueType debe ser DISTRIBUTION.

Depósitos de histogramas

Las métricas de distribución incluyen un histograma que cuenta el número de valores que caen en rangos especificados (depósitos). Puedes tener hasta 200 depósitos en una métrica de distribución.

Cada depósito tiene dos valores de límite, L y H, que definen los valores más bajos y más altos que cubre el depósito. El ancho del depósito es H - L. Como no puede haber espacios entre los depósitos, el límite inferior de un depósito es el mismo que el límite superior del depósito anterior, y así sucesivamente. Para que los límites no caigan en más de un depósito, un depósito incluye su límite inferior; su límite superior pertenece al siguiente depósito.

Todos los diseños de los depósitos pueden especificarse si enumeras, en orden ascendente, los valores de los límites entre los depósitos individuales. El primer depósito es el depósito de subdesbordamiento, que cuenta valores inferiores al primer límite. El último depósito es el depósito de desbordamiento, que cuenta valores mayores o iguales al último límite. Los otros depósitos cuentan valores mayores o iguales a su límite inferior y menores a su límite superior. Si hay valores de límite n, entonces hay depósitos n+1. A excepción de los depósitos de subdesbordamiento y desbordamiento, hay n-1 depósitos finitos.

Hay tres formas diferentes de especificar los límites entre los depósitos de histogramas para las métricas de distribución. Puedes especificar una fórmula para los valores de límite o enumerarlos:

  • Lineal (desplazamiento, ancho, i): Cada depósito tiene el mismo ancho. Los límites son desplazamiento + ancho * i, para i=0,1,2,…,N. A fin de obtener más información sobre depósitos lineales, consulta la referencia de API.

  • Exponencial (ajuste, factor de crecimiento, i): El ancho de los depósitos aumenta para los valores más altos. Los límites son ajuste * factor de crecimiento^i, para i=0,1,2,...,N. A fin de obtener más información sobre depósitos exponenciales, consulta la referencia de API.

  • Explicito: Enumeras todos los límites para los depósitos en el arreglo de límites. El depósito i tiene los siguientes límites:

    Límite superior: límites [i] para (0 <= i < N-1)
    Límite inferior: límites [i - 1] para (1 <= i < N)

    Para obtener más información sobre depósitos explícitos, consulta la referencia de API.

La forma en que especificas tus depósitos de histogramas se explica en la siguiente sección:

Consola de Logging

El submenú Histogram buckets (Depósitos de histogramas) se abre cuando creas una métrica de distribución y haces clic en More (Más) en el formulario Metric editor (Editor de métricas). A continuación, se muestra el subformulario para el diseño de depósito Linear (Lineal):

Depósitos de histogramas

Linear buckets (Depósitos lineales): Completa el formulario del depósito de histograma de la siguiente manera.

  • Type (Tipo): Linear (Lineal)
  • Start value (a) (Valor de inicio): Es el límite inferior del primer depósito finito. Este valor se llama desplazamiento en la API.
  • Number of buckets (N) (Cantidad de depósitos): Es la cantidad de depósitos finitos. El valor debe ser mayor o igual que 0.
  • Bucket width (b) (Ancho de depósito): Es la diferencia entre el límite superior y el límite inferior en cada depósito finito. El valor debe ser mayor que 0.

Por ejemplo, si el valor de inicio es 5, el número de depósitos es 4 y el ancho del depósito es 15, entonces los rangos del depósito son los siguientes:

[-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF]

Depósitos explícitos: Completa el formulario del depósito de histograma de la siguiente manera:

  • Tipo: Explícito
  • Límites (b): Es una lista separada por comas de los valores de límite de los depósitos finitos. Esto también determina el número de depósitos y sus anchos.

Por ejemplo, si la lista de límites es esta:

0, 1, 2, 5, 10, 20

entonces hay cinco depósitos finitos con los siguientes rangos:

[-INF, 0), [0, 1), [1, 2), [2,5), [5, 10), [10, 20), [20, +INF]

Depósitos exponenciales: Completa el formulario de histograma de la siguiente manera:

  • Tipo: Exponencial
  • Cantidad de depósitos (N): La cantidad total de depósitos finitos. El valor debe ser mayor que 0.

  • Ajuste lineal (a): La escala lineal para los depósitos. El valor debe ser mayor que 0.

  • Factor de crecimiento exponencial (b): El factor de crecimiento exponencial para los depósitos. El valor debe ser mayor que 1.

Por ejemplo, si N=4, a=3 y b=2, entonces los rangos de depósitos son los siguientes:

[-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF]

Para obtener más información sobre los depósitos, consulta Opciones de depósitos en la API de Stackdriver Monitoring.

API de Logging

El diseño del depósito opcional está especificado por el campo bucketOptions en el objeto LogMetric suministrado a projects.metrics.create. Para obtener información sobre el objeto LogMetric completo, consulta Crea una métrica de distribución en esta página. Las adiciones para diseños de depósito se muestran a continuación:

Depósitos lineales:

{ # LogMetric object
  ...
  bucketOptions: {
    linearBuckets: {
      numFiniteBuckets: 4,
      width: 15,
      offset: 5
    }
  },

La muestra anterior crea los siguientes depósitos:

[-INF, 5), [5, 20), [20, 35), [35, 50), [50, 65), [65, +INF]

Depósitos explícitos: Los límites se enumeran individualmente.

{ # LogMetric object
  ...
  bucketOptions: {
    explicitBuckets: {
      bounds: [0, 1, 2, 5, 10, 20 ]
    }
  },

La muestra anterior crea los siguientes depósitos:

[-INF, 0), [0, 1), [1, 2), [2, 5), [5, 10), [10, 20), [20, +INF]

Depósitos exponenciales: Los límites son ajuste * factor de crecimiento ^ i, para i=0,1,2,…, numFiniteBuckets

{ # LogMetric object
  ...
  bucketOptions: {
    exponentialBuckets: {
      numFiniteBuckets: 4,
      growthFactor: 2,
      scale: 3
    }
  },
  ...
}

La muestra anterior crea los siguientes depósitos:

[-INF, 3), [3, 6), [6, 12), [12, 24), [24, 48), [48, +INF]

Latencia de métrica nueva

Tu métrica nueva aparece de inmediato en la lista de métricas del Visor de registros y en los menús relevantes de Stackdriver Monitoring. Sin embargo, la métrica puede tardar hasta un minuto en comenzar a recopilar datos para las entradas de registro coincidentes.

Inspecciona métricas de distribución

A fin de crear una lista de las métricas basadas en registros de tu proyecto de GCP o inspeccionar una métrica particular en tu proyecto, haz lo siguiente:

Consola de Logging

Haz clic en el siguiente botón para dirigirte a la página Métricas basadas en registros, que muestra una lista de todas las métricas basadas en registros en el proyecto actual:

Ir a Métricas basadas en registros

A fin de ver los datos en una métrica basada en registros, selecciona Ver en Explorador de métricas en el menú ampliado del lado derecho de la lista de métricas.

API de Logging

Enumera las métricas

Para enumerar las métricas basadas en registros definidas por el usuario en un proyecto, usa el método de la API projects.metrics.list. Completa los parámetros del método de la siguiente manera:

  • parent: el nombre del recurso del proyecto: projects/[PROJECT_ID].
  • pageSize: la cantidad máxima de resultados.
  • pageToken: obtiene la próxima página de resultados. Consulta projects.metrics.list.

Recupera definiciones de métricas

A fin de recuperar una sola métrica basada en registros definida por el usuario, usa el método de la API projects.metrics.get. Completa los parámetros del método de la siguiente manera:

  • metricName: el nombre del recurso de la métrica:

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

Lee datos de métricas

A fin de leer los datos de serie temporal de una métrica basada en registros, usa projects.timeseries.list en la API de Stackdriver Monitoring. Para obtener más detalles, consulta Lee series temporales. A continuación, se presenta la información que necesitas para las métricas basadas en registros:

  • El tipo de métrica es logging.googleapis.com/user/[METRIC_ID].

SDK de Cloud

A fin de realizar una lista de las métricas basadas en registros definidas por el usuario en tu proyecto, usa el siguiente comando:

gcloud logging metrics list

A fin de mostrar una métrica basada en registros definida por el usuario en tu proyecto, usa el siguiente comando:

gcloud logging metrics describe [METRIC_NAME]

Para obtener más detalles, usa el siguiente comando:

gcloud logging metrics --help

No puedes leer los datos de series temporales de una métrica con el SDK de Cloud.

Actualiza métricas de distribución

Puedes actualizar una métrica basada en registros a fin de cambiar la descripción, los filtros y los nombres de los campos a los que se hace referencia en la métrica. Puedes agregar etiquetas nuevas a la métrica y cambiar las expresiones regulares usadas a fin de extraer valores para la métrica y sus etiquetas.

No puedes cambiar los nombres o tipos de las métricas basadas en registros o sus etiquetas. Tampoco puedes borrar las etiquetas existentes en una métrica basada en registros.

A fin de editar o actualizar una métrica basada en registros, haz lo siguiente:

Consola de Logging

  1. Dirígete a la página Métricas basadas en registros:

    Ir a Métricas basadas en registros

  2. Haz clic en Editar métrica en el menú a la derecha de la métrica basada en registros que deseas editar.

  3. Cambia solo los elementos permitidos en la métrica.

  4. Haz clic en Listo.

API de Logging

A fin de editar o actualizar una métrica basada en registros, usa el método projects.metrics.update en la API. Establece los campos de la siguiente manera:

  • metricName: el nombre completo del recurso de la métrica:

    projects/[PROJECT_ID]/metrics/[METRIC_ID]
    

    Por ejemplo:

    projects/my-gcp-project/metrics/my-error-metric
    
  • En el cuerpo de la solicitud, incluye un objeto LogMetric que es igual a la métrica existente excepto por los cambios y adiciones que deseas hacer.

SDK de Cloud

Solo puedes cambiar la descripción y el filtro de una métrica existente con el SDK de Cloud.

Usa el siguiente comando para actualizar una métrica basada en registros. Puedes especificar cualquiera de las dos marcas, o ambas:

gcloud logging metrics update [METRIC_NAME] --description=[DESCRIPTION] --log-filter=[FILTER]

Para obtener más detalles, usa el siguiente comando:

gcloud logging metrics update --help

Borra métricas de distribución

A fin de borrar una métrica basada en registros, sigue estos pasos:

Consola de Logging

  1. Dirígete a la página Métricas basadas en registros:

    Ir a Métricas basadas en registros

  2. Selecciona las métricas que deseas borrar y haz clic en Borrar en la parte superior de la página.

    De manera alternativa, haz clic en Borrar métrica en el menú a la derecha de la métrica basada en registros que deseas borrar.

API de Logging

Usa el método projects.metrics.delete en la API.

SDK de Cloud

Usa el siguiente comando para borrar una métrica basada en registros definida por el usuario en el proyecto actual:

gcloud logging metrics delete [METRIC_NAME]

Para obtener más detalles, usa el siguiente comando:

gcloud logging metrics delete --help

¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

Stackdriver Logging
¿Necesitas ayuda? Visita nuestra página de asistencia.