Cette page a été traduite par l'API Cloud Translation.

Métriques définies par l'utilisateur à partir 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 définies par l'utilisateur. 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 définies par l'utilisateur. 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.

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

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 collectées 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 ignorées 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étrique à 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.

Une métrique collectd peut être traitée en tant que métrique définie par l'utilisateur 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 définies par l'utilisateur n'acceptent qu'une seule source de données, toutes les métriques collectd que vous souhaitez utiliser avec cette installation doivent avoir une seule source de données.

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 définie par l'utilisateur. Nous allons suivre les étapes ci-dessous :

Identifier les métriques collectd pour chaque service Nginx.
Définir un descripteur de métrique Monitoring.
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 définie 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`¹
Type	`gauge`
Type instance	`active-connections`
`[value]`	toute valeur²

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 compatibles avec l'agent Monitoring.

Descripteur de métrique et séries temporelles Monitoring

Côté Monitoring, créez un descripteur de la métrique pour votre métrique définie par l'utilisateur. 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 la 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 :

Type de 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 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 votre métrique définie par l'utilisateur 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 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é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 métrique.
Le genre et le type de valeur des points 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 :

Type du descripteur de la métrique associé.
Les valeurs de tous les libellés du descripteur de métrique
Une valeur horodatée compatible avec le type et le genre de la 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, 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 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 un point de données dans Monitoring qui utilise un type de métrique non défini, un nouveau descripteur de la métrique est créé pour le point de données. Ce comportement peut poser problème lorsque vous déboguez le code qui écrit des données de métrique. Un type 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 Créer votre métrique.

Tarifs

En général, les métriques système Cloud Monitoring sont gratuites, contrairement aux métriques provenant 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 la tarification de Cloud Monitoring, consultez les documents suivants:

Limites

Cloud Monitoring limite le nombre de séries temporelles et de descripteurs de métrique 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.

Activer write_log

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

En mode root, modifiez le fichier de configuration suivant :
```
/etc/stackdriver/collectd.conf
```
Juste après LoadPlugin write_gcm, ajoutez :
```
LoadPlugin write_log
```
Juste après <Plugin "write_gcm">…</Plugin>, ajoutez :
```
<Plugin "write_log">
  Format JSON
</Plugin>
```
Recherchez <Target "write">…</Target>, et après chaque Plugin "write_gcm", ajoutez :
```
Plugin "write_log"
```
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"}]