Configurar métricas de distribución

En esta página se explica cómo crear métricas basadas en registros de tipo de distribución mediante laGoogle Cloud consola, la API Logging y la CLI de Google Cloud. Para obtener una visión general de las métricas basadas en registros, consulta el artículo Información general sobre las métricas basadas en registros.

Información general

Las métricas de distribución requieren un filtro para seleccionar las entradas de registro pertinentes y un extractor de valores para obtener el valor numérico de la distribución. El extractor de valores es del mismo tipo que el 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 segmentos de histograma. Los valores extraídos no se registran individualmente, sino que se registra su distribución en los contenedores configurados, junto con el recuento, la media y la suma de la desviación cuadrática de los valores. Puedes usar el diseño predeterminado de los segmentos del histograma de tu distribución o ajustar los límites de los segmentos para capturar los valores de forma aproximada.

Para obtener más información sobre cómo ver e interpretar las métricas de distribución, consulta el artículo Métricas de distribución.

Antes de empezar

1. Para usar métricas basadas en registros, debes tener un Google Cloud proyecto con la facturación habilitada:

   Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

   In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

   Verify that billing is enabled for your Google Cloud project.

   In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Roles required to select or create a project

   • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
   • Create a project: To create a project, you need the Project Creator (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

   Go to project selector

   Verify that billing is enabled for your Google Cloud project.

   1. Asegúrate de que tu rol de gestión de identidades y accesos incluya los permisos necesarios para crear y ver métricas basadas en registros, así como para crear políticas de alertas. Para obtener más información, consulta Permisos de las métricas basadas en registros.

   Crear una métrica de distribución

   La métrica cuenta las entradas de registro identificadas por un filtro que proporciones. Puede usar expresiones regulares en su filtro. Le recomendamos que incluya un tipo de recurso. La longitud de un filtro no puede superar los 20.000 caracteres.

   No incluyas información sensible en el filtro. Los filtros se tratan como datos de servicio.

   Consola

   Sigue estos pasos para crear una métrica de contador basada en registros en la consola deGoogle Cloud de tu proyecto: Google Cloud

   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. Haz clic en Crear métrica. Aparecerá el panel Crear métrica de registros.

   3. Define el Tipo de métrica: selecciona Distribución.

   4. En la sección Detalles, rellene los siguientes campos:

      • Nombre de la métrica de registro: elija un nombre único entre las métricas basadas en registros de su Google Cloud proyecto. Se aplican algunas restricciones de nomenclatura. Para obtener más información, consulta la sección Solución de problemas.
      • Descripción: escriba una descripción de la métrica.
      • Unidades: (opcional) En el caso de las métricas de distribución, puedes introducir unidades, como s y ms. Para obtener más información, consulta el campo unit de MetricDescriptor.

   5. Define el filtro de métricas en la sección Selección de filtros.

      1. Usa el menú Seleccionar proyecto o contenedor de registros para elegir si la métrica debe contar las entradas de registro de tu Google Cloud proyecto o solo las de un contenedor de registros específico.

      2. Crea un filtro que recoja solo las entradas de registro que quieras contar en tu métrica mediante el lenguaje de consultas de registro. También puede usar expresiones regulares para crear los filtros de su métrica.

      3. Nombre del campo: introduce el campo de entrada de registro que contiene el valor de la distribución. Se te ofrecen opciones mientras escribes. Por ejemplo:

         protoPayload.latency
         

      4. Expresión regular: (opcional) si Nombre de campo siempre contiene un valor numérico convertible al tipo double, puede dejar este campo vacío. De lo contrario, especifique una expresión regular que extraiga el valor de distribución numérica del valor del campo.

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

         ([0-9.]+)
         

         Los paréntesis, conocidos como grupo de captura de expresión regular, identifican la parte del texto coincidente que se extraerá. Consulta más información sobre cómo usar expresiones regulares.

      • Avanzado (contenedores de histograma): (opcional) Si haces clic en Avanzado, se abre una sección del formulario que puedes usar para especificar diseños de contenedores personalizados. Si no especifica los diseños de los segmentos, se proporcionará un diseño predeterminado. Para obtener más información, consulta la sección Contenedores de histograma de esta página.
      1. Para ver qué entradas de registro coinciden con su filtro, haga clic en Vista previa de los registros.

   6. (Opcional) Añade una etiqueta en la sección Etiquetas. Para obtener instrucciones sobre cómo crear etiquetas, consulta el artículo Crear una etiqueta.

   7. Haz clic en Crear métrica para crear la métrica.

   gcloud

   Para crear una métrica basada en registros de tipo de distribución, crea un archivo que contenga una representación de tu definición de LogMetric en formato JSON o YAML. A continuación, usa el siguiente comando para leer la configuración de tu archivo:

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

   Para obtener información sobre cómo describir los segmentos de histograma de una distribución, consulta Segmentos de histograma.

   API

   Para crear una métrica de distribución, usa el método projects.metrics.create de la API Logging. Si usas el panel Explorador de APIs de la página de referencia, prepara los argumentos de la siguiente manera:

   1. Asigna al campo parent el proyecto o el segmento en el que se va a crear la métrica:

      • En el caso de una métrica basada en registros con ámbito de proyecto, especifica el proyecto:

      projects/PROJECT_ID
      

      • En el caso de una métrica basada en registros con ámbito de segmento, especifica el segmento:

      projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
      

   2. Asigna al cuerpo de la solicitud un objeto LogMetric. A continuación, se muestra un objeto de ejemplo de una métrica de distribución.

      {
        name:        "my-metric"
        description: "Description of my-metric."
        filter:      "resource.type=gce_instance AND log_id(\"syslog\")",
        valueExtractor: "REGEXP_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:

   • Se aplican algunas restricciones de nomenclatura. Para obtener más información, consulta la sección Solución de problemas.

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

   Segmentos de histograma

   Las métricas de distribución incluyen un histograma que cuenta el número de valores que se encuentran en intervalos especificados (segmentos). Puedes tener hasta 200 contenedores en una métrica de distribución.

   Cada contenedor tiene dos valores límite, L y H, que definen los valores más bajo y más alto que abarca el contenedor. La anchura del segmento es H - L. Como no puede haber huecos entre los contenedores, el límite inferior de un contenedor es el mismo que el límite superior del contenedor anterior, y así sucesivamente. Para que los límites no se incluyan en más de un segmento, cada segmento incluye su límite inferior, mientras que su límite superior pertenece al siguiente segmento.

   Todos los diseños de los contenedores se pueden especificar enumerando, en orden creciente, los valores límite entre los contenedores. El primer segmento es el segmento de subdesbordamiento, que cuenta los valores inferiores al primer límite. El último segmento es el segmento de desbordamiento, que cuenta los valores mayores o iguales que el último límite. Los demás contenedores cuentan los valores que son mayores o iguales que su límite inferior y menores que su límite superior. Si hay n valores de límite, habrá n+1 segmentos. Sin incluir los segmentos de desbordamiento inferior y superior, hay n-1 segmentos finitos.

   Hay tres formas de especificar los límites entre los segmentos del histograma de las métricas de distribución. Puedes especificar una fórmula para los valores límite o enumerar los valores límite:

   • Lineal(desplazamiento, anchura, i): todos los segmentos tienen la misma anchura. Los límites son offset + width * i, para i=0,1,2,...,N. Para obtener más información sobre los contenedores lineales, consulta la referencia de la API.

   • Exponencial(escala, factor_de_crecimiento, i): la anchura de los segmentos aumenta para valores más altos. Los límites son escala * factor_de_crecimientoⁱ, para i=0,1,2,...,N. Para obtener más información sobre los contenedores exponenciales, consulta la referencia de la API.

   • Explícito: enumera todos los límites de los segmentos en la matriz bounds. El contenedor i tiene estos límites:

     Upper bound: bounds[*i*] for (0 <= *i* < *N*-1)
     Lower bound: bounds[*i* - 1] for (1 <= *i* < *N*)
     

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

   En la siguiente sección se explica cómo especificar los contenedores del histograma:

   Consola

   El submenú Contenedores del histograma se abre cuando creas una métrica de distribución y haces clic en Más en el formulario Editor de métricas. El siguiente subformulario es para el diseño de segmento Lineal:

   

   Contenedores lineales: rellena el formulario de contenedor del histograma de la siguiente manera.

   • Tipo: Lineal
   • Valor inicial (a): límite inferior del primer segmento finito. Este valor se denomina offset en la API.
   • Número de segmentos (N): número de segmentos finitos. El valor debe ser igual o superior a 0.
   • Anchura del contenedor (b): la diferencia entre el límite superior y el límite inferior de cada contenedor finito. El valor debe ser superior a 0.

   Por ejemplo, si el valor inicial es 5, el número de segmentos es 4 y la anchura de los segmentos es 15, los intervalos de los segmentos serán los siguientes:

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

   Segmentos explícitos: Rellena el formulario de segmentos del histograma de la siguiente manera:

   • Tipo: Explícito
   • Límites (b): lista separada por comas de los valores límite de los contenedores finitos. También determina el número de contenedores y su anchura.

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

   0, 1, 2, 5, 10, 20
   

   y, a continuación, hay cinco contenedores finitos con los siguientes intervalos:

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

   Segmentos exponenciales: Rellena el formulario de segmentos del histograma de la siguiente manera:

   • Tipo: Exponencial

   • Número de segmentos (N): número total de segmentos finitos. El valor debe ser superior a 0.

   • Escala lineal (a): escala lineal de los segmentos. El valor debe ser superior a 0.

   • Factor de crecimiento exponencial (b): factor de crecimiento exponencial de los segmentos. El valor debe ser superior a 1.

   Por ejemplo, si N=4, a=3 y b=2, los intervalos de los segmentos son los siguientes:

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

   Para obtener más información sobre los contenedores, consulta BucketOptions en la API de Cloud Monitoring.

   API

   El diseño de segmento opcional se especifica mediante el campo bucketOptions del objeto LogMetric proporcionado a projects.metrics.create. Para ver el objeto LogMetric completo, consulta Crear una métrica de distribución en esta página. Las adiciones a los diseños de contenedor son las siguientes:

   Contenedores lineales:

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

   El ejemplo anterior crea los siguientes segmentos:

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

   Contenedores explícitos: los límites se indican de forma individual.

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

   El ejemplo anterior crea los siguientes segmentos:

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

   Segmentos exponenciales: los límites son escala * factorDeCrecimiento ^ i, para i=0,1,2, ..., numFiniteBuckets.

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

   El ejemplo anterior crea los siguientes segmentos:

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

   Latencia de métricas nuevas

   La nueva métrica aparecerá inmediatamente en la lista de métricas y en los menús de monitorización correspondientes. Sin embargo, la métrica puede tardar hasta un minuto en empezar a recoger datos de las entradas de registro coincidentes.

   Consultar métricas de distribución

   Para enumerar las métricas basadas en registros definidas por el usuario de tu proyecto Google Cloud o para inspeccionar una métrica concreta de tu proyecto Google Cloud , haz lo siguiente:

   Consola

   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. En el panel Métricas definidas por el usuario, se muestran las métricas basadas en registros definidas por el usuario del proyecto actual: Google Cloud

   3. Para ver los datos de una métrica basada en registros, haga clic en el menú more_vert de la fila de la métrica y seleccione Ver en Explorador de métricas.

   gcloud

   Para ver una lista de las métricas basadas en registros definidas por el usuario de tu Google Cloud proyecto, usa el siguiente comando:

   gcloud logging metrics list
   

   Para mostrar una métrica basada en registros definida por el usuario en tu Google Cloud proyecto, usa el siguiente comando:

   gcloud logging metrics describe METRIC_NAME
   

   Para obtener ayuda, usa el siguiente comando:

   gcloud logging metrics --help
   

   No puedes leer los datos de la serie temporal de una métrica desde Google Cloud CLI.

   API

   Mostrar métricas

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

   • parent: el nombre de recurso del Google Cloud proyecto: projects/PROJECT_ID.
   • pageSize: número máximo de resultados.
   • pageToken: obtiene la siguiente página de resultados. Para obtener información sobre el uso de tokens de página, consulta projects.metrics.list.

   Recuperar definiciones de métricas

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

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

     projects/PROJECT_ID/metrics/METRIC_ID
     

   Leer datos de métricas

   Para leer los datos de series temporales de una métrica basada en registros, usa projects.timeseries.list en la API Cloud Monitoring. Para obtener información sobre los datos de series temporales, consulta Leer series temporales.

   Para leer una sola métrica basada en registros definida por el usuario, rellena los parámetros del método con este tipo de métrica y este identificador:

   logging.googleapis.com/user/METRIC_ID
   

   Actualizar métricas de distribución

   Puedes editar una métrica basada en registros definida por el usuario para cambiar su descripción, su filtro y los nombres de los campos a los que hace referencia la métrica. Puede añadir nuevas etiquetas a la métrica y cambiar las expresiones regulares que se usan para extraer valores de la métrica y sus etiquetas. Si usas una métrica con ámbito de contenedor, también puedes actualizar el contenedor de la métrica.

   No puedes cambiar los nombres ni los tipos de las métricas basadas en registros definidas por el usuario ni sus etiquetas, y tampoco puedes eliminar etiquetas de una métrica basada en registros.

   Para editar una métrica basada en registros, sigue estos pasos:

   Consola

   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. En el menú more_vert, haz clic en Editar métrica de la métrica basada en registros que quieras modificar.

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

   4. Haz clic en Actualizar métrica.

   gcloud

   Usa la CLI de Google Cloud para cambiar la descripción, la consulta de filtro y el contenedor de una métrica de contador. Puedes actualizar todos los campos a la vez o solo algunos.

   gcloud logging update METRIC_NAME \
     --description="METRIC_DESCRIPTION" \
     --log-filter="FILTER" \
     --bucket-name=BUCKET_NAME
   

   Si cambia el contenedor asociado a una métrica de ámbito de contenedor, los datos de la métrica recogidos antes del cambio ya no reflejarán la configuración actual. Los datos de métricas recogidos en el segmento anterior no se eliminan.

   Para actualizar las métricas de distribución u otros campos de métricas de contador, excepto METRIC_NAME, crea un archivo que contenga la especificación revisada de tu LogMetric en formato JSON o YAML. A continuación, actualiza la métrica llamando al comando update con el campo --config-from-file y sustituyendo FILENAME por el nombre de tu archivo JSON o YAML:

   gcloud logging update METRIC_NAME --config-from-file FILENAME
   

   Para obtener más información, usa el siguiente comando:

   gcloud logging metrics update --help
   

   API

   Para editar una métrica basada en registros, usa el método projects.metrics.update de la API. Define los campos de la siguiente manera:

   • metricName 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, incluya un objeto LogMetric que sea exactamente igual a la métrica que ya tiene, excepto por los cambios y las adiciones que quiera hacer.

   Eliminar métricas de distribución

   Para eliminar una métrica basada en registros definida por el usuario, sigue estos pasos:

   Consola

   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. Selecciona la métrica que quieras eliminar y haz clic en Eliminar.

      También puede hacer clic en Eliminar métrica en el more_vert menú de la métrica basada en registros que quiera eliminar.

   gcloud

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

   gcloud logging metrics delete METRIC_NAME
   

   Para obtener más información, usa el siguiente comando:

   gcloud logging metrics delete --help
   

   API

   Para eliminar una métrica basada en registros definida por el usuario, usa el método projects.metrics.delete de la API.

   Además, en la página Métrica basada en registros de la consola Google Cloud , el panel Métricas definidas por el usuario de la interfaz de métricas basadas en registros ofrece más funciones para ayudarte a gestionar las métricas definidas por el usuario de tu proyectoGoogle Cloud . Consulta más información en Métricas definidas por el usuario.