Métricas personalizadas del agente

En esta guía, se explica cómo 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. Los 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 de StatsD a métricas personalizadas. Si estás satisfecho con esa asignación, no necesitas realizar los pasos de personalización que se describen a continuación. Para obtener más información, consulta Complemento de 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 Usa 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 el 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 se adapte a tus necesidades.

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

    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. El agente también busca los archivos en /opt/stackdriver/collectd/etc/collectd.d/ para la compatibilidad con versiones anteriores.

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

Esta es la documentación para la versión de collectd del agente. Puedes agregar estas páginas al conjunto de páginas man de tu sistema. Consulta Antes de comenzar para obtener más información.

/etc/init.d/stackdriver-agent

Esta es la secuencia de comandos de inicialización 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 presentan en Métricas, series temporales y recursos y se describen en detalles en Estructura de tipos de métricas y Usa métricas personalizadas.

Puedes tener una métrica de collectd que se trate como una métrica personalizada si agregas los metadatos adecuados a la métrica:

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

  • label:[LABEL]: Etiquetas adicionales para la métrica exportada (opcional). Por ejemplo, si deseas una etiqueta de STRING de Monitoring llamada color, 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 usar una cadena de filtros 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 filtros 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 Por lo general, el valor es una marca de tiempo y un número de doble precisión. Monitoring maneja los detalles para 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): El nombre del servicio conectado a Nginx.
  • Categoría: INDICADOR
  • Tipo: DOBLE

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 describen 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:

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

El agente obtiene de forma automática otra información de las 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 filtros

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 configuración nueva

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 Métricas, series temporales y recursos. Encontrarás más detalles en Usa métricas personalizadas y en Estructura de tipos de métrica.

Descriptores de métricas. Un descriptor de métrica tiene las siguientes partes 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 métricas personalizadas deben comenzar con custom.googleapis.com/. Se recomienda una denominación jerárquica para facilitar el seguimiento de las métricas. Los nombres de las métricas no pueden contener guiones. Para conocer las reglas exactas de nombres, consulta Reglas para los nombres de métricas y etiquetas.

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

  • La categoría 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 categoría y el tipo de descriptor de métrica.

  • El recurso supervisado del que provienen los datos, que suele ser 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 documentación detallada para la métrica y sus etiquetas.

  • Puedes especificar categorías 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 borra todos sus datos) y, luego, volver a crear el descriptor de la forma que quieras.

Para obtener más detalles sobre cómo crear descriptores de métricas, consulta Define tu métrica.

Costos y límites

Stackdriver cobra por las métricas de collectd, las definidas por el usuario y las 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 la cantidad de series temporales de métricas y la cantidad de descriptores de métricas definidos por el usuario en cada proyecto de GCP. Para obtener más detalles, consulta Cuotas y límites.

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

Soluciona problemas

En esta sección, se explica cómo configurar el complemento write_log del agente de Monitoring a fin de borrar todo el conjunto de puntos de métrica, incluidos los metadatos. Esto se puede usar con el fin de determinar qué datos deben transformarse y, también, para garantizar que tus transformaciones se comporten como se espera.

Habilita write_log

El complemento write_log se incluye en el paquete stackdriver-agent. Para habilitar el complemento, haz lo siguiente:

  1. Con permisos de administrador, edita el siguiente archivo de configuración:

    /etc/stackdriver/collectd.conf
    
  2. Justo después de LoadPlugin write_gcm, agrega lo siguiente:

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

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

    Plugin "write_log"
    
  5. Guarda los 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 realizaste el paso anterior de manera correcta, 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

Se adaptó el formato de las líneas de muestra que aparecen a continuación 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"}]