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 con la consola deGoogle Cloud , la API de Logging y Google Cloud CLI. Para obtener una vista general de las métricas basadas en registros, consulta la Descripción general de las métricas basadas en registros.

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.

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

Antes de comenzar

1. Para usar métricas basadas en registros, debes tener un proyecto de Google Cloud 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.

   Go to project selector

   Make sure 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.

   Go to project selector

   Make sure that billing is enabled for your Google Cloud project.

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

   Crea una métrica de distribución

   La métrica cuenta las entradas de registro identificadas por un filtro que proporcionas. Puedes usar expresiones regulares en tu filtro, y te recomendamos que incluyas 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.

   Console

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

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

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

   4. Configura los siguientes campos en la sección Detalles:

      • Nombre de la métrica de registro: Elige un nombre que sea único entre las métricas basadas en registros de tu proyecto de Google Cloud . Se aplican algunas restricciones de denominación. Para obtener más detalles, consulta Solución de problemas.
      • Descripción: ingresa una descripción para la métrica.
      • Unidades: (Opcional) Para las métricas de distribución, puedes ingresar unidades, como s y ms. Para obtener más información, consulta el campo unit de MetricDescriptor.

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

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

      2. Crea un filtro que solo recopile las entradas de registro que deseas contar en tu métrica con el lenguaje de consulta de Logging. También puedes usar expresiones regulares para crear filtros de tu métrica.

      3. 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:

         protoPayload.latency
         

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

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

         ([0-9.]+)
         

         Los paréntesis, conocidos como grupo de captura de expresiones regulares, identifican la parte de coincidencia del texto que se extraerá. Consulta Usa expresiones regulares para obtener más detalles.

      • Avanzado (buckets de histogramas): cuando haces clic en Avanzado, se abre una sección del formulario que puedes usar para especificar diseños de buckets personalizados (opcional). Si no especificas tus diseños de bucket, se proporciona un diseño de bucket predeterminado. Para obtener más información, consulta Depósitos de histogramas en esta página.
      1. Para ver qué entradas de registro coinciden con tu filtro, haz clic en Obtener vista previa de los registros.

   6. Agrega una etiqueta en la sección Etiquetas (opcional). Para obtener instrucciones sobre cómo crear etiquetas, consulta Crea una etiqueta.

   7. Haz clic en Crear métrica a fin de crear la métrica.

   gcloud

   Para crear una métrica basada en registros de tipo distribución, crea un archivo que contenga una representación de tu definición de LogMetric en formato JSON o YAML. Luego, 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 buckets del histograma de una distribución, consulta Buckets del histograma.

   API

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

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

      • Para una métrica basada en registros con alcance de proyecto, especifica el proyecto:

      projects/PROJECT_ID
      

      • Para una métrica basada en registros con permisos de bucket, especifica el bucket:

      projects/PROJECT_ID/locations/LOCATION/bucket/BUCKET_ID
      

   2. Establece el cuerpo de la solicitud como un objeto LogMetric. A continuación, se muestra un objeto de muestra para 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 denominación; para obtener más detalles consulta la sección Solución de problemas.

   • metricDescriptor: Es 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 abarca el depósito. El ancho del depósito es H - L. Dado que no puede haber espacios entre los bucket s, el límite inferior de un bucket es el mismo que el límite superior del bucket anterior, y así sucesivamente. Para que los límites no caigan en más de un bucket, un bucket incluye su límite inferior; su límite superior pertenece al siguiente bucket.

   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 (compensación, ancho, i): Cada depósito tiene el mismo ancho. Los límites son compensación + ancho * i, para i=0, 1, 2, …,N. Para obtener más información sobre depósitos lineales, consulta la página de referencia de la API.

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

   • Explícito: Enumeras todos los límites para los buckets en el array de límites. El depósito i tiene los siguientes 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 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:

   Console

   El submenú Histogram buckets 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). El siguiente subformulario es para el diseño de bucket Lineal:

   

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

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

   Por ejemplo, si el valor de inicio es 5, el número de bucket s es 4 y el ancho del bucket es 15, entonces los rangos del bucket 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): 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.

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

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

   Por ejemplo, si N=4, a=3 y b=2, los rangos del bucket son los siguientes:

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

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

   API

   El campo bucketOptions del objeto LogMetric proporcionado para projects.metrics.create especifica el diseño del bucket opcional. 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 bucket 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 escalamiento * factor de crecimiento ^ i, parai=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 nueva métrica aparece en la lista de métricas y en los menús relevantes de Monitoring de inmediato. Sin embargo, la métrica podría tardar hasta un minuto en comenzar a recopilar datos para las entradas de registro coincidentes.

   Inspecciona métricas de distribución

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

   Console

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

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

   gcloud

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

   gcloud logging metrics list
   

   Para mostrar una métrica basada en registros definida por el usuario en tu proyecto Google Cloud , 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 series temporales de una métrica con Google Cloud CLI.

   API

   Mostrar métricas

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

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

   Recupera definiciones de métricas

   Para 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

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

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

   logging.googleapis.com/user/METRIC_ID
   

   Actualiza métricas de distribución

   Puedes editar una métrica basada en registros definida por el usuario para cambiar su descripción, filtro y nombres de 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. Si usas una métrica con alcance de bucket, también puedes actualizar el bucket de la métrica.

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

   Para editar una métrica basada en registros, haz lo siguiente:

   Console

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

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

   4. Haz clic en Actualizar métrica.

   gcloud

   Usa Google Cloud CLI para cambiar la descripción, la consulta de filtro y el bucket 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 cambias el bucket asociado a una métrica con alcance en el bucket, los datos de métricas recopilados antes del cambio ya no reflejarán la configuración actual. No se quitan los datos de métricas recopilados para el bucket anterior.

   Para actualizar las métricas de distribución o cualquier otro campo 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. Luego, actualiza la métrica llamando al comando update con el campo --config-from-file, reemplazando FILENAME por el nombre de tu archivo JSON o YAML:

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

   Para obtener más detalles, 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 en la API. Configura los campos de la siguiente manera:

   • metricName: es 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 sea igual a la métrica existente excepto por los cambios y adiciones que deseas hacer.

   Borra métricas de distribución

   Para borrar una métrica basada en registros definida por el usuario, haz lo siguiente:

   Console

   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. Selecciona la métrica que deseas borrar y haz clic en Borrar.

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

   gcloud

   Usa el siguiente comando para borrar 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 detalles, usa el siguiente comando:

   gcloud logging metrics delete --help
   

   API

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

   Además, en la página Métrica basada en registros de la consola de Google Cloud , el panel Métricas definidas por el usuario de la interfaz de métricas basadas en registros proporciona más funciones para ayudarte a administrar las métricas definidas por el usuario en tu proyecto deGoogle Cloud . Consulta Métricas definidas por el usuario para obtener más detalles.