Métricas definidas por el usuario del agente

Beta

Este producto o función está sujeto a los "Términos de las Ofertas de Acceso Previo a la Disponibilidad General" de la sección Términos Generales de los Servicios de los Términos Específicos de los Servicios. Los productos y las funciones previos a la disponibilidad general están disponibles tal cual y pueden tener una compatibilidad y asistencia limitadas. Para obtener más información, consulta las descripciones de las fases de lanzamiento.

En esta guía se explica cómo 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 sus propias métricas de la aplicación collectd a Monitoring como métricas definidas por el usuario. Tus complementos de collectd también pueden exportar datos a Monitoring.

Otra forma de exportar métricas de aplicaciones 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 conforme con esa asignación, no necesitas seguir los pasos de personalización que se describen a continuación. Para obtener más información, consulta el plugin StatsD.

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

• Métricas, series temporales y recursos
• Estructura de series temporales.
• Resumen de las métricas definidas por el usuario

Esta función solo está disponible para agentes que se ejecutan en Linux. No está disponible en Windows.

Antes de empezar

• Instala la versión más reciente del agente de Monitoring en una instancia de máquina virtual y comprueba que funciona. Para actualizar tu agente, consulta Actualizar el agente.

• Configura collectd para obtener datos de monitorización de tu aplicación. Collectd admite muchos frameworks de aplicaciones y endpoints de monitorización estándar a través de sus complementos de lectura. Busca un complemento de lectura que se adapte a tus necesidades.

• (Opcional) Para mayor comodidad, añade la documentación de referencia de collectd del agente a las páginas man de tu sistema. Para ello, actualiza la variable MANPATH y, a continuación, ejecuta mandb:

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

  Las páginas del manual son para stackdriver-collectd.

Archivos y directorios importantes

Los siguientes archivos y directorios, creados al instalar el agente, son relevantes para usar el agente de Monitoring (collectd):

/etc/stackdriver/collectd.conf

Archivo de configuración de collectd que usa el agente. Edita este archivo para cambiar la configuración general.

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

/etc/stackdriver/collectd.d/

Directorio de los archivos de configuración añadidos por el usuario. Para enviar métricas definidas por el usuario desde el agente, coloque los archivos de configuración necesarios, que se describen a continuación, en este directorio. Para garantizar la retrocompatibilidad, el agente también busca archivos en /opt/stackdriver/collectd/etc/collectd.d/.

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

Documentación de la versión de collectd del agente. Puedes añadir estas páginas al conjunto de páginas man de tu sistema. Para obtener más información, consulta la sección Antes de empezar.

/etc/init.d/stackdriver-agent

Secuencia de comandos de inicialización del agente.

Cómo gestiona Monitoring las métricas de collectd

Como contexto, los procesos del agente de Monitoring recogen métricas de collectd y las envían 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 sola fuente de datos se gestionan como métricas definidas por el usuario y se envían a Monitoring mediante el método projects.timeSeries.create de la API Monitoring.

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

• Métricas descartadas. Monitoring descarta de forma silenciosa 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 propio agente no sabe qué métricas se aceptan o se descartan.

Escribir métricas definidas por el usuario con el agente

Configura el agente para que envíe puntos de datos de métricas a Monitoring. Cada punto debe estar asociado a una métrica definida por el usuario, que se define con un descriptor de métrica. Estos conceptos se presentan en el artículo Métricas, series temporales y recursos y se describen en detalle en los artículos Estructura de las series temporales y Descripción general de las métricas definidas por el usuario.

Para que una métrica de collectd se trate como una métrica definida por el usuario, debes añadir los metadatos adecuados a la métrica:

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

• label:[LABEL] : (opcional) etiquetas adicionales de la métrica exportada. Por ejemplo, si quieres una etiqueta STRING de Monitoring llamada color, la 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 collectd para modificar los metadatos de tus métricas. Como las cadenas de filtros no pueden modificar la lista de fuentes de datos y las métricas definidas por el usuario solo admiten una fuente de datos, todas las métricas de collectd que quieras usar con esta función deben tener una única fuente de datos.

Ejemplo

En este ejemplo, monitorizaremos las conexiones Nginx activas de dos servicios Nginx, my_service_a y my_service_b. Los enviaremos a Monitoring mediante una métrica definida por el usuario. Seguiremos estos pasos:

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

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

3. Configura una cadena de filtros de collectd para añadir metadatos a las métricas de collectd y cumplir los requisitos del agente de Monitoring.

Métricas de collectd entrantes

Collectd espera que las métricas consten de los siguientes componentes. Los cinco primeros componentes forman el identificador de collectd de la métrica:

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

En este ejemplo, las métricas que quiere enviar como métricas definidas por el usuario tienen los siguientes valores:

Componente	Valor(es) esperado(s)
Anfitrión	any
Complemento	curl_json
Instancia de complemento	nginx_my_service_a o nginx_my_service_b^1
Tipo	gauge
Instancia de tipo	active-connections
[value]	cualquier valor^2

Notas:
¹ En el ejemplo, este valor codifica tanto la aplicación (Nginx) como el nombre del servicio conectado.
² El valor suele ser una marca de tiempo y un número de doble precisión. Monitoring se encarga de interpretar los distintos tipos de valores. El agente de monitorización no admite valores compuestos.

Monitorizar descriptores de métricas y series temporales

En la parte de monitorización, 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.
• Tipo: GAUGE
• Tipo: DOUBLE

Una vez que hayas diseñado el descriptor de métrica, puedes crearlo con projects.metricDescriptors.create o dejar que se cree a partir de los metadatos de la serie temporal, como se explica más abajo. Para obtener más información, consulta la sección Crear descriptores de métricas de esta página.

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

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

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

Tu cadena de filtros

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>

Cargar la nueva configuración

Reinicia el agente para que aplique la nueva configuración ejecutando el siguiente comando en tu instancia de VM:

sudo service stackdriver-agent restart

La información de tus métricas definidas por el usuario empezará a enviarse a Monitoring.

Referencias y prácticas recomendadas

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 consultar más información en los artículos Descripción general de las métricas definidas por el usuario y Estructura de las series temporales.

Descriptores de métricas Un descriptor de métrica tiene los siguientes elementos importantes:

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

  La nomenclatura recomendada es jerárquica para que los usuarios puedan hacer un seguimiento de las métricas más fácilmente. Los tipos de métrica no pueden contener guiones. Para consultar las reglas de nomenclatura exactas, consulta Nombres de tipos de métrica 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.

• El tipo y el tipo de valor de los puntos de datos, como "un valor de métrica de tipo double". Para obtener más información, consulta MetricKind y ValueType.

Serie temporal. Un punto de datos de una métrica tiene los siguientes elementos significativos:

• Tipo del descriptor de métrica asociado.

• Valores de todas las etiquetas del descriptor de métricas.

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

• El recurso monitorizado del que proceden los datos, normalmente una instancia de VM. El espacio para el recurso está integrado, por lo que el descriptor no necesita una etiqueta independiente.

Crear descriptores de métricas

No es necesario que cree un descriptor de métrica con antelación. Cuando llega un punto de datos a Monitoring, se pueden usar el tipo de métrica, las etiquetas y el valor del punto para crear automáticamente un descriptor de métrica de tipo Gauge o Cumulative. Para obtener más información, consulta Creación automática de descriptores de métricas.

Sin embargo, crear tu propio descriptor de métrica tiene varias ventajas:

• Puedes incluir documentación detallada sobre la métrica y sus etiquetas.

• Puede especificar más tipos de métricas. Las únicas combinaciones (tipo, clase) que admite el agente son (GAUGE, DOUBLE) y (CUMULATIVE, INT64). Para obtener más información, consulta Tipos de métricas y de valores.

• Puede especificar tipos de etiqueta distintos de STRING.

Si escribe un punto de datos en Monitoring que usa un tipo de métrica que no está definido, se crea un descriptor de métrica para el punto de datos. Este comportamiento puede ser un problema cuando depura el código que escribe datos de métricas, ya que si escribe mal el tipo de métrica, se generarán descriptores de métricas falsos.

Una vez que haya creado un descriptor de métrica o se haya creado automáticamente, no podrá cambiarlo. Por ejemplo, no puedes añadir ni quitar etiquetas. Solo puedes eliminar el descriptor de métrica (lo que elimina todos sus datos) y, a continuación, volver a crear el descriptor de la forma que quieras.

Para obtener más información sobre cómo crear descriptores de métricas, consulta el artículo Crear una métrica.

Precios

Por lo 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 el número de bytes o el número de muestras ingeridas.

Para obtener más información, consulta las secciones de Cloud Monitoring de la página Precios de Google Cloud Observability.

Límites

Cloud Monitoring tiene límites en el número de series temporales de métricas y en el número de descriptores de métricas definidos por el usuario en cada proyecto. Para obtener más información, consulta Cuotas y límites.

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

Solución de problemas

En esta sección se explica cómo configurar el complemento write_log del agente de monitorización para que genere el conjunto completo de puntos de métricas, incluidos los metadatos. Se puede usar para determinar qué puntos se deben transformar, así como para asegurarse de que las transformaciones se comportan como se espera.

Nota: Esto generará una gran cantidad de resultados en los registros del sistema. Te recomendamos que desactives esta función al final de la sesión de solución de problemas. Si has configurado el agente de Cloud Logging, puedes ver las entradas del registro del sistema en Cloud Logging.

Habilitar write_log

El complemento write_log se incluye en el paquete stackdriver-agent. Para habilitar el complemento, sigue estos pasos:

1. Como root, edita el siguiente archivo de configuración:

   /etc/stackdriver/collectd.conf
   

2. Justo después de LoadPlugin write_gcm, añade lo siguiente:

   LoadPlugin write_log
   

3. Justo después de <Plugin "write_gcm">…</Plugin>, añade lo siguiente:

   <Plugin "write_log">
     Format JSON
   </Plugin>
   

4. Busca <Target "write">…</Target> y, después de cada Plugin "write_gcm", añade 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 registrado, incluido el identificador collectd completo, las entradas de metadatos y el valor.

Salida de write_log

Si has completado el paso anterior correctamente, 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 ejemplo que se muestran 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"}]