Métricas definidas por el usuario del agente

Beta

Este producto o función está sujeto a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones específicas del Servicio. Los productos y las funciones que se encuentran en la fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

En esta guía, se explica cómo puedes configurar el agente de Monitoring para que reconozca y exporte las métricas de tu aplicación a Cloud Monitoring.

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

Una forma alternativa de exportar las métricas de la aplicación a Monitoring es usar StatsD. Cloud Monitoring proporciona una configuración predeterminada que asigna métricas de StatsD a métricas definidas por el usuario. 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 de StatsD.

Para obtener más información sobre las métricas, consulta los siguientes documentos:

• Métricas, series temporales y recursos.
• Estructura de las series temporales.
• Descripción general de las métricas definidas por el usuario.

Esta funcionalidad solo está disponible para los agentes que se ejecutan en Linux. No está disponible en Windows.

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

Nota: El agente de Monitoring no usa la configuración de collectd predeterminada del sistema /etc/collectd.conf.

/etc/stackdriver/collectd.d/

Este es el directorio para los archivos de configuración agregados por el usuario. Para enviar métricas definidas por el usuario 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 definidas por el usuario: 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 definidas por el usuario 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 definidas por el usuario. El agente desconoce cuál son las métricas aceptadas o cuáles las descartadas.

Escribe métricas definidas por el usuario con el agente

Configuras el agente para que envíe datos de métricas a Monitoring. Cada dato debe asociarse con una métrica definida por el usuario, que defines con un descriptor de métrica. Estos conceptos se presentan en Métricas, series temporales y recursos y se describen en detalle en Estructura de series temporales y Descripción general de las métricas definidas por el usuario.

Puedes tener una métrica de collectd que se trate como una métrica definida por el usuario 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 cadenas de filtros no pueden modificar la lista de fuentes de datos y las métricas definidas por el usuario 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 definida por el usuario. 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 definida por el usuario 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_b^1
Tipo	gauge
Tipo de instancia	active-connections
[value]	cualquier valor^2

Notas:
¹ En el ejemplo, este valor codifica la aplicación (Nginx) y el nombre del servicio conectado.
² 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. 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 definida por el usuario. 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 con 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:

• Tipo de 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 filtro

Nota: Debes conectar tu nueva cadena de filtros a la cadena de filtros PreCache.

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 type:
      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 user-defined metrics. The rule returns
  # to the default "PreCache" chain. The default processing
  # will write all metrics to Cloud Monitoring,
  # which will drop any unrecognized metrics: ones that aren't
  # in the list of curated metrics and don't have
  # the user-defined 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 definida por el usuario comienza a fluir en Monitoring.

Referencia y recomendaciones

Descriptores de métricas y series temporales

Para obtener una introducción a las métricas de Cloud Monitoring, consulta Métricas, series temporales y recursos. Puedes encontrar más detalles en Descripción general de las métricas definidas por el usuario y en Estructura de series temporales.

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

• Un tipo 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
  

  Se recomienda una denominación jerárquica para facilitar el seguimiento de las métricas. Los tipos de métricas no pueden contener guiones. Para conocer las reglas de denominación exactas, consulta Etiquetas y tipos de métricas de nombres.

• 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.

• El tipo y el tipo de valor 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 tipo del descriptor de métrica asociado.

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

• Un valor con marca de tiempo coherente con el tipo y la clase de valor del 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 tipo de métrica, 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 descriptores de métricas.

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 Tipos de valores y clases de métricas.

• Puedes especificar tipos de etiquetas que no sean STRING.

Si escribes un dato en Monitoring que usa un tipo de métrica no definido, se crea un nuevo descriptor de métrica para el dato. Este comportamiento puede ser un problema cuando depuras el código que escribe datos de métricas; si se escribe mal el tipo de métrica, se producen 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.

Precios

En general, las métricas del sistema de Cloud Monitoring son gratuitas, mientras que las métricas de sistemas, agentes o aplicaciones externos no lo son. Las métricas facturables se facturan según la cantidad de bytes o la cantidad de muestras transferidas.

Para obtener más información sobre los precios de Cloud Monitoring, consulta los siguientes documentos:

• Resumen de precios de Cloud Monitoring.
• Precios de Cloud Monitoring.

Límites

Cloud Monitoring 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. Para obtener más detalles, consulta Cuotas y límites.

Si descubres que creaste descriptores de métricas que ya no deseas, puedes buscar y borrar los descriptores con 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.

Nota: Esto producirá una gran cantidad de resultados en los registros del sistema. Recomendamos desactivar esta función al final de tu sesión de solución de problemas. Si configuraste el agente de Cloud Logging, puedes ver las entradas de registro del sistema en Cloud Logging.

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"}]