Métriques définies par l'utilisateur à partir de l'agent

Bêta

Ce produit ou cette fonctionnalité est soumis aux "Conditions des offres de pré-DG" dans la section "Conditions d'utilisation générales" des Conditions spécifiques au service. Les produits et fonctionnalités pré-DG sont disponibles "en l'état" et peuvent bénéficier d'une assistance limitée. Pour en savoir plus, consultez les descriptions des étapes de lancement.

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. En plus d'exporter de nombreuses métriques système et tierces prédéfinies vers Cloud Monitoring, l'agent peut exporter vos propres métriques d'application collectd vers Monitoring en tant que métriques définies par l'utilisateur. Les plug-ins collectd peuvent également exporter vers Monitoring.

Un autre moyen d'exporter les métriques d'application vers Monitoring consiste à utiliser StatsD. Cloud Monitoring fournit une configuration par défaut qui mappe les métriques StatsD aux métriques définies par l'utilisateur. Si ce mappage vous convient, vous n'avez pas besoin des étapes de personnalisation décrites ci-dessous. Pour en savoir plus, consultez la page Plug-in StatsD.

Pour en savoir plus sur les métriques, consultez les documents suivants:

• Métriques, séries temporelles et ressources.
• Structure des séries temporelles.
• Présentation des métriques définies par l'utilisateur

Cette fonctionnalité n'est disponible que pour les agents exécutés sous Linux. Elle n'est pas disponible sous Windows.

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.

Remarque :La configuration collectd par défaut du système, /etc/collectd.conf, n'est pas utilisée par l'agent Monitoring.

/etc/stackdriver/collectd.d/

Répertoire des fichiers de configuration ajoutés par l'utilisateur. Pour envoyer des métriques définies par l'utilisateur à 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 définies par l'utilisateur : 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 définies par l'utilisateur 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 qui ne sont pas des métriques définies par l'utilisateur sont supprimées silencieusement par Monitoring. L'agent lui-même ne sait pas quelles métriques sont acceptées ou ignorées.

Écrire des métriques définies par l'utilisateur avec l'agent

Vous configurez l'agent pour envoyer des points de données de métriques à Monitoring. Chaque point doit être associé à une métrique définie par l'utilisateur, que vous définissez à l'aide d'un descripteur de métrique. 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 Présentation des métriques définies par l'utilisateur.

Vous pouvez traiter une métrique collectd comme une métrique définie par l'utilisateur en ajoutant les métadonnées appropriées à la métrique:

• 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 définies par l'utilisateur ne prennent en charge qu'une seule source de données, toutes les métriques collectd que vous souhaitez utiliser avec cette fonction doivent avoir 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, Nous les enverrons à Monitoring à l'aide d'une métrique définie par l'utilisateur. 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 que vous souhaitez envoyer en tant que métriques définies par l'utilisateur 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_b^1
Type	gauge
Type instance	active-connections
[value]	toute valeur^2

Remarques :
¹ Dans l'exemple, cette valeur encode à la fois le nom de l'application (Nginx) et le nom du service connecté.
² 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 pas acceptées par l'agent Monitoring.

Descripteur de métrique et séries temporelles Monitoring

Côté Monitoring, concevez un descripteur de la métrique pour la métrique définie par l'utilisateur. Le descripteur suivant est un choix judicieux pour les données de cet exemple:

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

Une fois le descripteur de la métrique conçu, vous pouvez le créer à l'aide de projects.metricDescriptors.create ou le laisser créer automatiquement à partir des métadonnées de séries temporelles, décrites 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 :

• Type de métrique : custom.googleapis.com/nginx/active_connections
• Valeurs des libellés 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

Remarque :Vous devez relier votre nouvelle chaîne de filtres à la chaîne de filtres PreCache.

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

Charger la nouvelle configuration

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

sudo service stackdriver-agent restart

Les informations sur les métriques définies par l'utilisateur commencent à être 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 Présentation des métriques définies par l'utilisateur et Structure des séries temporelles.

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

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

  La dénomination recommandée est hiérarchique afin de faciliter le suivi des métriques. Les types de métriques ne peuvent pas contenir de traits d'union. Pour connaître les règles de dénomination exactes, consultez la section Attribuer des noms 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 métrique.

• Le genre et le type de valeur des points de données, par exemple "une 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 :

• Type du descripteur de la métrique associé.

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

• Valeur horodatée cohérente avec le type et le genre de valeur du descripteur de la 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 type de métrique du point, ses libellés et sa valeur peuvent être utilisés pour créer automatiquement un descripteur de jauge ou de métrique cumulative. Pour en savoir plus, consultez la section Créer automatiquement des descripteurs de métrique.

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 en savoir plus, consultez la section Genres de métriques et types de valeurs.

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

Si vous écrivez dans Monitoring un point de données qui utilise un type de métrique non défini, un descripteur de la métrique est créé pour ce point de données. Ce comportement peut poser problème lors du débogage du code qui écrit les données de métrique. Une faute d'orthographe du type de métrique entraîne de faux descripteurs de métrique.

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 Créer votre métrique.

Tarification

En général, les métriques système de Cloud Monitoring sont gratuites, contrairement aux métriques de systèmes, d'agents ou d'applications externes. Les métriques facturables sont facturées en fonction du nombre d'octets ou du nombre d'échantillons ingérés.

Pour en savoir plus sur les tarifs de Cloud Monitoring, consultez les documents suivants:

• Récapitulatif des tarifs de Cloud Monitoring
• Tarifs de Cloud Monitoring

Limites

Cloud Monitoring limite le nombre de séries temporelles de métriques et le nombre de descripteurs de métriques définis par l'utilisateur dans chaque projet. 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.

Remarque : Cette fonctionnalité génère de nombreux résultats dans les journaux système. Nous vous recommandons de la désactiver à la fin de la session de dépannage. Si vous avez configuré l'agent Cloud Logging, vous pouvez afficher les entrées de journal système dans Cloud Monitoring.

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