Métriques personnalisées de l'agent

Ce guide explique comment configurer l'agent de surveillance pour qu'il reconnaisse et exporte les métriques de votre application vers Cloud Monitoring.

L'agent de surveillance est un démon collectd. L'agent peut non seulement exporter vers Cloud Monitoring de nombreuses métriques système et tierces prédéfinies, mais également vos propres métriques d'application collectd en tant que métriques personnalisées. Les plug-ins collectd peuvent également exporter vers Monitoring.

Une autre méthode d'exportation des métriques d'application vers Monitoring consiste à utiliser StatsD. Cloud Monitoring propose une configuration par défaut qui mappe les métriques StatsD avec les métriques personnalisées. Si ce mappage vous convient, vous n'avez pas besoin d'exécuter les étapes de personnalisation décrites ci-dessous. Pour en savoir plus, consultez la page Plug-in StatsD.

Si vous ne connaissez pas les métriques personnalisées de Monitoring, consultez les pages Métriques, séries temporelles et ressources, Structure des séries temporelles et Utiliser des métriques personnalisées.

Avant de commencer

  • Installez l'agent de surveillance le plus récent sur une instance de VM et vérifiez qu'il fonctionne. Pour mettre à jour l'agent, reportez-vous à la section Mettre à jour l'agent.

  • Configurez collectd pour obtenir les données de surveillance de votre application. Collectd accepte de nombreux frameworks d'application et points de terminaison de surveillance standards via ses plug-ins de lecture. Recherchez le plug-in de lecture qui correspond à vos besoins.

  • (Facultatif) Pour plus de commodité, ajoutez la documentation de référence collectd de l'agent aux pages man de votre système. Pour cela, mettez à jour la variable MANPATH, puis exécutez mandb :

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

    Les pages man sont destinées à stackdriver-collectd.

Fichiers et répertoires importants

Les fichiers et répertoires suivants, créés lors de l'installation de l'agent de surveillance (collectd) servent à sa configuration :

/etc/stackdriver/collectd.conf

Le fichier de configuration collectd utilisé par l'agent. Éditez ce fichier pour modifier la configuration générale.

/etc/stackdriver/collectd.d/

Répertoire des fichiers de configuration ajoutés par l'utilisateur. Pour envoyer des métriques personnalisées à partir de l'agent, vous devez placer les fichiers de configuration requis (décrits ci-dessous) dans ce répertoire. Pour assurer la rétrocompatibilité, l'agent recherche également les fichiers dans /opt/stackdriver/collectd/etc/collectd.d/.

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

Documentation de la version de l'agent collectd. Vous pouvez ajouter ces pages à l'ensemble de pages man de votre système. Pour en savoir plus, consultez la section Avant de commencer.

/etc/init.d/stackdriver-agent

Script d'initialisation de l'agent.

Comment Monitoring gère les métriques collectd

L'agent de surveillance traite les métriques collectd en arrière-plan et les envoie à Monitoring, qui traite chacune d'elles en tant que membre de l'une des catégories suivantes :

  • Métriques personnalisées. Les métriques collectd associées à la clé de métadonnées stackdriver_metric_type et à une seule source de données sont traitées comme des métriques personnalisées et envoyées à Monitoring à l'aide de la méthode projects.timeSeries.create de l'API Monitoring.

  • Métriques sélectionnées. Toutes les autres métriques collectd sont envoyées à Monitoring via une API interne. Seules les métriques de la liste des métriques sélectionnées sont acceptées et traitées.

  • Métriques supprimées. Les métriques collectd qui ne figurent pas dans la liste des métriques sélectionnées et ne correspondent pas à des métriques personnalisées sont supprimées en mode silencieux par Monitoring. L'agent ne sait pas quelles métriques sont acceptées ou supprimées.

Écrire des métriques personnalisées avec l'agent

Vous configurez l'agent pour envoyer des points de données de métrique à Monitoring. Chaque point doit être associé à une métrique personnalisée que vous définissez à l'aide d'un descripteur de la statistique. Ces concepts sont présentés sur la page Métriques, séries temporelles et ressources et décrits en détail sur les pages Structure des séries temporelles et Utiliser des métriques personnalisées.

Une métrique collectd peut être traitée en tant que métrique personnalisée en lui ajoutant les métadonnées appropriées :

  • stackdriver_metric_type : (obligatoire) nom de la métrique exportée. Exemple : custom.googleapis.com/my_custom_metric.

  • label:[LABEL] : (facultatif) libellés supplémentaires de la métrique exportée. Par exemple, le libellé Monitoring STRING nommé color correspond à la clé de métadonnées label:color et à la valeur de clé "blue". Vous pouvez indiquer jusqu'à 10 libellés par type de métrique.

Vous pouvez modifier les métadonnées des métriques à l'aide d'une chaîne de filtres collectd. Étant donné que les chaînes de filtres ne peuvent pas modifier la liste des sources de données et que les métriques personnalisées n'acceptent qu'une seule source de données, toutes les métriques collectd à utiliser avec cette fonction doivent posséder une source de données unique.

Exemple

Dans cet exemple, nous allons surveiller les connexions Nginx actives à partir de deux services Nginx, my_service_a et my_service_b, puis les envoyer à Monitoring à l'aide d'une métrique personnalisée. Nous allons suivre les étapes ci-dessous :

  1. Identifier les métriques collectd pour chaque service Nginx.

  2. Définir un descripteur de métrique Monitoring.

  3. Configurer une chaîne de filtres collectd pour ajouter des métadonnées aux métriques collectd afin de répondre aux attentes de l'agent de surveillance.

Métriques collectd entrantes

Collectd s'attend à ce que les métriques comprennent les composants suivants. Les cinq premiers composants constituent l'identifiant collectd de la métrique :

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

Dans cet exemple, les métriques à envoyer en tant que métrique personnalisée ont les valeurs suivantes :

Composant Valeur(s) attendue(s)
Hôte tous
Plug-in curl_json
Instance de plug-in nginx_my_service_a ou
nginx_my_service_b1
Type gauge
Type instance active-connections
[value] toute valeur2

Remarques :
1 Dans l'exemple, cette valeur encode à la fois le nom de l'application (Nginx) et le nom du service connecté.
2 La valeur est généralement un horodatage et un nombre à double précision. Monitoring gère les détails de l'interprétation des différents types de valeurs. Les valeurs composées ne sont actuellement pas acceptées par l'agent de surveillance.

Descripteur de métrique et séries temporelles Monitoring

Côté Monitoring, créez un descripteur de métrique pour votre métrique personnalisée. Le descripteur suivant peut convenir pour les données de cet exemple :

  • Nom : custom.googleapis.com/nginx/active_connections
  • Libellés :
    • service_name (STRING) : nom du service associé à Nginx.
  • Genre : GAUGE
  • Type : DOUBLE

Une fois que vous avez défini le descripteur de métrique, vous pouvez le créer à l'aide de projects.metricDescriptors.create ou le faire créer automatiquement à partir des métadonnées de séries temporelles présentées ci-dessous. Pour plus d'informations, consultez la section Créer des descripteurs de métrique sur cette page.

En raison de la façon dont le descripteur de métrique est défini, les données de série temporelle y étant associées doivent contenir les informations suivantes :

  • Nom de la métrique : custom.googleapis.com/nginx/active_connections
  • Valeurs de libellé de métrique :
    • service_name : "my_service_a" ou "my_service_b"

D'autres informations de série temporelle, y compris la ressource surveillée associée (l'instance de VM qui envoie les données) et le point de données de métrique, sont automatiquement obtenues par l'agent pour toutes les métriques. Aucune action particulière n'est requise de votre part.

La chaîne de filtres

Créez un fichier, /opt/stackdriver/collectd/etc/collectd.d/nginx_curl_json.conf, contenant le code suivant :

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

Charger la nouvelle configuration

Pour récupérer la nouvelle configuration, redémarrez l'agent en exécutant la commande suivante sur l'instance de VM :

sudo service stackdriver-agent restart

Les informations relatives à la métrique personnalisée sont transmises à Monitoring.

Référence et bonnes pratiques

Descripteurs de métrique et séries temporelles

Pour obtenir une présentation des métriques Cloud Monitoring, consultez la page Métriques, séries temporelles et ressources. Pour en savoir plus, consultez les pages Utiliser des métriques personnalisées et Structure des séries temporelles.

Descripteurs de métrique. Un descripteur de métrique comporte les éléments significatifs suivants :

  • Un nom au format custom.googleapis.com/[NAME1]/.../[NAME0]. Exemple :

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

    Les noms de métrique personnalisée doivent commencer par custom.googleapis.com/. La dénomination recommandée est hiérarchique afin de faciliter le suivi des métriques. Les noms de métrique ne doivent pas contenir de tirets. Pour connaître les règles de dénomination exactes, consultez la section Attribuer un nom aux types de métriques et aux libellés.

  • Un maximum de 10 libellés pour annoter les données de métrique. Par exemple : device_name, fault_type ou response_code. Les valeurs des libellés ne sont pas spécifiées dans le descripteur de la statistique.

  • Le genre et le type de point de données. Par exemple : "valeur de jauge de type double". Pour en savoir plus, consultez les sections suivantes : MetricKind et ValueType.

Séries temporelles. Un point de données de métrique comporte les éléments significatifs suivants :

  • Le nom du descripteur de métrique associé

  • Les valeurs de tous les libellés du descripteur de métrique

  • Une valeur horodatée compatible avec le genre et le type du descripteur de métrique

  • La ressource surveillée dont proviennent les données, généralement une instance de VM. Le descripteur n'a pas besoin de libellé distinct pour l'espace réservé à la ressource, car il est intégré.

Créer des descripteurs de métrique

Vous n'avez pas besoin de créer de descripteur de métrique à l'avance. Lorsqu'un point de données arrive dans Monitoring, le nom de métrique, les libellés et la valeur de ce point de données peuvent servir à créer automatiquement un descripteur de jauge ou de métrique cumulée. Pour plus d'informations, consultez Créer automatiquement des métriques personnalisées.

Cependant, lorsque vous créez votre propre descripteur de métrique, vous bénéficiez des avantages suivants :

  • Vous pouvez inclure une documentation pertinente sur la métrique et ses libellés.

  • Vous pouvez spécifier d'autres genres et types de métriques. Les seules combinaisons (genre, type) acceptées par l'agent sont (GAUGE, DOUBLE) et (CUMULATIVE, INT64). Pour plus d'informations, consultez la page Genres de métriques et types de valeurs.

  • Vous pouvez spécifier des types de libellés différents de STRING.

Dans Monitoring, si vous écrivez un point de données qui utilise un nom de métrique non défini, un nouveau descripteur de métrique est créé pour ce point de données. Cela peut poser problème lors du débogage du code d'écriture de données de métrique. Un nom de métrique mal orthographié engendrera des descripteurs de métrique erronés.

Une fois le descripteur de métrique créé, par vous-même ou automatiquement, il n'est plus modifiable. Par exemple, vous ne pouvez pas ajouter ou supprimer de libellés. Vous pouvez uniquement supprimer le descripteur de métrique (ce qui supprime toutes ses données), puis le recréer comme vous le souhaitez.

Pour plus d'informations sur la création de descripteurs de métrique, consultez Définir une métrique personnalisée.

Coûts et limites

Cloud Monitoring facture les métriques collectd (métriques d'agent et définies par l'utilisateur) en fonction du volume de données de métrique reçues. Pour en savoir plus, consultez la section Tarifs de la suite d'opérations de Google Cloud.

Outre la tarification, Cloud Monitoring limite le nombre de séries temporelles et de descripteurs de métrique définis par l'utilisateur dans chaque projet GCP. Pour plus de détails, consultez la page Quotas et limites.

Si vous avez créé des descripteurs de métrique dont vous ne voulez plus, vous pouvez les rechercher et les supprimer à l'aide de l'API Monitoring. Pour en savoir plus, consultez la section sur projects.metricDescriptors.

Dépannage

Cette section explique comment configurer le plug-in write_log de l'agent de surveillance pour vider tous les points de métrique, y compris les métadonnées. Cette fonctionnalité permet de déterminer les points à transformer et de garantir que les transformations se comportent comme prévu.

Activer write_log

Le plug-in write_log est inclus dans le package stackdriver-agent. Pour activer le plug-in, procédez comme suit :

  1. En mode root, modifiez le fichier de configuration suivant :

    /etc/stackdriver/collectd.conf
    
  2. Juste après LoadPlugin write_gcm, ajoutez :

    LoadPlugin write_log
    
  3. Juste après <Plugin "write_gcm">…</Plugin>, ajoutez :

    <Plugin "write_log">
      Format JSON
    </Plugin>
    
  4. Recherchez <Target "write">…</Target>, et après chaque Plugin "write_gcm", ajoutez :

    Plugin "write_log"
    
  5. Enregistrez vos modifications et redémarrez l'agent :

    sudo service stackdriver-agent restart
    

Ces modifications vont générer une ligne de journal par valeur de métrique signalée, y compris l'identifiant collectd complet, les entrées de métadonnées et la valeur.

Sortie de write_log

Si l'étape précédente a abouti, la sortie de write_log doit s'afficher dans les journaux système :

  • Linux basé sur Debian : /var/log/syslog
  • Linux basé sur Red Hat : /var/log/messages

Les exemples de lignes ci-dessous ont été mis en forme pour faciliter leur lecture dans ce document.

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