ddtrace est le client de tracing de Datadog pour Ruby. Il permet de tracer les requêtes qui transitent par vos serveurs Web, bases de données et microservices, offrant ainsi aux développeurs une visibilité optimale sur les goulots d’étranglement et les requêtes problématiques.

Prise en main

Si vous effectuez une mise à niveau depuis une version 0.x, consultez notre guide dédié.

Pour la documentation générale sur l’APM, consultez la documentation relative à la configuration.

Pour découvrir comment APM se présente une fois que votre application a commencé à envoyer des informations à Datadog, consultez la section relative aux termes et concepts.

Pour vous familiariser avec l’API de la bibliothèque, consultez notre documentation YARD.

Pour contribuer au code, consultez les règles de contribution et le guide de développement.

Table des matières

• Compatibilité
• Installation
  • Configurer l’Agent Datadog pour le tracing
  • Instrumenter votre application
    • Applications Rails ou Hanami
    • Autres applications Ruby
    • Configurer OpenTracing
    • Configurer OpenTelemetry
  • Associer votre application à l’Agent Datadog
• Instrumentation manuelle
• Instrumenter des intégrations
  • Action Cable
  • Action Mailer
  • Action Pack
  • Action View
  • Active Job
  • Active Model Serializers
  • Active Record
  • Active Support
  • AWS
  • Concurrent Ruby
  • Cucumber
  • Dalli
  • DelayedJob
  • Elasticsearch
  • Ethon et Typhoeus
  • Excon
  • Faraday
  • Grape
  • GraphQL
  • gRPC
  • Hanami
  • http.rb
  • httpclient
  • httpx
  • Kafka
  • MongoDB
  • MySQL2
  • Net/HTTP
  • Postgres
  • Presto
  • Qless
  • Que
  • Racecar
  • Rack
  • Rails
  • Rake
  • Redis
  • Resque
  • Rest Client
  • RSpec
  • Sequel
  • Shoryuken
  • Sidekiq
  • Sinatra
  • Sneakers
  • Stripe
  • Sucker Punch
• Configuration supplémentaire
  • Logging personnalisé
  • Environnement et tags
  • Debugging et diagnostic
  • Échantillonnage
    • Échantillonnage côté application
    • Échantillonnage prioritaire
    • Échantillonnage de spans uniques
  • Tracing distribué
  • Mise en file d’attente des requêtes HTTP
  • Pipeline de traitement
    • Filtrage
    • Traitement
  • Mise en corrélation des traces
  • Configurer la couche de transport
  • Métriques
    • [Métriques runtime d’application](#metriques-((runtime-d-application)
  • OpenTracing
  • Profiling
    • Dépannage
    • Profiling des tâches Resque
• Problèmes connus et configurations suggérées
  • Charge utile trop volumineuse
  • Erreur Stack level too deep

Compatibilité

Interpréteurs Ruby pris en charge :

Serveurs Web pris en charge :

Frameworks de tracing pris en charge :

Complète indique que toutes les fonctionnalités du traceur sont prises en charge.

Obsolète indique que la prise en charge passera à Maintenance dans une prochaine version.

Maintenance indique que seules les corrections de bugs critiques seront backportées jusqu’à la fin de vie.

Fin de vie indique que le service n’est plus pris en charge.

Prise en charge par macOS (Apple)

L’utilisation de ddtrace sous macOS est prise en charge à des fins de développement, mais pas pour des déploiements en production.

Prise en charge par Microsoft Windows

Microsoft Windows ne prend actuellement pas en charge ddtrace. Nous acceptons les contributions de la communauté et les problèmes associés, mais ils ne sont pas prioritaires.

Installation

Il vous suffit de suivre quelques étapes rapides pour pouvoir tracer votre application Ruby :

1. Configurer l’Agent Datadog pour le tracing
2. Instrumenter votre application
3. Associer votre application à l’Agent Datadog

Configurer l’Agent Datadog pour le tracing

Avant d’installer ddtrace, installez l’Agent Datadog afin que ddtrace puisse lui envoyer des données de trace.

Configurez ensuite l’Agent Datadog de façon à ce qu’il accepte les traces. Pour ce faire, effectuez l’une des opérations suivantes :

• Définissez DD_APM_ENABLED=true dans l’environnement de l’Agent.

OU

• Ajoutez apm_enabled: true dans le fichier de configuration de l’Agent.

De plus, dans les environnement conteneurisés…

• Définissez DD_APM_NON_LOCAL_TRAFFIC=true dans l’environnement de l’Agent.

OU

• Ajoutez apm_non_local_traffic: true dans le fichier de configuration de l’Agent.

Consultez les instructions de configuration spécifiques pour Docker, Kubernetes, Amazon ECS ou Fargate pour vérifier que l’Agent est configuré de façon à recevoir des traces dans un environnement conteneurisé.

Configurer l’ingestion des données de trace

L’Agent Datadog détecte par défaut les traces via HTTP sur le port 8126.

Pour modifier le protocole ou le port utilisés pour la détection des données de trace par l’Agent, procédez comme suit :

Pour une détection HTTP via TCP :

• Définissez DD_APM_RECEIVER_PORT=<port> dans l’environnement de l’Agent.

OU

• Ajoutez apm_config: receiver_port: <port> dans le fichier de configuration de l’Agent.

Pour un socket de domaine Unix (UDS) :

• Définissez DD_APM_RECEIVER_SOCKET=<chemin-vers-fichier-socket>.

OU

• Ajoutez apm_config: receiver_socket: <chemin-vers-fichier-socket> dans le fichier de configuration de l’Agent.

Instrumenter votre application

Applications Rails ou Hanami

1. Ajoutez le gem ddtrace à votre fichier Gem :

   source 'https://rubygems.org'
   gem 'ddtrace', require: 'ddtrace/auto_instrument'
   

2. Installez le gem avec bundle install.

3. Créez un fichier config/initializers/datadog.rb contenant :

   Datadog.configure do |c|
     # Add additional configuration here.
     # Activate integrations, change tracer settings, etc...
   end
   

   Grâce à ce bloc, vous pouvez :

   • ajouter des paramètres de configuration supplémentaires ;
   • activer ou reconfigurer l’instrumentation.

Autres applications Ruby

Si votre application n’utilise pas les gems pris en charge (Rails ou Hanami) qui sont indiqués ci-dessus, vous pouvez la configurer comme suit :

1. Ajoutez le gem ddtrace à votre fichier Gem :

   source 'https://rubygems.org'
   gem 'ddtrace'
   

2. Installez le gem avec bundle install.

3. Utilisez require pour exiger les bibliothèques ou frameworks pris en charge à instrumenter.

4. Ajoutez require 'ddtrace/auto_instrument' à votre application. _Remarque : effectuez cette opération après avoir exigé les bibliothèques ou frameworks pris en charge.

   # Example frameworks and libraries
   require 'sinatra'
   require 'faraday'
   require 'redis'
   
   require 'ddtrace/auto_instrument'
   

5. Ajoutez un bloc de configuration à votre application :

   Datadog.configure do |c|
     # Add additional configuration here.
     # Activate integrations, change tracer settings, etc...
   end
   

   Grâce à ce bloc, vous pouvez :

   • ajouter des paramètres de configuration supplémentaires ;
   • activer ou reconfigurer l’instrumentation.

Configurer OpenTracing

1. Ajoutez le gem ddtrace à votre fichier Gem :

   source 'https://rubygems.org'
   gem 'ddtrace'
   

2. Installez le gem avec bundle install.

3. Ajoutez ce qui suit à votre fichier de configuration OpenTracing :

   require 'opentracing'
   require 'datadog/tracing'
   require 'datadog/opentracer'
   
   # Activate the Datadog tracer for OpenTracing
   OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new
   

4. Ajoutez un bloc de configuration à votre application :

   Datadog.configure do |c|
     # Configure the Datadog tracer here.
     # Activate integrations, change tracer settings, etc...
     # By default without additional configuration,
     # no additional integrations will be traced, only
     # what you have instrumented with OpenTracing.
   end
   

   Grâce à ce bloc, vous pouvez :

   • ajouter des paramètres de configuration Datadog supplémentaires ;
   • activer ou reconfigurer l’instrumentation Datadog.

Configurer OpenTelemetry

Vous pouvez envoyer directement des traces OpenTelemetry à l’Agent Datadog (sans ddtrace) avec OTLP. Consultez notre documentation sur l’ingestion OTLP dans l’Agent Datadog pour en savoir plus.

Associer votre application à l’Agent Datadog

Par défaut, ddtrace se connecte à l’Agent à l’aide des premiers paramètres disponibles, selon les priorités indiquées :

1. Via les paramètres de configuration explicitement fournis (hostname, port et transport)
2. Via le socket de domaine Unix (UDS) situé à l’emplacement /var/run/datadog/apm.socket
3. À l’aide du protocole HTTP via TCP sur 127.0.0.1:8126

Si votre Agent Datadog effectue une écoute à l’un de ces emplacements, aucune configuration supplémentaire n’est requise.

Si votre Agent s’exécute sur un autre host ou conteneur que votre application, ou si vous souhaitez envoyer des traces via un autre protocole, vous devez configurer votre application en conséquence.

• Comment envoyer des données de trace à l’Agent à l’aide du protocole HTTP via TCP
• Comment envoyer des traces à l’Agent via un socket de domaine Unix (UDS)

Dernières étapes d’installation

Une fois la configuration terminée, vos services commencent à apparaître sur la page des services APM après quelques minutes. Pour apprendre à utiliser l’IU de l’APM, cliquez ici.

Instrumentation manuelle

Si le framework que vous utilisez n’est pas pris en charge, vous pouvez choisir d’instrumenter manuellement votre code.

Pour tracer du code Ruby, vous pouvez utiliser la méthode Datadog::Tracing.trace :

Datadog::Tracing.trace(name, **options) do |span, trace|
  # Incorporer le code que vous souhaitez instrumenter dans ce bloc
  # La span peut également être modifiée ici
  # Exemple : changement de nom de ressource, définition de tags, etc.
end

Assurez-vous de remplacer name par une string décrivant le type d’opération effectuée (p. ex. 'web.request' ou 'request.parse')

options correspond aux arguments de mot-clé facultatifs suivants :

Nous vous conseillons fortement de définir un service et une resource au strict minimum. Les spans sans service ou resource (nil) seront ignorées par l’Agent Datadog.

Exemple d’instrumentation manuelle :

get '/posts' do
  Datadog::Tracing.trace('web.request', service: 'my-blog', resource: 'GET /posts') do |span|
    # Tracer l'appel activerecord
    Datadog::Tracing.trace('posts.fetch') do
      @posts = Posts.order(created_at: :desc).limit(10)
    end

    # Ajouter des tags APM
    span.set_tag('http.method', request.request_method)
    span.set_tag('posts.count', @posts.length)

    # Tracer le rendu du modèle
    Datadog::Tracing.trace('template.render') do
      erb :index
    end
  end
end

Tracing asynchrone

Il n’est pas toujours possible d’utiliser Datadog::Tracing.trace autour d’un bloc de code. Il arrive que certaines instrumentations basées sur des événements ou des notifications ne vous notifient qu’au début ou à la fin d’un événement.

Pour tracer ces opérations, vous pouvez tracer le code de façon asynchrone en appelant Datadog::Tracing.trace sans bloc :

# Certains frameworks d'instrumentation appellent ce qui suit après la fin d'un événement…
def db_query(start, finish, query)
  span = Datadog::Tracing.trace('database.query', start_time: start)
  span.resource = query
  span.finish(finish)
end

Lorsque vous appelez Datadog::Tracing.trace sans bloc, la Datadog::Tracing::SpanOperation renvoyée par la fonction est initialisée, mais pas finalisée. Vous pouvez ensuite modifier cette span comme bon vous semble, puis la finaliser avec finish.

Toutes les spans doivent être finalisées. Si une span est encore ouverte alors que la trace se termine, cette dernière sera ignorée. Si vous pensez que l’une de vos traces n’est pas finalisée, activez le mode debugging afin de visualiser les avertissements.

Pour éviter ce problème lorsque vous avez recours à des événements d’initialisation et de finalisation, utilisez Datadog::Tracing.active_span pour récupérer la span active.

# Exemple : ActiveSupport::Notifications appelle ce qui suit au début d'un événement
def start(name, id, payload)
  # Démarrer une span
  Datadog.Tracing.trace(name)
end

# Exemple : ActiveSupport::Notifications appelle ce qui suit à la fin d'un événement
def finish(name, id, payload)
  # Récupérer la span active (thread-safe)
  current_span = Datadog.Tracing.active_span
  unless current_span.nil?
    current_span.resource = payload[:query]
    current_span.finish
  end
end

Enrichir les traces à l’aide de méthodes imbriquées

Vous pouvez ajouter des informations supplémentaires sous forme de tags à la span active en utilisant la méthode de votre choix. Attention : si la méthode est appelée et qu’aucune span n’est active, active_span est défini sur nil.

# Exemple : ajouter un tag à la span active

current_span = Datadog::Tracing.active_span
current_span.set_tag('my_tag', 'my_value') unless current_span.nil?

Vous pouvez également récupérer la span active en utilisant la méthode active_trace. Cette méthode renverra nil si aucune trace n’est active.

# exemple : accéder à la trace active

current_trace = Datadog::Tracing.active_trace

Instrumenter des intégrations

Un vaste nombre de bibliothèques et de frameworks sont pris en charge par défaut, ce qui signifie qu’ils peuvent être instrumentés automatiquement. Ces instrumentations ne sont pas activées par défaut, mais elles peuvent facilement être activées et configurées avec l’API Datadog.configure :

Datadog.configure do |c|
  # Activer et configurer une intégration
  c.tracing.instrument :integration_name, **options
end

options correspond aux arguments de mot-clé pour la configuration propre aux intégrations.

Vous trouverez ci-dessous la liste des intégrations disponibles ainsi que leurs options de configuration :

CI Visibility

Pour la solution CI Visibility Datadog, il est possible d’activer et de configurer l’instrumentation de bibliothèque à l’aide de l’API Datadog.configure suivante :

Datadog.configure do |c|
  # Activer et configurer une intégration
  c.ci.instrument :integration_name, **options
end

options correspond aux arguments de mot-clé pour la configuration propre aux intégrations.

Voici la liste des intégrations CI Visibility disponibles :

Action Cable

L’intégration Action Cable permet de tracer les messages des broadcasts et les actions effectuées sur un canal.

Vous pouvez l’activer via Datadog.configure :

require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :action_cable
end

Action Mailer

L’intégration Action Mailer permet de tracer les actions ActionMailer pour la version 5 de Rails.

Vous pouvez l’activer via Datadog.configure :

require 'ddtrace'
Datadog.configure do |c|
  c.tracing.instrument :action_mailer, **options
end

options correspond aux arguments de mot-clé suivants :

Action Pack

Action Pack est généralement configuré en même temps que Rails, mais il est possible de l’activer séparément :

require 'actionpack'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :action_pack
end

Action View

Action View est généralement configuré en même temps que Rails, mais il est possible de l’activer séparément :

require 'actionview'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :action_view, **options
end

options correspond aux arguments de mot-clé suivants :

Active Job

Active Job est généralement configuré en même temps que Rails, mais il est possible de l’activer séparément :

require 'active_job'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :active_job
end

ExampleJob.perform_later

Active Model Serializers

L’intégration Active Model Serializers permet de tracer l’événement serialize pour les versions 0.9+ et l’événement render pour les versions 0.10+.

require 'active_model_serializers'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :active_model_serializers
end

my_object = MyModel.new(name: 'my object')
ActiveModelSerializers::SerializableResource.new(test_obj).serializable_hash

Active Record

Active Record est généralement configuré en même temps qu’un framework Web (tel que Rails ou Sinatra), mais il est possible de le configurer séparément :

require 'tmpdir'
require 'sqlite3'
require 'active_record'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :active_record, **options
end

Dir::Tmpname.create(['test', '.sqlite']) do |db|
  conn = ActiveRecord::Base.establish_connection(adapter: 'sqlite3',
                                                 database: db)
  conn.connection.execute('SELECT 42') # traced!
end

options correspond aux arguments de mot-clé suivants :

Configurer les paramètres de tracing par base de données

Il est possible de configurer les paramètres de tracing par connexion de base de données via l’option describes :

# Ajouter une option `:describes` avec une clé de connexion.
# Toutes les clés suivantes sont acceptées et fonctionnent de façon similaire.
# Si un bloc est spécifié, cela renvoie un objet Settings
# qui accepte toutes les options de configuration énumérées ci-dessus.

Datadog.configure do |c|
  # Symbole correspondant à votre connexion de base de données dans config/database.yml
  # Uniquement disponible si vous utilisez Rails avec Active Record.
  c.tracing.instrument :active_record, describes: :secondary_database, service_name: 'secondary-db'

  # Modèle de configuration du bloc.
  c.tracing.instrument :active_record, describes: :secondary_database do |second_db|
    second_db.service_name = 'secondary-db'
  end

  # Chaîne de connexion avec les paramètres de connexion suivants :
  # adapter, username, host, port et database.
  # Les autres champs sont ignorés.
  c.use :active_record, describes: 'mysql2://root@127.0.0.1:3306/mysql', service_name: 'secondary-db'

  # Hash avec les paramètres de connexion suivants :
  # adapter, username, host, port, database.
  # Les autres champs sont ignorés.
  c.tracing.instrument :active_record, describes: {
      adapter:  'mysql2',
      host:     '127.0.0.1',
      port:     '3306',
      database: 'mysql',
      username: 'root'
    },
    service_name: 'secondary-db'

  # Si vous utilisez le gem `makara`, il est possible de faire correspondre la connexion `role` :
  c.use :active_record, describes: { makara_role: 'primary' }, service_name: 'primary-db'
  c.use :active_record, describes: { makara_role: 'replica' }, service_name: 'secondary-db'
end

Vous pouvez également créer des configurations basées sur les correspondances partielles de champs de connexion de base de données :

Datadog.configure do |c|
  # Correspond à n'importe quelle connexion sur le host `127.0.0.1`.
 c.tracing.instrument :active_record, describes: { host:  '127.0.0.1' }, service_name: 'local-db'

  # Correspond à n'importe quelle connexion `mysql2`.
  c.tracing.instrument :active_record, describes: { adapter: 'mysql2'}, service_name: 'mysql-db'

  # Correspond à n'importe quelle connexion `mysql2` à la base de données `reports`.
  #
  # Si plusieurs configurations `describe` correspondent, seule la dernière s'applique.
  # Ici, une connexion avec l'adaptateur `mysql` et la base de données `reports`
  # sera configurée avec `service_name: 'reports-db'`, et non `service_name: 'mysql-db'`.
  c.tracing.instrument :active_record, describes: { adapter: 'mysql2', database:  'reports'}, service_name: 'reports-db'
end

Lorsque plusieurs configurations describes correspondent à une connexion, la dernière règle configurée qui correspond est appliquée.

Si Active Record trace un événement qui utilise une connexion qui correspond à une clé définie par describes, les paramètres de tracing associés à cette connexion sont utilisés. Si la connexion ne correspond à aucune des connexions décrites, les paramètres par défaut définis par c.tracing.instrument :active_record sont utilisés à la place.

Active Support

Active Support est généralement configuré en même temps que Rails, mais il est possible de l’activer séparément :

require 'activesupport'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :active_support, **options
end

cache = ActiveSupport::Cache::MemoryStore.new
cache.read('city')

options correspond aux arguments de mot-clé suivants :

AWS

L’intégration AWS permet de tracer l’ensemble des interactions (tels que les appels d’API) avec les services AWS (S3, ElastiCache etc.).

require 'aws-sdk'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :aws, **options
end

# Exécuter l'appel tracé
Aws::S3::Client.new.list_buckets

options correspond aux arguments de mot-clé suivants :

Concurrent Ruby

L’intégration Concurrent Ruby ajoute la prise en charge de la propagation de contexte lorsque ::Concurrent::Future est utilisé. De cette façon, il est possible de s’assurer que le code tracé dans Future#execute est associé au bon parent.

Pour activer votre intégration, utilisez la méthode Datadog.configure :

# Dans l'initialiseur Rails ou un équivalent
Datadog.configure do |c|
  # Patcher ::Concurrent::Future pour utiliser un ExecutorService qui propage le contexte
  c.tracing.instrument :concurrent_ruby
end

# Passer le context au code exécuté dans Concurrent::Future
Datadog::Tracing.trace('outer') do
  Concurrent::Future.execute { Datadog::Tracing.trace('inner') { } }.wait
end

Cucumber

Lorsque vous utilisez le framework cucumber, l’intégration Cucumber trace toutes les exécutions de scénarios et d’étapes.

Pour activer votre intégration, utilisez la méthode Datadog.configure :

require 'cucumber'
require 'ddtrace'

# Configurer l'intégration Cucumber par défaut
Datadog.configure do |c|
  c.ci.instrument :cucumber, **options
end

# L'exemple suivant décrit comment appliquer des tags provenant d'un scénario à la span active
Around do |scenario, block|
  active_span = Datadog.configuration[:cucumber][:tracer].active_span
  unless active_span.nil?
    scenario.tags.filter { |tag| tag.include? ':' }.each do |tag|
      active_span.set_tag(*tag.name.split(':', 2))
    end
  end
  block.call
end

options correspond aux arguments de mot-clé suivants :

Dalli

L’intégration Dalli permet de tracer l’ensemble des appels à votre serveur memcached :

require 'dalli'
require 'ddtrace'

# Configurer le comportement de tracing de Dalli par défaut
Datadog.configure do |c|
  c.tracing.instrument :dalli, **options
end

# Configurer le comportement de tracing de Dalli pour un client spécifique
client = Dalli::Client.new('localhost:11211', **options)
client.set('abc', 123)

options correspond aux arguments de mot-clé suivants :

DelayedJob

L’intégration DelayedJob utilise des hooks de cycle de vie pour tracer les exécutions de tâches et les mises en file d’attente.

Vous pouvez l’activer via Datadog.configure :

require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :delayed_job, **options
end

options correspond aux arguments de mot-clé suivants :

Elasticsearch

L’intégration Elasticsearch permet de tracer n’importe quel appel à perform_request depuis l’objet Client :

require 'elasticsearch/transport'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :elasticsearch, **options
end

# Envoyer une requête à Elasticsearch
client = Elasticsearch::Client.new url: 'http://127.0.0.1:9200'
response = client.perform_request 'GET', '_cluster/health'

# Si vous souhaitez utiliser des paramètres différents pour une instance client spécifique
Datadog.configure_onto(client.transport, **options)

options correspond aux arguments de mot-clé suivants :

Ethon

L’intégration ethon permet de tracer n’importe quelle requête HTTP par le biais d’objets Easy ou Multi. Notez que cette intégration prend également en charge la bibliothèque Typhoeus, qui est basée sur Ethon.

require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :ethon, **options

  # Si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression régulière
  c.tracing.instrument :ethon, describes: /user-[^.]+\.example\.com/ do |ethon|
    ethon.service_name = 'user.example.com'
    ethon.split_by_domain = false # Uniquement nécessaire si split_by_domain prend par défaut la valeur true
  end
end

options correspond aux arguments de mot-clé suivants :

Excon

L’intégration excon est disponible via le middleware ddtrace :

require 'excon'
require 'ddtrace'

# Configurer le comportement de tracing d'Excon par défaut
Datadog.configure do |c|
  c.tracing.instrument :excon, **options

  # Si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression régulière
  c.tracing.instrument :excon, describes: /user-[^.]+\.example\.com/ do |excon|
    excon.service_name = 'user.example.com'
    excon.split_by_domain = false # Uniquement nécessaire si split_by_domain prend par défaut la valeur true
  end
end

connection = Excon.new('https://example.com')
connection.get

options correspond aux arguments de mot-clé suivants :

Configurer des paramètres différents pour chaque connexion

Si vous utilisez plusieurs connexions avec Excon, vous pouvez définir des paramètres différents pour chaque connexion en configurant leurs constructeurs avec un middleware :

# Incorporer la pile de middlewares par défaut dans le middleware de tracing Datadog
Excon.new(
  'http://example.com',
  middlewares: Datadog::Tracing::Contrib::Excon::Middleware.with(options).around_default_stack
)

# Insérer le middleware dans une pile de middlewares personnalisée.
# Remarque : le middleware de tracing doit être inséré après le ResponseParser !
Excon.new(
  'http://example.com',
  middlewares: [
    Excon::Middleware::ResponseParser,
    Datadog::Tracing::Contrib::Excon::Middleware.with(options),
    Excon::Middleware::Idempotent
  ]
)

Où options est un hash pouvant contenir n’importe quel paramètre énuméré dans le tableau ci-dessus.

Faraday

L’intégration faraday est disponible via le middleware ddtrace :

require 'faraday'
require 'ddtrace'

# Configurer le comportement de tracing de Faraday par défaut
Datadog.configure do |c|
  c.tracing.instrument :faraday, **options

  # Si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression régulière
  c.tracing.instrument :faraday, describes: /user-[^.]+\.example\.com/ do |faraday|
    faraday.service_name = 'user.example.com'
    faraday.split_by_domain = false # Uniquement nécessaire si split_by_domain prend par défaut la valeur true
  end
end

# Si vous souhaitez utiliser des paramètres différents pour une instance client spécifique
connection = Faraday.new('https://example.com') do |builder|
  builder.use(:ddtrace, **options)
  builder.adapter Faraday.default_adapter
end

connection.get('/foo')

options correspond aux arguments de mot-clé suivants :

Grape

L’intégration Grape permet d’instrumenter les endpoints et filtres Grape. Elle peut être utilisée conjointement à d’autres intégrations telles que Rack et Rails.

Pour activer votre intégration, utilisez la méthode Datadog.configure avant de définir votre application Grape :

# api.rb
require 'grape'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :grape, **options
end

# Ensuite, définir votre application
class RackTestingAPI < Grape::API
  desc 'main endpoint'
  get :success do
    'Hello world!'
  end
end

options correspond aux arguments de mot-clé suivants :

GraphQL

L’intégration GraphQL permet d’instrumenter les requêtes GraphQL.

Pour activer votre intégration, utilisez la méthode Datadog.configure :

# Dans l'initialiseur Rails ou un équivalent
Datadog.configure do |c|
  c.tracing.instrument :graphql, schemas: [YourSchema], **options
end

# Ensuite, exécuter une requête GraphQL
YourSchema.execute(query, variables: {}, context: {}, operation_name: nil)

La méthode instrument :graphql accepte les paramètres suivants. Des options supplémentaires peuvent être spécifiées avec options :

Configurer des schémas GraphQL manuellement

Si vous préférez configurer les paramètres de tracing pour un schéma spécifique (par exemple lorsque plusieurs schémas sont associés à des noms de service différents), vous pouvez ajouter ce qui suit à la définition du schéma via l’API GraphQL :

# Schéma basé sur une classe
class YourSchema < GraphQL::Schema
  use(
    GraphQL::Tracing::DataDogTracing,
    service: 'graphql'
  )
end

# Schéma de type .define
YourSchema = GraphQL::Schema.define do
  use(
    GraphQL::Tracing::DataDogTracing,
    service: 'graphql'
  )
end

Vous pouvez également modifier un schéma déjà défini :

# Schéma basé sur une classe
YourSchema.use(
    GraphQL::Tracing::DataDogTracing,
    service: 'graphql'
)

# Schéma de type .define
YourSchema.define do
  use(
    GraphQL::Tracing::DataDogTracing,
    service: 'graphql'
  )
end

Si vous avez opté pour la configuration manuelle, n’utilisez pas instrument :graphql dans Datadog.configure afin d’éviter que le tracing soit effectué en double. Ces deux modes de configuration du tracing de GraphQL ne doivent pas être utilisés en même temps.

gRPC

L’intégration grpc permet d’ajouter des intercepteurs côté client et côté serveur, qui sont exécutés en tant que middleware avant l’appel de procédure à distance du service. Les applications gRPC étant souvent distribuées, l’intégration partage les données de tracing entre client et serveur.

Pour configurer votre intégration, utilisez la méthode Datadog.configure comme suit :

require 'grpc'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :grpc, **options
end

# Côté serveur
server = GRPC::RpcServer.new
server.add_http2_port('localhost:50051', :this_port_is_insecure)
server.handle(Demo)
server.run_till_terminated

# Côté client
client = Demo.rpc_stub_class.new('localhost:50051', :this_channel_is_insecure)
client.my_endpoint(DemoMessage.new(contents: 'hello!'))

options correspond aux arguments de mot-clé suivants :

Configurer des paramètres différents pour chaque client

Lorsque plusieurs clients appellent plusieurs services différents, vous avez la possibilité de passer directement l’intercepteur Datadog :

configured_interceptor = Datadog::Tracing::Contrib::GRPC::DatadogInterceptor::Client.new do |c|
  c.service_name = "Alternate"
end

alternate_client = Demo::Echo::Service.rpc_stub_class.new(
  'localhost:50052',
  :this_channel_is_insecure,
  :interceptors => [configured_interceptor]
)

De cette façon, l’intégration fera en sorte que le configured_interceptor établisse une configuration de tracing unique pour cette instance client.

hanami

L’intégration hanami effectuera l’instrumentation de routing, action et render pour votre application Hanami. Pour activer l’instrumentation hanami, il est recommandé de procéder à une instrumentation automatique avec ce qui suit :

gem 'ddtrace', require: 'ddtrace/auto_instrument'

Créez ensuite un fichier d’initialiseur dans votre dossier config/initializers :

# config/initializers/datadog.rb
Datadog.configure do |c|
  c.tracing.instrument :hanami, **options
end

options correspond aux arguments de mot-clé suivants :

http.rb

L’intégration http.rb permet de tracer n’importe quel appel HTTP effectué via le gem Http.rb.

require 'http'
require 'ddtrace'
Datadog.configure do |c|
  c.tracing.instrument :httprb, **options
  # Si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression régulière
  c.tracing.instrument :httprb, describes: /user-[^.]+\.example\.com/ do |httprb|
    httprb.service_name = 'user.example.com'
    httprb.split_by_domain = false # Uniquement nécessaire si split_by_domain prend par défaut la valeur true
  end
end

options correspond aux arguments de mot-clé suivants :

httpclient

L’intégration httpclient permet de tracer n’importe quel appel HTTP effectué via le gem httpclient.

require 'httpclient'
require 'ddtrace'
Datadog.configure do |c|
  c.tracing.instrument :httpclient, **options
  # SI nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression régulière
  c.tracing.instrument :httpclient, describes: /user-[^.]+\.example\.com/ do |httpclient|
    httpclient.service_name = 'user.example.com'
    httpclient.split_by_domain = false # Uniquement nécessaire si split_by_domain prend par défaut la valeur true
  end
end

options correspond aux arguments de mot-clé suivants :

httpx

httpx gère sa propre intégration avec ddtrace :

require "ddtrace"
require "httpx/adapters/datadog"

Datadog.configure do |c|
  c.tracing.instrument :httpx

  # Si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression régulière
  c.tracing.instrument :httpx, describes: /user-[^.]+\.example\.com/ do |http|
    http.service_name = 'user.example.com'
    http.split_by_domain = false # Uniquement nécessaire si split_by_domain prend par défaut la valeur true
  end
end

Kafka

L’intégration Kafka permet de tracer le gem ruby-kafka :

Vous pouvez l’activer via Datadog.configure :

require 'active_support/notifications' # nécessaire pour activer l'instrumentation 'ruby-kafka'
require 'kafka'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :kafka
end

MongoDB

L’intégration permet de tracer n’importe quelle Command envoyée depuis le pilote Ruby pour MongoDB vers un cluster MongoDB. De plus, les ODM (Object Document Mappers) tels que Mongoid qui utilisent le pilote Ruby officiel seront automatiquement instrumentés. Pour activer l’intégration, procédez simplement ainsi :

require 'mongo'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :mongo, **options
end

# Créer un client MongoDB et l'utiliser normalement
client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'artists')
collection = client[:people]
collection.insert_one({ name: 'Steve' })

# Si vous souhaitez utiliser des paramètres différents pour une instance client spécifique
Datadog.configure_onto(client, **options)

options correspond aux arguments de mot-clé suivants :

Configurer les paramètres de tracing par connexion

Il est possible de configurer les paramètres de tracing par connexion via l’option describes :

# Ajouter une option `:describes` avec une clé de connexion.
# Toutes les clés suivantes sont acceptées et fonctionnent de façon similaire.
# Si un bloc est spécifié, cela renvoie un objet Settings
# qui accepte toutes les options de configuration énumérées ci-dessus.

Datadog.configure do |c|
  # Chaîne pour la connexion réseau
  c.tracing.instrument :mongo, describes: '127.0.0.1:27017', service_name: 'mongo-primary'

  # Expression régulière pour la connexion réseau
  c.tracing.instrument :mongo, describes: /localhost.*/, service_name: 'mongo-secondary'
end

client = Mongo::Client.new([ '127.0.0.1:27017' ], :database => 'artists')
collection = client[:people]
collection.insert_one({ name: 'Steve' })
# L'appel tracé appartiendra au service `mongo-primary`

client = Mongo::Client.new([ 'localhost:27017' ], :database => 'artists')
collection = client[:people]
collection.insert_one({ name: 'Steve' })
# L'appel tracé appartiendra au service `mongo-secondary`

Lorsque plusieurs configurations describes correspondent à une connexion, la dernière règle configurée qui correspond est appliquée.

MySQL2

L’intégration MySQL2 permet de tracer n’importe quelle commande SQL envoyée via le gem mysql2.

require 'mysql2'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :mysql2, **options
end

client = Mysql2::Client.new(:host => "localhost", :username => "root")
client.query("SELECT * FROM users WHERE group='x'")

options correspond aux arguments de mot-clé suivants :

Net/HTTP

L’intégration Net/HTTP permet de tracer n’importe quel appel HTTP effectué via le module Net::HTTP de la bibliothèque standard.

require 'net/http'
require 'ddtrace'

Datadog.configure do |c|
  c.tracing.instrument :http, **options

  # Si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression régulière
  c.tracing.instrument :http, describes: /user-[^.]+\.example\.com/ do |http|
    http.service_name = 'user.example.com'
    http.split_by_domain = false # Uniquement nécessaire si split_by_domain prend par défaut la valeur true
  end
end

Net::HTTP.start('127.0.0.1', 8080) do |http|
  request = Net::HTTP::Get.new '/index'
  response = http.request(request)
end

content = Net::HTTP.get(URI('http://127.0.0.1/index.html'))

options correspond aux arguments de mot-clé suivants :

Si vous souhaitez configurer chaque objet de connexion séparément, vous pouvez utiliser la méthode Datadog.configure_onto comme suit :

client = Net::HTTP.new(host, port)
Datadog.configure_onto(client, **options)