Se usó la API de Cloud Translation para traducir esta página.

Métricas definidas por el usuario del agente

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 para usa StatsD. Cloud Monitoring proporciona una configuración predeterminada que asigna De las métricas StatsD a las 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:

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: La configuración de collectd predeterminada del sistema, /etc/collectd.conf, no lo usa el agente de Monitoring.
/etc/stackdriver/collectd.d/: Este es el directorio para los archivos de configuración agregados por el usuario. Para enviar alertas de texto del agente, coloca los archivos de configuración requeridos, de abajo, 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

Configura el agente para que envíe datos de métricas Supervisión Cada punto debe estar asociado con una métrica definida por el usuario, que se define con un descriptor de métrica. Estos conceptos se presentan en Métricas, series temporales y recursos. y se describe 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. Como las cadenas de filtros no pueden modificar la lista de fuentes de datos Las métricas definidas por el usuario solo admiten una única fuente de datos, cualquier métrica de collectd que desea usar con esta instalación deben tener una única 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 Supervisión con una métrica definida por el usuario. Sigue los pasos enumerados a continuación:

Identifica las métricas de collectd para cada servicio de Nginx.
Define un descriptor de métrica de Monitoring.
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`¹
Tipo	`gauge`
Tipo de instancia	`active-connections`
`[value]`	cualquier valor²

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 controla los detalles de la interpretación de los distintos tipos de valores. Los valores compuestos no son compatibles con el Agente de supervisión.

Series temporales y descriptor de métrica de Monitoring

Del 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

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.
La categoría 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 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 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 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.

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:

Límites

Cloud Monitoring tiene límites para la cantidad de tiempo de las 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.

Habilita write_log

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

Con permisos de administrador, edita el siguiente archivo de configuración:
```
/etc/stackdriver/collectd.conf
```
Justo después de LoadPlugin write_gcm, agrega lo siguiente:
```
LoadPlugin write_log
```
Justo después de <Plugin "write_gcm">…</Plugin>, agrega lo siguiente:
```
<Plugin "write_log">
  Format JSON
</Plugin>
```
Busca <Target "write">…</Target> y después de cada Plugin "write_gcm" agrega lo siguiente:
```
Plugin "write_log"
```
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"}]