Configurer Cloud Trace pour Ruby

Vous pouvez activer Cloud Trace pour les applications Ruby à l'aide de la bibliothèque Cloud Trace pour Ruby.

Installer la bibliothèque

Installez Ruby 2.2+ ou une version ultérieure.
Ajoutez le gem Stackdriver à votre fichier Gemfile :
```
gem "stackdriver"
```
Utilisez Bundler pour installer le gem :
```
bundle install
```

Activer la bibliothèque

Rails

Si vous utilisez Ruby on Rails, Bundler charge automatiquement la bibliothèque dans votre application quand elle démarre.

Sans Rails

D'autres applications basées sur Rack peuvent utiliser l'intergiciel Rack fourni par la bibliothèque :

require "google/cloud/trace"

use Google::Cloud::Trace::Middleware

Pour en savoir plus ou pour signaler des problèmes avec la bibliothèque, consultez le dépôt du code source de la bibliothèque.

Configurer le client

Vous pouvez personnaliser le comportement de la bibliothèque Cloud Trace pour Ruby. Consultez la configuration de la bibliothèque pour connaître la liste des options de configuration possibles.

Ajouter un délai de trace personnalisé

La bibliothèque Cloud Trace pour Ruby crée automatiquement un enregistrement de trace pour chaque requête reçue par votre application Rack. Vous pouvez également ajouter des délais de trace personnalisés à chaque requête :

Google::Cloud::Trace.in_span "my_task" do |_span|
  # Insert task

  Google::Cloud::Trace.in_span "my_subtask" do |subspan|
    # Insert subtask
  end
end

Configurer votre plate-forme

Vous pouvez utiliser Cloud Trace sur Google Cloud et d'autres plates-formes.

Exécuter des applications sur Google Cloud

Lorsque votre application s'exécute sur Google Cloud, vous n'avez pas besoin de fournir des identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Cependant, vous devez vous assurer que le niveau d'accès de l'API Cloud Trace est activé sur votre plate-forme Google Cloud.

Pour obtenir la liste des environnements Google Cloud compatibles, consultez la page Environnements compatibles.

Pour les configurations suivantes, les paramètres de niveau d'accès par défaut activent l'API Cloud Trace :

Environnement flexible App Engine
Environnement standard App Engine
Google Kubernetes Engine (GKE)

Remarque :Si vous utilisez Autopilot ou si vous activez Workload Identity pour votre cluster GKE, veillez à configurer votre application pour utiliser Workload Identity.
Compute Engine
Cloud Run

Si vous utilisez des niveaux d'accès personnalisés, assurez-vous que le niveau d'accès de l'API Cloud Trace est activé :

Pour en savoir plus sur la configuration des niveaux d'accès pour votre environnement à l'aide de la console Google Cloud, consultez la page Configurer votre projet Google Cloud.
Pour les utilisateurs gcloud, spécifiez les niveaux d'accès à l'aide de l'indicateur --scopes et incluez le niveau d'accès à l'API Cloud Trace trace.append. Par exemple, pour créer un cluster GKE avec uniquement l'API Cloud Trace activée, procédez comme suit :
```
gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append
```

Exécuter en local et depuis un autre emplacement

Si votre application s'exécute en dehors de Google Cloud, vous devez fournir les identifiants d'authentification sous la forme d'un compte de service à la bibliothèque cliente. Le compte de service doit contenir le rôle d'agent Cloud Trace. Pour savoir comment faire, consultez la page Créer un compte de service.

Les bibliothèques clientes Google Cloud pour Ruby utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application. La section suivante explique comment définir ces identifiants et l'ID du projet Google Cloud.

Définir l'ID et les identifiants de projet Google Cloud

Cette section décrit trois approches différentes que vous pouvez utiliser pour définir l'ID de projet Google Cloud, les identifiants d'authentification ou les deux dans votre application Ruby.

Variable d'environnement

Lorsque vous ne définissez pas explicitement l'ID du projet Google Cloud, la bibliothèque Ruby google-cloud détermine automatiquement si la variable d'environnement GOOGLE_CLOUD_PROJECT est définie et, le cas échéant, utilise la valeur GOOGLE_CLOUD_PROJECT comme ID de projet Google Cloud. Pour en savoir plus, consultez la page Authentification.

Comme décrit précédemment, les bibliothèques clientes Google Cloud utilisent les identifiants par défaut de l'application (ADC) pour trouver les identifiants de votre application. Vous pouvez fournir ces identifiants en définissant la variable d'environnement GOOGLE_APPLICATION_CREDENTIALS :

Linux/macOS

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Windows

Fenêtre de commande :

set GOOGLE_CLOUD_PROJECT=your-project-id
set GOOGLE_APPLICATION_CREDENTIALS=/path/to/key.json

Powershell :

$env:GOOGLE_CLOUD_PROJECT="your-project-id"
$env:GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"

Interface de configuration de Ruby on Rails

Si vous utilisez Ruby on Rails, vous pouvez fournir les paramètres via l'interface de configuration de Ruby on Rails :

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Trace specific parameters
  config.google_cloud.trace.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.trace.keyfile    = "/path/to/service-account.json"
end

Vous pouvez également définir une configuration partagée pour tous les gems Stackdriver à l'aide de la commande suivante :

# Add this to config/environments/*.rb
Rails.application.configure do |config|
  # Stackdriver Shared parameters
  config.google_cloud.project_id = "YOUR-PROJECT-ID"
  config.google_cloud.keyfile    = "/path/to/service-account.json"
end

Trace est activé par défaut lorsque Rails est exécuté en mode de production. Pour activer Trace en mode de développement, ajoutez les éléments suivants :

# Add this to config/environments/development.rb
Rails.application.configure do |config|
  config.google_cloud.use_trace = true
end

Interface de configuration de l'instrumentation

Une autre possibilité pour Ruby consiste à fournir les paramètres via l'interface de configuration lorsqu'ils sont utilisés dans d'autres applications basées sur Rack :

require "google/cloud/trace"

Google::Cloud.configure do |config|
  # Stackdriver Trace specific parameters
  config.trace.project_id = "YOUR-PROJECT-ID"
  config.trace.keyfile    = "/path/to/service-account.json"
end

Vous pouvez également définir une configuration partagée pour tous les gems Stackdriver en utilisant :

require "stackdriver"

Google::Cloud.configure do |config|
  # Stackdriver Shared parameters
  config.project_id = "YOUR-PROJECT-ID"
  config.keyfile    = "/path/to/service-account.json"
end

Afficher les traces

Dans le panneau de navigation de la console Google Cloud, sélectionnez Trace, puis Explorateur Trace:

Accéder à Explorateur Trace

Dépannage

Pour en savoir plus sur la résolution des problèmes liés à Cloud Trace, consultez la page Dépannage.