Plug-in StatsD

StatsD est un protocole d'envoi de métriques et un daemon pour l'agrégation de données métriques. Configurer le plug-in StatsD de l'agent Monitoring conduit à faire fonctionner l'agent comme un daemon StatsD qui écrit des métriques dans Monitoring.

L'utilisation du plug-in StatsD avec sa configuration par défaut est le moyen le plus simple d'obtenir vos métriques définies par l'utilisateur dans Monitoring. Le plug-in StatsD n'est disponible que dans l'agent Linux Stackdriver Monitoring.

L'agent Monitoring peut également exporter d'autres métriques collectd en tant que métriques définies par l'utilisateur, mais il n'existe pas de configuration par défaut simple. Pour en savoir plus, consultez Métriques définies par l'utilisateur à partir de l'agent.

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

Découverte

Monitoring ne détecte pas automatiquement StatsD. Pour utiliser les métriques StatsD, configurez le plug-in StatsD comme décrit dans la section suivante.

Configurer le plug-in StatsD

Prérequis

Le plug-in StatsD requiert la version 5.5.2-356 ou une version ultérieure de l'agent Monitoring. Pour mettre à jour l'agent, reportez-vous à la section Mettre à jour l'agent.

Activer le plug-in

Effectuez les opérations suivantes sur votre instance de VM compatible sous Linux :

  1. Téléchargez le fichier statsd.conf et placez-le dans le répertoire /etc/stackdriver/collectd.d/ à l'aide de la commande suivante :

    (cd /etc/stackdriver/collectd.d/ && sudo curl -O https://raw.githubusercontent.com/Stackdriver/stackdriver-agent-service-configs/master/etc/collectd.d/statsd.conf)

  2. Le fichier de configuration par défaut demande à l'agent d'accepter les métriques StatsD sur le port StatsD par défaut, 8125.

    Si vous souhaitez envoyer certaines métriques vers votre daemon StatsD et d'autres métriques au daemon StatsD de l'agent, modifiez les paramètres de port dans le fichier de configuration.

  3. Redémarrez l'agent Monitoring pour récupérer la configuration StatsD en exécutant la commande suivante :

    sudo service stackdriver-agent restart

Pour plus d'informations sur le plug-in statsd collectd, consultez la section Plug-in:StatsD.

Mappage par défaut vers les métriques définies par l'utilisateur

Pour vous aider à démarrer rapidement, le plug-in StatsD de l'agent est fourni avec une configuration collectd par défaut qui fait correspondre les métriques StatsD aux métriques Stackdriver définies par l'utilisateur:

  • Toutes les métriques du plug-in StatsD contiennent statsd dans le composant collectd plugin.

  • Chaque type de métrique StatsD, disponible dans le composant collectd type, possède un nom correspondant de type de métrique défini par l'utilisateur.

  • Le nom de la métrique StatsD, contenu dans le composant collectd type_instance, est stocké en tant que valeur d'un libellé appelé metric.

    La valeur du libellé metric est différente pour le type de métrique Timer : elle comprend à la fois le nom de la métrique et un nom de compteur : "average" (moyenne), "upper" (supérieure) "lower" (inférieure), "sum" (somme), "percentile-50" (50e centile) et "percentile-95" (95e centile).

Par exemple, le tableau suivant montre comment les types de métriques StatsD compatibles et le nom de la métrique sont mappés avec les métriques Monitoring définies par l'utilisateur:

Type StatsD Nom StatsD Type de métrique Stackdriver Type de métrique Type de valeur Libellé(s) de la métrique
Counter my.counter custom.googleapis.com/statsd/derive Cumulé Int64 metric:my.counter
Gauge my.gauge custom.googleapis.com/statsd/gauge Jauge Double metric:my.gauge
Set my.set custom.googleapis.com/statsd/objects Jauge Double metric:my.set
Timer1 my.timer custom.googleapis.com/statsd/latency Jauge Double metric:my.timer-average
(identique) (identique) (identique) metric:my.timer-upper
(identique) (identique) (identique) metric:my.timer-lower
(identique) (identique) (identique) metric:my.timer-sum
(identique) (identique) (identique) metric:my.timer-percentile-50
(identique) (identique) (identique) metric:my.timer-percentile-95
custom.googleapis.com/statsd/gauge Jauge (identique) metric:my.timer-count

Remarques :
1 Il existe une séquence entrante de métriques statistiques statsd du même nom. L'agent agrège les métriques StatsD de type timer et exporte les données récapitulatives vers 7 séries temporelles différentes.

Pour en savoir plus sur les types StatsD, consultez la Spécification StatsD.

Personnaliser les métriques exportées

La configuration par défaut de StatsD est conçue pour vous permettre de démarrer rapidement. Cette section vous aide à personnaliser la configuration pour répondre à des besoins plus complexes.

Vous devez être familiarisé avec les métriques définies par l'utilisateur. Pour obtenir une présentation des métriques, consultez la page Métriques, séries temporelles et ressources. Pour en savoir plus, consultez la page Présentation des métriques définies par l'utilisateur.

Vous pouvez personnaliser les éléments suivants :

  • Vous pouvez modifier les valeurs affectées au libellé metric par défaut. Si vous utilisez plus de valeurs de libellés, vous aurez plus de séries temporelles dans votre métrique définie par l'utilisateur. Si vous utilisez moins de valeurs de libellés, vous aurez moins de séries temporelles.

  • Vous pouvez modifier les types de métriques définies par l'utilisateur. Vous n'avez pas besoin d'utiliser les types prédéfinis fournis dans la configuration par défaut. Par exemple, vous pouvez identifier des métriques avec un certain nom et les utiliser pour elles avec un type de métrique défini par l'utilisateur différent.

  • Si vous modifiez les types de métriques définies par l'utilisateur, vous pouvez également modifier les libellés associés à chaque type. La configuration par défaut comporte un seul libellé, mais vous pouvez en ajouter ou modifier la clé du libellé.

Si vous modifiez les types de métriques, vous devez définir vos nouveaux types de métriques définis par l'utilisateur dans l'API Monitoring. Pour en savoir plus, consultez la section suivante, Concevoir un type de métrique.

Exemple

Supposons que vous utilisez StatsD pour surveiller une application composée de deux services, my_service_a et my_service_b. Pour chaque service, vous voulez exporter dans Monitoring une métrique de type compteur qui représente le nombre de requêtes ayant échoué. Vous ne voulez pas utiliser les types de métriques StatsD par défaut.

Métriques collectd entrantes

Avant de définir vos propres types de métriques, il est important de comprendre la structure d'une métrique collectd et la façon dont une métrique StatsD est mappée par défaut avec les métriques définies par l'utilisateur.

Les métriques collectd, en particulier les métriques StatsD, incluent les composants suivants :

    Host, Plugin, Plugin-instance, Type, Type-instance

Dans cet exemple, les métriques StatsD que vous souhaitez exporter correspondent aux identifiants suivants dans collectd :

Composant Valeur(s) attendue(s)
Hôte tous
Plug-in statsd
Instance de plug-in non défini1
Type derive2
Type instance [SERVICE_NAME].GET.[CODE]3
[VALUE] toute valeur4

Remarques :
1 Ce composant est actuellement laissé vide par le plug-in StatsD.
2 Une métrique de compteur StatsD est mappée avec le type collectd derive. 3 Par exemple, une instance de type peut être my_service_a.GET.500. 4 [VALUE] est généralement un horodatage et un nombre au format double précision.

Le tableau suivant montre comment cette métrique serait mappée par défaut :

Type StatsD Nom StatsD Type de métrique Stackdriver Type de métrique Type de valeur Libellés de la métrique
Nombre my_service_a.GET.500 custom.googleapis.com/statsd/derive Cumulé Int64 metric:my_servce_a.GET.500
Nombre my_service_b.GET.403 custom.googleapis.com/statsd/derive Cumulé Int64 metric:my_servce_b.GET.403

Le mappage par défaut peut présenter quelques difficultés pour vous :

  • Cette métrique de compteur particulière ([SERVICE_NAME].GET.[CODE]) figure dans le même type de métrique défini par l'utilisateur que toutes les autres métriques de compteur. Il n'est pas facile d'obtenir uniquement les données de cette métrique, car Stackdriver n'est actuellement pas compatible avec les recherches d'expressions régulières sur les libellés.

  • Vous ne pouvez pas facilement obtenir des données pour des services individuels ou des codes de réponse individuels dans vos données. Par exemple, vous ne pouvez pas obtenir facilement le nombre total d'erreurs (tous types confondus) survenues dans my_service_a.

  • La configuration par défaut exporte toutes les métriques StatsD vers Stackdriver, ce qui peut être coûteux si vous n'êtes intéressé que par certaines métriques.

Concevoir un type de métrique

Pour en savoir plus sur la création de types de métriques, consultez la section Créer un type de métrique défini par l'utilisateur.

Le type de métrique défini par l'utilisateur suivant constitue un choix judicieux pour les données de cet exemple, car il ne contient que la métrique StatsD qui vous intéresse et son choix de libellés permet de mieux organiser les données:

  • Type : custom.googleapis.com/http/request_errors
  • Libellés :
    • service_name (STRING) : nom du service.
    • response_code (INT64) : code de réponse HTTP.
  • Type de métrique : CUMULÉ
  • Type de valeur: INT64

Le tableau suivant montre le mappage souhaité entre StatsD et Stackdriver :

Type StatsD Nom StatsD Type de métrique Stackdriver Type de métrique Type de valeur Libellés de la métrique
Nombre my_service_a.GET.500 custom.googleapis.com/http/request_errors Cumulé Int64 service_name:my_service_a, response_code:500
Nombre my_service_b.GET.403 custom.googleapis.com/http/request_errors Cumulé Int64 service_name:my_service_b, response_code:403

Une fois que vous avez défini le type de métrique, vous pouvez le créer à l'aide de metricDescriptors.create. Pour savoir comment laisser Monitoring créer le type de métrique à votre place, consultez la page Créer automatiquement des descripteurs de métrique.

Mapper la configuration

Pour exporter la métrique StatsD vers le nouveau type de métrique définie par l'utilisateur, remplacez le contenu de la configuration par défaut du plug-in StatsD, /etc/stackdriver/collectd.d/statsd.conf, par le code suivant:

<Plugin statsd>
  Host "127.0.0.1"
  Port "8125"
  DeleteSets true
  TimerPercentile 50.0
  TimerPercentile 95.0
  TimerLower true
  TimerUpper true
  TimerSum true
  TimerCount true
</Plugin>

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">
  # The following rule does all the work for your metric:
  <Rule "rewrite_request_errors">
    # Do a careful match for just your metrics; if it fails, drop down
    # to the next rule:
    <Match regex>
      Plugin "^statsd$"
      TypeInstance "^.*\\.GET\\..*$"    # Match on type instance.
    </Match>

    <Target "set">
      # Specify the metric descriptor type:
      MetaData "stackdriver_metric_type" "custom.googleapis.com/http/request_errors"
      # Initialize the labels from the "type_instance" label; clean the values up in the next Target below.
      MetaData "label:service_name" "%{type_instance}"
      MetaData "label:response_code" "%{type_instance}"
    </Target>

    <Target "replace">
      # Remove ".GET.[code]" to get the real service name.
      MetaData "label:service_name" "\\.GET\\.[0-9]*$" ""
      # Remove "[service].GET." to get the real response code.
      MetaData "label:response_code" "^[^\\.]*\\.GET\\." ""
    </Target>
  </Rule>
</Chain>

Redémarrer l'agent

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 sont immédiatement transmises à Monitoring.

Étapes suivantes

La personnalisation du plug-in StatsD s'effectue de la même manière que la personnalisation des métriques collectd pour Monitoring. Pour en savoir plus, consultez les sections "Documentation de référence" et "Dépannage" de la page Métriques définies par l'utilisateur à partir de l'agent.