OpenCensus est un projet Open Source gratuit dont les bibliothèques sont:
- Fournissez une assistance neutre en matière de fournisseur pour la collecte de données de métrique et de trace dans plusieurs langues.
- Peut exporter les données collectées vers différentes applications backend, y compris Cloud Monitoring, à l'aide des exportateurs.
Bien que Cloud Monitoring fournisse une API compatible avec la définition et la collecte de métriques personnalisées, il s'agit d'une API propriétaire de bas niveau. OpenCensus fournit une API qui suit le style de la communauté des langages, ainsi qu'un exportateur qui envoie les données de métriques à Cloud Monitoring via l'API Monitoring.
OpenCensus offre également une bonne prise en charge du traçage des applications. Pour obtenir des informations générales à ce sujet, consultez la page relative au traçage dans OpenCensus. Cloud Trace recommande d'utiliser OpenCensus pour l'instrumentation de trace. Pour collecter à la fois des données de métrique et de trace provenant de vos services, vous pouvez utiliser une distribution unique des bibliothèques. Pour en savoir plus sur l'utilisation d'OpenCensus avec Cloud Trace, consultez la page Bibliothèques clientes pour Trace.
Avant de commencer
Pour utiliser Cloud Monitoring, vous devez disposer d'un projet Cloud pour lequel la facturation est activée. Si nécessaire, procédez comme suit:
-
Dans Google Cloud Console, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
-
Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.
- Assurez-vous que l'API Monitoring est activée. Pour en savoir plus, consultez la page Activer l'API Monitoring.
Votre application Cloud doit authentifier votre application pour laquelle les applications s'exécutent en dehors de Google Cloud. En règle générale, vous configurez l'authentification en créant un compte de service pour votre projet et en configurant une variable d'environnement.
Pour les applications que vous exécutez sur une instance Amazon Elastic Compute Cloud (Amazon EC2), créez le compte de service du projet de connecteur AWS de l'instance.
Pour en savoir plus sur la création d'un compte de service, consultez la page Premiers pas avec l'authentification.
Installer OpenCensus
Pour utiliser les métriques collectées par OpenCensus dans votre projet Google Cloud, vous devez mettre les bibliothèques de métriques OpenCensus et l'exportateur Stackdriver à disposition de votre application. L'exportateur Stackdriver exporte les métriques qu'OpenCensus collecte vers votre projet Google Cloud. Vous pouvez ensuite utiliser Cloud Monitoring pour créer un graphique ou surveiller ces métriques.
Go
Pour pouvoir utiliser OpenCensus, vous devez disposer de Go version 1.11 ou supérieure. Les dépendances sont gérées automatiquement à votre place.
Java
Pour Maven, ajoutez le code suivant à l'élément
dependencies
de votre fichier pom.xml
:
Node.js
- Avant d'installer les bibliothèques principales et d'exportateurs OpenCensus, assurez-vous d'avoir préparé votre environnement pour le développement Node.js.
- Le moyen le plus simple d'installer OpenCensus est d'utiliser npm :
npm install @opencensus/core npm install @opencensus/exporter-stackdriver
- Placez les instructions
require
indiquées ci-dessous en haut du point d'entrée ou du script principal de votre application, avant tout autre code :
Python
Installez les bibliothèques principales d'OpenCensus et celles de l'exportateur Stackdriver à l'aide de la commande suivante :
pip install -r opencensus/requirements.txt
Le fichier requirements.txt
se trouve dans le dépôt GitHub de ces exemples, python-docs-samples.
Écrire des métriques personnalisées avec OpenCensus
L'instrumentation de votre code pour utiliser OpenCensus pour les métriques implique trois étapes:
- Importez les statistiques OpenCensus et les packages d'exportateurs Stackdriver d'OpenCensus.
- Initialisez l'exportateur Stackdriver.
- Utilisez l'API OpenCensus pour instrumenter votre code.
L'exemple suivant est un programme minimal qui écrit les données de métriques à l'aide d'OpenCensus. Le programme exécute une boucle et collecte les mesures de latence. Une fois la boucle terminée, il exporte les statistiques vers Cloud Monitoring et l'arrête:
Go
Java
Node.js
Python
Le programme crée une vue OpenCensus appelée task_latency_distribution
. Cette chaîne devient une partie du nom de la métrique lorsqu'elle est exportée vers Cloud Monitoring. Pour découvrir comment la view (vue) OpenCensus est réalisée en tant que descripteur de métrique Cloud Monitoring, consultez la section Récupérer des descripteurs de métrique.
Vous pouvez donc utiliser le nom de la view comme chaîne de recherche lors de la sélection d'une métrique à représenter graphiquement.
- Dans Google Cloud Console, accédez à la page Explorateur de métriques de Monitoring.
- Dans la barre d'outils, sélectionnez l'onglet Explorateur.
- Accédez à l'onglet Configuration.
- Développez le menu Sélectionner une métrique, saisissez
OpenCensus/task_latency_distribution
dans la barre de filtre, puis utilisez les sous-menus pour sélectionner un type de ressource et une métrique spécifiques :- Dans le menu Ressources actives, sélectionnez la ressource surveillée. Si vous exécutez le programme dans un environnement local, sélectionnez Global.
- Dans le menu Catégories de métriques actives, sélectionnez Personnalisées.
- Dans le menu Métriques actives, sélectionnez Répartition de la latence des tâches.
- Cliquez sur Appliquer.
- Facultatif : pour configurer l'affichage des données, ajoutez des filtres et utilisez les menus Grouper par, Agrégateur et type de graphique. Pour ce graphique, développez le menu Graphique en courbes, puis sélectionnez Graphique de carte de densité. Pour plus d'informations, consultez Sélectionner des métriques lors de l'utilisation de l'explorateur de métriques.
- Facultatif : modifiez les paramètres du graphique :
- Pour le quota et les autres métriques qui indiquent un échantillon par jour, définissez la période sur au moins une semaine et définissez le type de tracé sur Graphique à barres empilées.
- Pour les métriques à valeur de distribution, définissez le type de tracé sur Graphique de carte de densité.
Accéder à l'explorateur de métriques
La capture d'écran suivante montre la série temporelle collectée après l'exécution du programme sur un environnement local:
Chaque barre de la carte de densité représente une seule exécution du programme. Les composants colorés de chaque barre représentent les buckets de la répartition de la latence.
Lire les métriques OpenCensus dans Cloud Monitoring
Vous utilisez des métriques personnalisées, y compris celles qui sont écrites par OpenCensus, telles que les métriques intégrées. Vous pouvez les représenter sous forme de graphique, définir des alertes, les lire et les surveiller.
Cette section explique comment utiliser APIs Explorer pour lire les données de métriques. Pour savoir comment lire les données de métriques à l'aide de l'API Cloud Monitoring ou en utilisant des bibliothèques clientes, consultez les documents suivants:
- Parcourir les métriques explique comment répertorier et examiner vos métriques personnalisées et intégrées.
- Lire les métriques explique comment récupérer des données de séries temporelles à partir de métriques personnalisées et intégrées à l'aide de l'API Monitoring.
Par exemple, la capture d'écran de la section précédente provient de l'explorateur de métriques. Lorsque vous utilisez des outils de création de graphiques, nous vous recommandons d'utiliser le nom de la vue OpenCensus pour filtrer la liste des métriques. Pour plus d'informations, consultez Sélectionner des métriques lors de l'utilisation de l'explorateur de métriques.
Récupérer les descripteurs de métriques
Pour récupérer les données de métriques en utilisant directement l'API Monitoring, vous devez connaître les noms Cloud Monitoring vers lesquels les métriques OpenCensus ont été exportées. Pour déterminer ces noms, récupérez les descripteurs de métriques créés par l'exportateur, puis examinez le champ type
. Pour en savoir plus sur les descripteurs de métrique, consultez la page MetricDescriptor
.
Pour afficher les descripteurs de métriques créés pour les métriques exportées, procédez comme suit:
- Accédez à la page de référence sur
metricDescriptors.list
. Dans le widget Essayer cette API de la page de référence, renseignez les champs suivants:
Saisissez le nom de votre projet dans le champ
name
. Utilisez la structure de noms suivante :projects/PROJECT_ID
. Ce document utilise un projet portant l'IDa-gcp-project
.Saisissez un filtre dans le champ
filter
. Un projet comporte de nombreux descripteurs de métriques. Le filtrage vous permet d'éliminer les descripteurs qui ne vous intéressent pas.Par exemple, comme le nom de la vue OpenCensus fait partie du nom de la métrique, vous pouvez ajouter un filtre de ce type:
metric.type=has_substring("task_latency_distribution")
La clé
metric.type
est un champ de type intégré dans une série temporelle. Pour en savoir plus, consultez la pageTimeSeries
.Cliquez sur Exécuter.
Les lignes suivantes affichent le descripteur de métrique renvoyé :
{ "metricDescriptors": [ { "name": "projects/a-gcp-project/metricDescriptors/custom.googleapis.com/opencensus/task_latency_distribution", "labels": [ { "key": "opencensus_task", "description": "Opencensus task identifier" } ], "metricKind": "CUMULATIVE", "valueType": "DISTRIBUTION", "unit": "ms", "description": "The distribution of the task latencies", "displayName": "OpenCensus/task_latency_distribution", "type": "custom.googleapis.com/opencensus/task_latency_distribution" } ] }
Cette ligne du descripteur de métrique indique le nom du type de métrique dans Cloud Monitoring :
"type": "custom.googleapis.com/opencensus/task_latency_distribution"
Vous disposez maintenant des informations nécessaires pour récupérer manuellement les données associées au type de métrique. La valeur du champ type
s'affiche également dans Google Cloud Console lorsque vous graphiquez la métrique.
Récupérer les données de métriques
Pour récupérer manuellement les données de séries temporelles à partir d'un type de métrique, procédez comme suit:
- Accédez à la page de référence
timeSeries.list
. Dans le widget Essayer cette API de la page de référence, renseignez les champs suivants:
- Saisissez le nom de votre projet dans le champ
name
. Utilisez la structure de noms suivante :projects/PROJECT_ID
. Dans le champ
filter
, saisissez la valeur suivante :metric.type="custom.googleapis.com/opencensus/task_latency_distribution"
Saisissez les valeurs dans les champs
interval.startTime
etinterval.endTime
. Ces valeurs doivent être saisies sous forme d'horodatage (par exemple,2018-10-11T15:48:38-04:00
). Assurez-vous que la valeurstartTime
est antérieure à la valeurendTime
.Cliquez sur le bouton Execute (Exécuter).
- Saisissez le nom de votre projet dans le champ
Les lignes suivantes affichent le résultat d'une récupération de ce type :
{ "timeSeries": [ { "metric": { "labels": { "opencensus_task": "java-3424@docbuild" }, "type": "custom.googleapis.com/opencensus/task_latency_distribution" }, "resource": { "type": "gce_instance", "labels": { "instance_id": "2455918024984027105", "zone": "us-east1-b", "project_id": "a-gcp-project" } }, "metricKind": "CUMULATIVE", "valueType": "DISTRIBUTION", "points": [ { "interval": { "startTime": "2019-04-04T17:49:34.163Z", "endTime": "2019-04-04T17:50:42.917Z" }, "value": { "distributionValue": { "count": "100", "mean": 2610.11, "sumOfSquaredDeviation": 206029821.78999996, "bucketOptions": { "explicitBuckets": { "bounds": [ 0, 100, 200, 400, 1000, 2000, 4000 ] } }, "bucketCounts": [ "0", "0", "1", "6", "13", "15", "44", "21" ] } } } ] }, [ ... data from additional program runs deleted ...] ] }
Les données de métriques renvoyées incluent les éléments suivants:
- Informations relatives à la ressource surveillée sur laquelle les données ont été collectées
OpenCensus peut détecter automatiquement les ressources surveillées
gce_instance
,k8s_container
etaws_ec2_instance
. Ces données provenaient d'un programme exécuté sur une instance de Compute Engine. Pour en savoir plus sur l'utilisation d'autres ressources surveillées, consultez la page Définir une ressource surveillée pour l'exportateur. - Description du type de métrique et du type des valeurs
- Les points de données réels collectés dans l'intervalle de temps demandé
Surveillance des métriques OpenCensus par Monitoring
L'utilisation directe de l'API Cloud Monitoring est compatible avec les métriques personnalisées. Elle est décrite dans la section Créer des métriques personnalisées à l'aide de l'API. En fait, l'exportateur OpenCensus pour Cloud Monitoring utilise cette API pour vous. Cette section fournit des informations sur la manière dont Cloud Monitoring représente les métriques écrites par OpenCensus.
Les constructions utilisées par l'API OpenCensus diffèrent de celles utilisées par Cloud Monitoring, de même que la terminologie employée. Lorsque Cloud Monitoring fait référence à des "métriques", OpenCensus fait parfois référence à des "stats" (statistiques). Par exemple, le composant OpenCensus qui envoie des données métriques à Cloud Monitoring est appelé "stats exporter for Stackdriver" (exportateur de stats pour Stackdriver).
Pour en savoir plus sur le modèle OpenCensus pour les métriques, consultez la section Métriques OpenCensus.
Les modèles de données pour les stats OpenCensus et les métriques Stackdriver Monitoring n'affichent pas une correspondance parfaite. Bon nombre des mêmes concepts existent chez chacun, mais ils ne sont pas directement interchangeables.
Une vue OpenCensus est semblable à
MetricDescriptor
dans l'API Monitoring. Elle décrit la manière de collecter et d'agréger des "measurements" individuels. Les balises sont incluses avec toutes les mesures enregistrées.Un tag (balise) OpenCensus est une paire clé/valeur, Une balise OpenCensus correspond généralement à la propriété
LabelDescriptor
de l'API Monitoring. Les tags vous permettent de capturer des informations contextuelles que vous pouvez utiliser pour filtrer et regrouper des métriques.Une measure (type de mesure) OpenCensus décrit les données métriques à enregistrer. Une aggregation (agrégation) OpenCensus est une fonction appliquée aux données utilisées pour les résumer. Ces fonctions sont utilisées pour l'exportation afin de déterminer le
MetricKind
, leValueType
et l'unité indiqués dans le descripteur de métrique Cloud Monitoring.Une mesure OpenCensus est un point de données collecté. Les measurements doivent être agrégées dans des views. Sinon, les measurements individuels sont supprimés. Une mesure OpenCensus est semblable à un
Point
dans l'API Monitoring. Lorsque les measurements sont agrégés dans des views, les données agrégées sont stockées en tant que view data (données de vue), à la manière d'une ressourceTimeSeries
dans l'API Monitoring.
Étapes suivantes
OpenCensus fournit la documentation de référence primaire pour son API relative aux métriques et pour l'exportateur Stackdriver. Le tableau suivant fournit des liens vers ces documents de référence :
Langage Documentation de référence sur les API Documentation sur l'exportateur Guide de démarrage rapide Go API Go Stats and Trace Exporters (Exportateurs de statistiques et de traces) Métriques Java API Java Stats Exporter (Exportateur de statistiques) Métriques NodeJS API NodeJS Stats Exporter (Exportateur de statistiques) Métriques Python API Python Stats Exporter (Exportateur de statistiques) Métriques