Métricas personalizadas del agente

Esta guía explica cómo puedes configurar el agente de Stackdriver Monitoring para reconocer y exportar las métricas de tu aplicación a Stackdriver.

El agente de Monitoring es un daemon collectd. Además de exportar muchas métricas predefinidas del sistema y de terceros a Stackdriver, el agente puede exportar tus propias métricas de aplicación de collectd a Stackdriver como métricas personalizadas. Tus complementos de collectd también se pueden exportar a Stackdriver.

Una forma alternativa de exportar las métricas de la aplicación a Stackdriver es usar StatsD. Stackdriver Monitoring proporciona una configuración predeterminada que asigna métricas StatsD a las métricas personalizadas. Si estás satisfecho con esa asignación, no necesitas los pasos de personalización que se describen a continuación. Para obtener más información, consulta Complemento StatsD.

Si no estás familiarizado con las métricas personalizadas de Stackdriver, consulta Métricas, series temporales y recursos, Estructura de tipos de métricas y Usar métricas personalizadas.

Antes de comenzar

  • Instala el agente de Monitoring más reciente en una instancia de VM y verifica que funcione. Para actualizar tu agente, consulta Actualiza el agente.

  • Configura collectd para obtener datos de supervisión de tu aplicación. Collectd es compatible con muchos marcos de trabajo de aplicaciones y extremos de supervisión estándar a través de sus complementos de lectura. Encuentra un complemento de lectura que te sea útil.

  • (Opcional) Para tu conveniencia, agrega la documentación de referencia de collectd del agente a las páginas man de tu sistema mediante la actualización de la variable MANPATH, y luego ejecuta mandb:

    export MANPATH="$MANPATH:/opt/stackdriver/collectd/share/man"
    sudo mandb
    

    Las páginas man son para stackdriver-collectd.

Archivos y directorios importantes

Los siguientes archivos y directorios, creados mediante la instalación del agente, son relevantes para usar el agente de Monitoring (collectd):

/etc/stackdriver/collectd.conf

Este es el archivo de configuración de collectd que utiliza el agente. Edita este archivo para cambiar la configuración general.

/etc/stackdriver/collectd.d/

Este es el directorio para los archivos de configuración agregados por el usuario. Para enviar métricas personalizadas desde el agente, coloca los archivos de configuración necesarios, que se analizan a continuación, en este directorio. Para compatibilidad con versiones anteriores, el agente también busca archivos en /opt/stackdriver/collectd/etc/collectd.d/.

/opt/stackdriver/collectd/share/man/*

Esta es la documentación para la versión del agente de collectd. Puedes agregar estas páginas al conjunto de páginas man de tu sistema; consulta Antes de comenzar para obtener detalles.

/etc/init.d/stackdriver-agent

Esta es la secuencia de comandos init para el agente.

Cómo maneja Monitoring las métricas de collectd

El agente de Monitoring procesa las métricas de collectd en segundo plano y las envía a Monitoring, que trata cada métrica como miembro de una de las siguientes categorías:

  • Métricas personalizadas. Las métricas de collectd que tienen la clave de metadatos stackdriver_metric_type y una única fuente de datos se manejan como métricas personalizadas y se envían a Monitoring mediante el método projects.timeSeries.create en la API de Monitoring.

  • Métricas seleccionadas. Todas las demás métricas de collectd se envían a Monitoring a través de una API interna. Solo las métricas de la lista de métricas seleccionadas se aceptan y procesan.

  • Métricas descartadas. Monitoring descarta silenciosamente las métricas de collectd que no están en la lista de métricas seleccionadas y que no son métricas personalizadas. El agente desconoce cuál son las métricas aceptadas o cuáles las descartadas.

Escribe métricas personalizadas con el agente

Configura el agente para que envíe datos de métricas a Monitoring. Cada dato debe asociarse con una métrica personalizada, que defines con un descriptor de métrica. Estos conceptos se introducen en Métricas, series temporales y recursos y se describen en detalles en Estructura de tipos de métricas y Cómo utilizar métricas personalizadas.

Puedes tener una métrica de collectd tratada como una métrica personalizada mediante la adición de los metadatos adecuados a la métrica:

  • stackdriver_metric_type: (obligatorio) nombre de la métrica exportada. Por ejemplo: custom.googleapis.com/my_custom_metric.

  • label:[LABEL]: (opcional) etiquetas adicionales para la métrica exportada. Por ejemplo, si deseas nombrar una etiqueta STRING de Monitoring como color, entonces tu clave de metadatos sería label:color y el valor de la clave podría ser "blue". Puedes tener hasta 10 etiquetas por tipo de métrica.

Puedes utilizar una cadena de filtro de collectd a fin de modificar los metadatos para tus métricas. Debido a que las strings de filtros no pueden modificar la lista de fuentes de datos y las métricas personalizadas solo admiten una única fuente de datos, cualquier métrica de collectd que quieras utilizar con esta instalación debe tener una sola fuente de datos.

Ejemplo

En este ejemplo, supervisaremos las conexiones de Nginx activas de dos servicios de Nginx, my_service_a y my_service_b. Los enviaremos a Monitoring mediante una métrica personalizada. Sigue los pasos enumerados a continuación:

  1. Identifica las métricas de collectd para cada servicio de Nginx.

  2. Define un descriptor de métrica de Monitoring.

  3. Configura una cadena de filtro de collectd para agregar metadatos a las métricas de collectd, a fin de cumplir las expectativas del agente de Monitoring.

Métricas de collectd entrantes

Collectd espera métricas que constan de los siguientes componentes. Los primeros cinco componentes conforman el identificador de collectd para la métrica:

    Host, Plugin, Plugin-instance, Type, Type-instance, [value]

En este ejemplo, las métricas que quieres enviar como una métrica personalizada tienen los siguientes valores:

Componente Valor(es) esperado(s)
Host cualquiera
Complemento curl_json
Instancia de complemento nginx_my_service_a o
nginx_my_service_b1
Tipo gauge
Tipo de instancia active-connections
[value] cualquier valor2

Notas:
1 En el ejemplo, este valor codifica la aplicación (Nginx) y el nombre del servicio conectado.
2 Generalmente el valor es una marca de tiempo y un número de doble precisión. Monitoring maneja los detalles de interpretar los diferentes tipos de valores. Actualmente el agente de Monitoring no admite los valores compuestos.

Series temporales y descriptor de métrica de Monitoring

En el lado de Monitoring, diseña un descriptor de métrica para tu métrica personalizada. El siguiente descriptor es una opción razonable para los datos de este ejemplo:

  • Nombre: custom.googleapis.com/nginx/active_connections
  • Etiquetas:
    • service_name (STRING): nombre del servicio conectado a Nginx.
  • Tipo: GAUGE
  • Tipo: DOUBLE

Una vez que hayas diseñado el descriptor de métrica, puedes crearlo mediante projects.metricDescriptors.create o puedes dejar que se cree a partir de los metadatos de series temporales, que se analizan a continuación. Para obtener más información, consulta Crea descriptores de métricas en esta página.

Los datos de series temporales para este descriptor de métrica deben contener la siguiente información, debido a la forma en que se define el descriptor de métrica:

  • Nombre de la métrica: custom.googleapis.com/nginx/active_connections
  • Valores de la etiqueta de métrica:
    • service_name: "my_service_a" o "my_service_b"

El agente obtiene automáticamente otra información de series temporales, incluidos el recurso supervisado asociado (la instancia de VM que envía los datos) y el dato de la métrica para todas las métricas. No tienes que hacer nada especial.

Tu cadena de filtro

Crea un archivo, /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf, que contenga el siguiente código:

LoadPlugin match_regex
LoadPlugin target_set
LoadPlugin target_replace

# Insert a new rule in the default "PreCache" chain, to divert your metrics.
PreCacheChain "PreCache"
<Chain "PreCache">
  <Rule "jump_to_custom_metrics_from_curl_json">
    # If the plugin name and instance match, this is PROBABLY a metric we're looking for:
    <Match regex>
      Plugin "^curl_json$"
      PluginInstance "^nginx_"
    </Match>
    <Target "jump">
      # Go execute the following chain; then come back.
      Chain "PreCache_curl_json"
    </Target>
  </Rule>
  # Continue processing metrics in the default "PreCache" chain.
</Chain>

# Following is a NEW filter chain, just for your metric.
# It is only executed if the default chain "jumps" here.
<Chain "PreCache_curl_json">

  # The following rule does all the work for your metric:
  <Rule "rewrite_curl_json_my_special_metric">
    # Do a careful match for just your metrics; if it fails, drop down
    # to the next rule:
    <Match regex>
      Plugin "^curl_json$"                   # Match on plugin.
      PluginInstance "^nginx_my_service_.*$" # Match on plugin instance.
      Type "^gauge$"                         # Match on type.
      TypeInstance "^active-connections$"    # Match on type instance.
    </Match>

    <Target "set">
      # Specify the metric descriptor name:
      MetaData "stackdriver_metric_type" "custom.googleapis.com/nginx/active_connections"
      # Specify a value for the "service_name" label; clean it up in the next Target:
      MetaData "label:service_name" "%{plugin_instance}"
    </Target>

    <Target "replace">
      # Remove the "nginx_" prefix in the service_name to get the real service name:
      MetaData "label:service_name" "nginx_" ""
    </Target>
  </Rule>

  # The following rule is run after rewriting your metric, or
  # if the metric wasn't one of your custom metrics. The rule returns to
  # the default "PreCache" chain. The default processing
  # will write all metrics to Stackdriver Monitoring,
  # which will drop any unrecognized metrics: ones that are not
  # in the list of curated metrics and do not have
  # the custom metric metadata.
  <Rule "go_back">
    Target "return"
  </Rule>
</Chain>

Carga la nueva configuración

Reinicia tu agente a fin de recoger la configuración nueva; para hacerlo, ejecuta el comando siguiente en tu instancia de VM:

sudo service stackdriver-agent restart

Tu información de métrica personalizada comienza a fluir hacia Monitoring.

Referencia y recomendaciones

Descriptores de métricas y series temporales

Para obtener una introducción a las métricas de Stackdriver, consulta la sección Métricas, series temporales y recursos. Encontrarás más detalles disponibles en Cómo usar métricas personalizadas y en Estructura de tipos de métrica.

Descriptores de métricas. Un descriptor de métrica tiene las siguientes piezas significativas:

  • Un nombre con el formato custom.googleapis.com/[NAME1]/.../[NAME0]. Por ejemplo:

    custom.googleapis.com/my_measurement
    custom.googleapis.com/instance/network/received_packets_count
    custom.googleapis.com/instance/network/sent_packets_count
    

    Los nombres de las métricas personalizadas deben comenzar con custom.googleapis.com/. La denominación recomendada es jerárquica para facilitar el seguimiento de las métricas. Los nombres de las métricas no pueden contener guiones; a fin de conocer las reglas de nomenclatura exactas, consulta Reglas para los nombres de métricas y etiquetas.

  • Hasta 10 etiquetas para anotar los datos de las métricas, como device_name, fault_type o response_code. Los valores de las etiquetas no se especifican en el descriptor de métrica.

  • La clase y el tipo de los datos, como "un valor de indicador de tipo doble". Para obtener más información, consulta MetricKind y ValueType.

Series temporales. Un dato de la métrica tiene las siguientes piezas significativas:

  • El nombre del descriptor de métrica asociado.

  • Valores para todas las etiquetas del descriptor de métrica.

  • Un valor con marca de tiempo coherente con la clase y el tipo de descriptor de métrica.

  • El recurso supervisado del que provienen los datos, generalmente una instancia de VM. El espacio para el recurso está integrado, por lo que el descriptor no necesita una etiqueta separada.

Crea descriptores de métricas

No es necesario crear un descriptor de métrica por adelantado. Cuando un dato llega a Monitoring, el nombre de la métrica del dato, las etiquetas y el valor del dato se pueden usar para crear automáticamente un indicador o un descriptor de métrica acumulativo. Para obtener más información, consulta Creación automática de métricas personalizadas.

Sin embargo, hay ventajas en la creación de tu propio descriptor de métrica:

  • Puedes incluir alguna documentación inteligente para la métrica y sus etiquetas.

  • Puedes especificar clases y tipos adicionales de métricas. Las únicas combinaciones (clase, tipo) admitidas por el agente son (GAUGE, DOUBLE) y (CUMULATIVE, INT64). Para obtener más información, consulta Clases de métricas y tipos de valores).

  • Puedes especificar tipos de etiquetas que no sean STRING.

Si escribes un dato en Monitoring que usa un nombre de métrica no definido, se creará un nuevo descriptor de métrica para el dato. Esto puede ser un problema si estás depurando el código que escribe datos de métricas; si se escribe mal el nombre de la métrica, se producirán descriptores de métricas falsos.

Después de crear un descriptor de métrica, o después de que se haya creado automáticamente, este no se podrá cambiar. Por ejemplo, no podrás agregar o quitar etiquetas. Solo podrás borrar el descriptor de métrica, lo que elimina todos sus datos, y luego volver a crear el descriptor de la forma que quieras.

Para obtener más detalles sobre la creación de descriptores de métricas, consulte Define tu métrica.

Costos y límites

Stackdriver cobra por las métricas de collectd, tanto las definidas por el usuario como las métricas del agente, en función del volumen de datos de métricas recibidos. Para obtener más detalles, consulta Precios de Stackdriver.

Además de los precios, Stackdriver tiene límites en el número de series temporales de métricas y el número de descriptores de métricas definidos por el usuario en cada proyecto de GCP.a Para obtener más detalles, consulta Cuotas y límites.

Si descubres que has creado descriptores de métricas que ya no quieres, puedes buscarlos y borrarlos mediante la API de Monitoring. Para obtener más información, consulta projects.metricDescriptors.

Solución de problemas

Esta sección explica cómo configurar el complemento write_log del agente de Monitoring para volcar el conjunto completo de los datos de métricas, incluidos los metadatos. Esto se puede usar con el fin de determinar qué datos deben transformarse, así como para garantizar que tus transformaciones se comporten como se espera.

Habilita write_log

El complemento write_log está incluido en el paquete stackdriver-agent (versión 5.5.2-356 y posterior). Para habilitar el complemento, edita /opt/stackdriver/collectd.conf como raíz:

  1. Justo después de LoadPlugin write_gcm, agrega lo siguiente:

    LoadPlugin write_log
    
  2. Justo después de <Plugin "write_gcm">…</Plugin>, agrega lo siguiente:

    <Plugin "write_log">
      Format JSON
    </Plugin>
    
  3. Busca <Target "write">…</Target> y después de cada Plugin "write_gcm", agrega lo siguiente:

    Plugin "write_log"
    
  4. Guarda tus cambios y reinicia el agente:

    sudo service stackdriver-agent restart
    

Estos cambios imprimirán una línea de registro por cada valor de métrica informado, incluido el identificador de collectd completo, las entradas de metadatos y el valor.

Resultado de write_log

Si tuviste éxito en el paso anterior, deberías ver el resultado de write_log en los registros del sistema:

  • Linux basado en Debian: /var/log/syslog
  • Linux basado en Red Hat: /var/log/messages

Las líneas de muestra a continuación se han formateado para que sean más fáciles de leer en este documento.

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[1933524992], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"free"}]

Dec  8 15:13:45 test-write-log collectd[1061]: write_log values:#012[{
    "values":[0], "dstypes":["gauge"], "dsnames":["value"],
    "time":1481210025.252, "interval":60.000,
    "host":"test-write-log.c.test-write-log.internal",
    "plugin":"df", "plugin_instance":"udev", "type":"df_complex", "type_instance":"reserved"}]
¿Te sirvió esta página? Envíanos tu opinión:

Enviar comentarios sobre…

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