Tracer des applications Ruby
Rapport de recherche Datadog : Bilan sur l'adoption de l'informatique sans serveur Rapport : Bilan sur l'adoption de l'informatique sans serveur

Tracer des applications Ruby

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.

Débuter

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

Pour découvrir comment l’APM se présente une fois que votre application a commencé à envoyer des informations à Datadog, consultez la section Visualiser vos données APM.

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

Table des matières

Compatibilité

Interpréteurs Ruby pris en charge :

TypeDocumentationVersionType de prise en chargeVersion du gem prise en charge
MRIhttps://www.ruby-lang.org/2.7ComplèteDernière
2.6ComplèteDernière
2.5ComplèteDernière
2.4ComplèteDernière
2.3ComplèteDernière
2.2ComplèteDernière
2.1ComplèteDernière
2.0ComplèteDernière
1.9.3Maintenance (jusqu’au 6 août 2020)< 0.27.0
1.9.1Maintenance (jusqu’au 6 août 2020)< 0.27.0
JRubyhttp://jruby.org/9.2.0.0AlphaDernière

Serveurs Web pris en charge :

TypeDocumentationVersionType de prise en charge
Pumahttp://puma.io/2.16+/3.6+Complète
Unicornhttps://bogomips.org/unicorn/4.8+/5.1+Complète
Passengerhttps://www.phusionpassenger.com/5.0+Complète

Frameworks de tracing pris en charge :

TypeDocumentationVersionVersion du gem prise en charge
OpenTracinghttps://github.com/opentracing/opentracing-ruby0.4.1+ (avec Ruby 2.1+)>= 0.16.0

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.

Installation

Suivez les étapes ci-dessous pour commencer à tracer votre application Ruby sans attendre.

Configurer l’Agent Datadog

Avant de configurer le tracing de votre application, installez l’Agent Datadog. Le traceur de l’APM Ruby envoie les données de tracing via l’Agent Datadog.

Installez et configurez l’Agent Datadog. Consultez la documentation supplémentaire relative au tracing d’applications Docker.

Démarrage rapide pour les applications Rails

  1. Ajoutez le gem ddtrace à votre fichier Gem :

    source 'https://rubygems.org'
    gem 'ddtrace'
  2. Installez le gem avec bundle install

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

    Datadog.configure do |c|
      # This will activate auto-instrumentation for Rails
      c.use :rails
    end

    Vous pouvez également activer d’autres intégrations ici (consultez Instrumenter des intégrations)

Démarrage rapide pour les applications Ruby

  1. Installez le gem avec gem install ddtrace
  2. Ajoutez un bloc de configuration à votre application Ruby :

    require 'ddtrace'
    Datadog.configure do |c|
      # Configure the tracer here.
      # Activate integrations, change tracer settings, etc...
      # By default without additional configuration, nothing will be traced.
    end
  3. Ajoutez ou activez l’instrumentation en suivant l’une de ces étapes :

Démarrage rapide pour OpenTracing

  1. Installez le gem avec gem install ddtrace
  2. Ajoutez ce qui suit à votre fichier de configuration OpenTracing :

    require 'opentracing'
    require 'ddtrace'
    require 'ddtrace/opentracer'
    
    # Activate the Datadog tracer for OpenTracing
    OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new
  3. (Facultatif) Ajoutez un bloc de configuration à votre application Ruby pour configurer Datadog :

    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
  4. (Facultatif) Ajoutez ou activez une instrumentation supplémentaire en suivant l’une de ces étapes :

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 un bloc arbitraire de code Ruby, vous pouvez utiliser la méthode Datadog.tracer.trace :

Datadog.tracer.trace(name, options) do |span|
  # Incorporez le code que vous souhaitez instrumenter dans ce bloc.
  # Vous pouvez également modifier la span ici.
  # Modifiez le nom de la ressource, définissez des 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 est un hash facultatif qui accepte les paramètres suivants :

CléTypeDescriptionValeur par défaut
servicestringLe nom du service auquel cette span appartient (p. ex. 'mon-service-web')default-service du traceur, $PROGRAM_NAME ou 'ruby'
resourcestringNom de la ressource ou de l’action tracée. Les traces associées à un même nom de ressource seront regroupées pour la collecte de métriques (elles resteront toutefois consultables séparément). Généralement spécifique à un domaine, tel qu’une URL, une requête, etc. (p. ex. 'Article#submit', http://exemple.com/articles/list.)name de la span.
span_typestringType de span ('http', 'db', etc.)nil
child_ofDatadog::Span / Datadog::ContextParent de cette span. Si aucun parent n’est spécifié, devient automatiquement la span active.nil
start_timeIntegerHeure d’initialisation réelle de la span. Utile dans les cas où les événements tracés se sont déjà produits.Time.now.utc
tagsHashTags supplémentaires à ajouter à la span.{}
on_errorProcGestionnaire invoqué lorsqu’un bloc devant être tracé renvoie une erreur. Arguments : span spécifiée et error. Définit l’erreur sur la span par défaut.`proc {

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

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

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

Tracing asynchrone

Il n’est pas toujours possible d’utiliser Datadog.tracer.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.tracer.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.tracer.trace('database.query')
  span.resource = query
  span.start_time = start
  span.finish(finish)
end

Lorsque vous appelez Datadog.tracer.trace sans bloc, la Datadog::Span 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.tracer.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)
  # Start a span
  Datadog.tracer.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.tracer.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.tracer.active_span
current_span.set_tag('my_tag', 'my_value') unless current_span.nil?

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

# exemple : ajouter un tag à la span racine active

current_root_span = Datadog.tracer.active_root_span
current_root_span.set_tag('my_tag', 'my_value') unless current_root_span.nil?

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.use :integration_name, options
end

options est un hash des paramètres de configuration spécifiques à l’intégration.

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

NomCléVersions prises en chargeConfigurationSource Gem
Action Cableaction_cable>= 5.0LienLien
Action Viewaction_view>= 3.0LienLien
Active Model Serializersactive_model_serializers>= 0.9LienLien
Action Packaction_pack>= 3.0LienLien
Active Recordactive_record>= 3.0LienLien
Active Supportactive_support>= 3.0LienLien
AWSaws>= 2.0LienLien
Concurrent Rubyconcurrent_ruby>= 0.9LienLink
Dallidalli>= 2.0LienLien
DelayedJobdelayed_job>= 4.1LienLien
Elasticsearchelasticsearch>= 1.0LienLien
Ethonethon>= 0.11LienLien
Exconexcon>= 0.50LienLien
Faradayfaraday>= 0.14LienLien
Grapegrape>= 1.0LienLien
GraphQLgraphql>= 1.7.9LienLien
gRPCgrpc>= 1.7LienLien
MongoDBmongo>= 2.1LienLien
MySQL2mysql2>= 0.3.21LienLien
Net/HTTPhttp(Toute version de Ruby prise en charge)LienLien
Prestopresto>= 0.5.14LienLien
Racecarracecar>= 0.3.5LienLien
Rackrack>= 1.1LienLien
Railsrails>= 3.0LienLien
Rakerake>= 12.0LienLien
Redisredis>= 3.2LienLien
Resqueresque>= 1.0, < 2.0LienLien
Client Restrest-client>= 1.8LienLien
Sequelsequel>= 3.41LienLien
Shoryukenshoryuken>= 3.2LienLien
Sidekiqsidekiq>= 3.5.4LienLien
Sinatrasinatra>= 1.4LienLien
Sucker Punchsucker_punch>= 2.0LienLien

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.use :action_cable, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de action_cable'action_cable'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Action View

Active Support 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.use :action_view, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation des rendus.action_view
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer
template_base_pathUtilisé pour le parsing du nom du modèle. Si vous ne stockez pas vos modèles dans le dossier views/, vous devrez peut-être modifier cette valeur.'views/'

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.use :active_model_serializers, options
end

my_object = MyModel.new(name: 'my object')
ActiveModelSerializers::SerializableResource.new(test_obj).serializable_hash
CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de active_model_serializers.'active_model_serializers'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :action_pack, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation des rendus.action_pack
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :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') # tracing terminé
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
orm_service_nameNom de service utilisé pour la partie ORM Ruby de l’instrumentation de active_record. Lorsqu’il est explicitement défini, ce paramètre remplace le nom de service associé aux spans ORM. Autrement, les spans héritent du service de leur parent.'active_record'
service_nameNom de service utilisé pour la partie base de données de l’instrumentation de active_record.Nom de l’adaptateur de base de données (p. ex. 'mysql2')
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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 équivalentes.
# 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 ActiveRecord.
  c.use :active_record, describes: :secondary_database, service_name: 'secondary-db'

  c.use :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 :
  # Adaptateur, utilisateur, host, port, base de données
  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 :
  # Adaptateur, utilisateur, host, port, base de données
  c.use :active_record, describes: {
      adapter:  'mysql2',
      host:     '127.0.0.1',
      port:     '3306',
      database: 'mysql',
      username: 'root'
    },
    service_name: 'secondary-db'
end

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.use :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.use :active_support, options
end

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

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
cache_serviceNom de service utilisé pour la mise en cache avec l’instrumentation de active_support.active_support-cache
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :aws, options
end

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

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de aws'aws'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :concurrent_ruby, options
end

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

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
service_nameNom de service utilisé pour l’instrumentation de concurrent-ruby'concurrent-ruby'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :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 est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de dalli'memcached'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

DelayedJob

L’intégration DelayedJob utilise des hooks de cycle de vie pour tracer les exécutions de tâches.

Vous pouvez l’activer via Datadog.configure :

require 'ddtrace'

Datadog.configure do |c|
  c.use :delayed_job, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de DelayedJob'delayed_job'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :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'

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
quantizeHash contenant les options de quantification. Possibilité d’utiliser :show avec un tableau de clés à ne pas quantifier (ou :all pour ignorer la quantification), ou :exclude avec un tableau de clés à exclure entièrement.{}
service_nameNom de service utilisé pour l’instrumentation de elasticsearch'elasticsearch'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :ethon, options

  # si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression regex
  c.use :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 est true par défaut
  end
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
distributed_tracingActive le tracing distribuétrue
service_nameNom de service utilisé pour l’instrumentation de ethon'ethon'
split_by_domainDéfinir sur true pour utiliser le domaine de requête comme nom de service.false
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :excon, options

  # si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression regex
  c.use :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 est true par défaut
  end
end

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

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
distributed_tracingActive le tracing distribuétrue
error_handlerUn Proc qui accepte un paramètre response. S’il renvoie une valeur truthy, la span de la trace est définie comme une erreur. Par défaut, seules les réponses 5XX sont définies comme des erreurs.nil
service_nameNom de service pour l’instrumentation d’Excon. Lorsque spécifié à un middleware pour une connexion spécifique, s’applique uniquement à cet objet de connexion.'excon'
split_by_domainDéfinir sur true pour utiliser le domaine de requête comme nom de service.false
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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::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::Contrib::Excon::Middleware.with(options),
    Excon::Middleware::Idempotent
  ]
)

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.use :faraday, options

  # si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression regex
  c.use :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 est true par défaut
  end
end

# Si vous souhaitez remplacer la configuration globale pour une instance de 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 est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
distributed_tracingActive le tracing distribuétrue
error_handlerUn Proc qui accepte un paramètre response. S’il renvoie une valeur truthy, la span de la trace est définie comme une erreur. Par défaut, seules les réponses 5XX sont définies comme des erreurs.nil
service_nameNom du service pour l’instrumentation de Faraday. Lorsque spécifié à un middleware pour une connexion spécifique, s’applique uniquement à cet objet de connexion.'faraday'
split_by_domainDéfinir sur true pour utiliser le domaine de requête comme nom de service.false
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :grape, options
end

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

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.nil
enabledDéfinit si Grape doit être tracé ou non. Utile pour désactiver le tracing temporairement. true ou falsetrue
service_nameNom de service utilisé pour l’instrumentation de grape'grape'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :graphql, schemas: [YourSchema], options
end

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

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

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.nil
service_nameNom de service utilisé pour l’instrumentation de graphql'ruby-graphql'
schemasObligatoire. Tableau d’objets GraphQL::Schema à tracer. Le tracing sera activé pour tous les schémas énumérés, en utilisant les options spécifiées dans cette configuration. Si aucun schéma n’est spécifié, le tracing ne sera pas activé.[]
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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 :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.use :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 est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de grpc'grpc'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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::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.

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.use :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(client, options)

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
quantizeHash contenant les options de quantification. Possibilité d’utiliser :show avec un tableau de clés à ne pas quantifier (ou :all pour ignorer la quantification), ou :exclude avec un tableau de clés à exclure entièrement.{ show: [:collection, :database, :operation] }
service_nameNom de service utilisé pour l’instrumentation de mongo'mongodb'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :mysql2, options
end

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

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de mysql2'mysql2'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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.use :http, options

  # si nécessaire, spécifier un nom de service différent pour les hostnames correspondant à une expression regex
  c.use :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 est true par défaut
  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 est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
distributed_tracingActive le tracing distribuétrue
service_nameNom de service utilisé pour l’instrumentation de http'net/http'
split_by_domainDéfinir sur true pour utiliser le domaine de requête comme nom de service.false
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

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

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

Presto

L’intégration Presto permet de tracer n’importe quelle commande SQL envoyée via le gem presto-client.

require 'presto-client'
require 'ddtrace'

Datadog.configure do |c|
  c.use :presto, options
end

client = Presto::Client.new(
  server: "localhost:8880",
  ssl: {verify: false},
  catalog: "native",
  schema: "default",
  time_zone: "US/Pacific",
  language: "English",
  http_debug: true,
)

client.run("select * from system.nodes")

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de presto'presto'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Racecar

L’intégration Racecar permet de tracer les tâches Racecar.

Vous pouvez l’activer via Datadog.configure :

require 'ddtrace'

Datadog.configure do |c|
  c.use :racecar, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de racecar'racecar'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Rack

L’intégration Rack permet d’utiliser un middleware pour tracer toutes les requêtes avant qu’elles n’atteignent le framework ou l’application cible. Elle répond à l’interface minimale Rack, offrant des valeurs raisonnables qui peuvent être récupérées au niveau de Rack.

Cette intégration est automatiquement activée avec les frameworks Web tels que Rails. Si vous utilisez une application Rack standard, activez l’intégration dans votre config.ru :

# exemple de config.ru
require 'ddtrace'

Datadog.configure do |c|
  c.use :rack, options
end

use Datadog::Contrib::Rack::TraceMiddleware

app = proc do |env|
  [ 200, {'Content-Type' => 'text/plain'}, ['OK'] ]
end

run app

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.nil
applicationVotre application Rack. Obligatoire pour middleware_names.nil
distributed_tracingActive le tracing distribué de façon à associer les traces de ce service aux traces d’autres services si des en-têtes de tracing sont reçus.true
headersHash d’en-têtes de requête ou de réponse HTTP à ajouter en tant que tags à rack.request. Accepte les clés request et response des valeurs sous forme de tableau, par exemple ['Last-Modified']. Ajoute les tags http.request.headers.* et http.response.headers.* respectivement.{ response: ['Content-Type', 'X-Request-ID'] }
middleware_namesActivez ce paramètre pour utiliser les classes de middleware en tant que noms de ressource pour les spans rack. Nécessite d’utiliser l’option application.false
quantizeHash contenant les options de quantification. Possibilité d’utiliser :query ou :fragment.{}
quantize.queryHash contenant les options propres à la requête lors de la quantification des URL. Possibilité d’utiliser :show ou :exclude. Voir les options ci-dessous. Cette option doit être imbriquée dans l’option quantize.{}
quantize.query.showDéfinit les valeurs à toujours afficher. Par défaut, aucune valeur n’est affichée. Spécifier un tableau de chaînes ou :all pour afficher toutes les valeurs. Cette option doit être imbriquée dans l’option query.nil
quantize.query.excludeDéfinit les valeurs à supprimer entièrement. Par défaut, aucune valeur n’est exclue. Spécifier un tableau de chaînes ou :all pour supprimer la chaîne de requête entière. Cette option doit être imbriquée dans l’option query.nil
quantize.fragmentDéfinit le comportement à appliquer pour les fragments d’URL. Par défaut, les fragments sont supprimés. Utiliser :show pour afficher les fragments d’URL. Cette option doit être imbriquée dans l’option quantize.nil
request_queuingPermet de suivre le temps que la requête HTTP passe dans la file d’attente du serveur frontend. Consultez la section Mise en file d’attente des requêtes HTTP pour en savoir plus sur la configuration. Définir sur true pour activer.false
service_nameNom de service utilisé pour l’instrumentation de rack'rack'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer
web_service_nameNom de service pour les spans de mise en file d’attente des requêtes sur le serveur frontend. (Ex. : 'nginx')'web-server'

Configurer le comportement de quantification des URL

Datadog.configure do |c|
  # Comportement par défaut : toutes les valeurs sont quantifiées, les fragments sont supprimés.
  # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id&sort_by
  # http://example.com/path?categories[]=1&categories[]=2 --> http://example.com/path?categories[]

  # Afficher les valeurs pour le paramètre de chaîne de requête 'category_id'
  # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id=1&sort_by
  c.use :rack, quantize: { query: { show: ['category_id'] } }

  # Afficher les valeurs pour tous les paramètres de chaîne de requête
  # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id=1&sort_by=asc
  c.use :rack, quantize: { query: { show: :all } }

  # Exclure entièrement le paramètre de chaîne de requête 'sort_by'
  # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id
  c.use :rack, quantize: { query: { exclude: ['sort_by'] } }

  # Supprimer la chaîne de requête entière
  # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path
  c.use :rack, quantize: { query: { exclude: :all } }

  # Afficher les fragments d'URL
  # http://example.com/path?category_id=1&sort_by=asc#featured --> http://example.com/path?category_id&sort_by#featured
  c.use :rack, quantize: { fragment: :show }
end

Rails

L’intégration Rails permet de tracer les requêtes, les appels de base de données, le rendu des modèles ainsi que les opérations read/write/delete du cache. L’intégration exploite l’instrumentation d’Active Support en écoutant l’API Notification de façon à tracer chaque opération instrumentée par l’API.

Pour activer l’instrumentation Rails, créez un fichier initialiseur dans votre dossier config/initializers :

# config/initializers/datadog.rb
require 'ddtrace'

Datadog.configure do |c|
  c.use :rails, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.nil
cache_serviceNom du service de cache utilisé lors du tracing des activités de cache'<nom_app>-cache'
controller_serviceNom de service utilisé lors du tracing d’un contrôleur d’action Rails'<nom_app>'
database_serviceNom du service de base de données utilisé lors du tracing des activités de base de données'<nom_app>-<nom_adaptateur>'
distributed_tracingActive le tracing distribué de façon à associer les traces de ce service aux traces d’autres services si des en-têtes de tracing sont reçus.true
exception_controllerClasse ou module qui identifie une classe de contrôleur d’exception personnalisé. Le traceur offre une gestion améliorée des erreurs lorsqu’il peut identifier les contrôleurs d’exception personnalisés. Par défaut, lorsque cette option n’est pas définie, le traceur « devine » à quoi ressemble un contrôleur d’exception personnalisé. Cette option facilite leur identification.nil
middlewareAjoute le middleware de tracing à l’application Rails. Définir sur false pour ne pas charger le middleware.true
middleware_namesPermet aux requêtes de middleware court-circuitées d’afficher le nom du middleware en tant que ressource pour la trace.false
service_nameNom de service utilisé lors du tracing de requêtes d’application (au niveau de rack)'<nom_app>' (récupéré à partir de l’espace de nommage de votre application Rails)
template_base_pathUtilisé pour le parsing du nom du modèle. Si vous ne stockez pas vos modèles dans le dossier views/, vous devrez peut-être modifier cette valeur.'views/'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Versions prises en charge

Versions de RubyVersions de Rails prises en charge
2.03.0-3.2
2.13.0-4.2
2.2-2.33.0-5.2
2.44.2.8-5.2
2.54.2.8-6.0
2.6-2.75.0-6.0

Rake

Il est possible d’instrumenter vos tâches Rake en activant l’intégration rake. Toutes les tâches et leurs sous-tâches seront tracées.

Pour activer le tracing des tâches Rake, ajoutez ce qui suit à votre Rakefile :

# Au début de votre Rakefile :
require 'rake'
require 'ddtrace'

Datadog.configure do |c|
  c.use :rake, options
end

task :my_task do
  # Spécifier votre tâche ici…
end

Rake::Task['my_task'].invoke

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
enabledDéfinit si les tâches Rake doivent être tracées ou non. Utile pour désactiver le tracing temporairement. true ou falsetrue
quantizeHash contenant les options de quantification des arguments de tâche. Des détails supplémentaires et des exemples sont disponibles plus bas.{}
service_nameNom de service utilisé pour l’instrumentation de rake'rake'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Configurer le comportement de quantification des tâches

Datadog.configure do |c|
  # On considère une tâche qui accepte :one, :two, :three…
  # L'invocation se fait avec 'foo', 'bar', 'baz'.

  # Comportement par défaut : tous les arguments sont quantifiés.
  # `rake.invoke.args` tag  --> ['?']
  # `rake.execute.args` tag --> { one: '?', two: '?', three: '?' }
  c.use :rake

  # Afficher les valeurs pour l'argument :two uniquement
  # `rake.invoke.args` tag  --> ['?']
  # `rake.execute.args` tag --> { one: '?', two: 'bar', three: '?' }
  c.use :rake, quantize: { args: { show: [:two] } }

  # Afficher les valeurs pour tous les arguments.
  # `rake.invoke.args` tag  --> ['foo', 'bar', 'baz']
  # `rake.execute.args` tag --> { one: 'foo', two: 'bar', three: 'baz' }
  c.use :rake, quantize: { args: { show: :all } }

  # Exclure entièrement l'argument :three
  # `rake.invoke.args` tag  --> ['?']
  # `rake.execute.args` tag --> { one: '?', two: '?' }
  c.use :rake, quantize: { args: { exclude: [:three] } }

  # Supprimer entièrement les arguments
  # `rake.invoke.args` tag  --> ['?']
  # `rake.execute.args` tag --> {}
  c.use :rake, quantize: { args: { exclude: :all } }
end

Redis

L’intégration Redis permet de tracer les appels simples ainsi que les pipelines.

require 'redis'
require 'ddtrace'

Datadog.configure do |c|
  c.use :redis, options
end

# Exécuter les commandes Redis
redis = Redis.new
redis.set 'foo', 'bar'

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de redis'redis'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Vous pouvez également définir une configuration différente pour chaque instance comme suit :

customer_cache = Redis.new
invoice_cache = Redis.new

Datadog.configure(customer_cache, service_name: 'customer-cache')
Datadog.configure(invoice_cache, service_name: 'invoice-cache')

# L'appel tracé appartient au service `customer-cache`
customer_cache.get(...)
# L'appel tracé appartient au service `invoice-cache`
invoice_cache.get(...)

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 équivalentes.
# 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|
  # La configuration par défaut pour tous les clients redis
  c.use :redis, service_name: 'redis-default'

  # Le configuration correspondant à un socket unix donné
  c.use :redis, describes: { url: 'unix://path/to/file' }, service_name: 'redis-unix'

  # Chaîne de connexion
  c.use :redis, describes: { url: 'redis://127.0.0.1:6379/0' }, service_name: 'redis-connection-string'
  # Host, port, bdd, schéma client
  c.use :redis, describes: { host: 'my-host.com', port: 6379, db: 1, scheme: 'redis' }, service_name: 'redis-connection-hash'
  # Sous-ensemble du hash de connexion uniquement
  c.use :redis, describes: { host: ENV['APP_CACHE_HOST'], port: ENV['APP_CACHE_PORT'] }, service_name: 'redis-cache'
  c.use :redis, describes: { host: ENV['SIDEKIQ_CACHE_HOST'] }, service_name: 'redis-sidekiq'
end

Resque

L’intégration Resque utilise des hooks Resque qui viennent entourer la méthode perform.

Pour tracer une tâche Resque :

require 'ddtrace'

class MyJob
  def self.perform(*args)
    # do_something
  end
end

Datadog.configure do |c|
  c.use :resque, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de resque'resque'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer
workersUn tableau comprenant toutes les classes worker que vous souhaitez tracer (ex. : [MyJob])[]

Client Rest

L’intégration rest-client est disponible via le middleware ddtrace :

require 'rest_client'
require 'ddtrace'

Datadog.configure do |c|
  c.use :rest_client, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
distributed_tracingActive le tracing distribuétrue
service_nameNom de service utilisé pour l’instrumentation de rest_client.'rest_client'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Sequel

L’intégration Sequel permet de tracer les requêtes envoyées à votre base de données.

require 'sequel'
require 'ddtrace'

# Connexion à la base de données
database = Sequel.sqlite

# Création d'une table
database.create_table :articles do
  primary_key :id
  String :name
end

Datadog.configure do |c|
  c.use :sequel, options
end

# Envoi d'une requête
articles = database[:articles]
articles.all

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de sequelNom de l’adaptateur de base de données (p. ex. 'mysql2')
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Seules les versions 2.0+ de Ruby sont prises en charge.

Configurer des paramètres différents pour chaque base de données

Si vous utilisez plusieurs bases de données avec Sequel, vous pouvez définir des paramètres différents pour chacune d’entre elles en configurant leurs objets Sequel::Database respectifs :

sqlite_database = Sequel.sqlite
postgres_database = Sequel.connect('postgres://user:password@host:port/database_name')

# Configurer chaque base de données avec des noms de service différents
Datadog.configure(sqlite_database, service_name: 'my-sqlite-db')
Datadog.configure(postgres_database, service_name: 'my-postgres-db')

Shoryuken

L’intégration Shoryuken est un middleware exécuté côté serveur qui permet de tracer les exécutions de tâches.

Vous pouvez l’activer via Datadog.configure :

require 'ddtrace'

Datadog.configure do |c|
  c.use :shoryuken, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de shoryuken'shoryuken'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Sidekiq

L’intégration Sidekiq est un middleware exécuté côté client et côté serveur qui permet de tracer les mises en file d’attente et les exécutions des tâches.

Vous pouvez l’activer via Datadog.configure :

require 'ddtrace'

Datadog.configure do |c|
  c.use :sidekiq, options
end

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
client_service_nameNom de service utilisé pour l’instrumentation de sidekiq côté client'sidekiq-client'
service_nameNom de service utilisé pour l’instrumentation de sidekiq côté serveur'sidekiq'
tag_argsActiver le tagging des arguments des tâches. true pour l’activer, false pour le désactiver.false
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Sinatra

L’intégration Sinatra permet de tracer les requêtes et le rendu des modèles.

Pour commencer à utiliser le client de tracing, assurez-vous d’importer ddtrace et use :sinatra après sinatra ou sinatra/base, et avant de définir votre application/vos routages :

Application classique

require 'sinatra'
require 'ddtrace'

Datadog.configure do |c|
  c.use :sinatra, options
end

get '/' do
  'Hello world!'
end

Application modulaire

require 'sinatra/base'
require 'ddtrace'

Datadog.configure do |c|
  c.use :sinatra, options
end

class NestedApp < Sinatra::Base
  register Datadog::Contrib::Sinatra::Tracer

  get '/nested' do
    'Hello from nested app!'
  end
end

class App < Sinatra::Base
  register Datadog::Contrib::Sinatra::Tracer

  use NestedApp

  get '/' do
    'Hello world!'
  end
end

Assurez-vous d’enregistrer Datadog::Contrib::Sinatra::Tracer en tant que middleware avant de monter vos applications imbriquées.

Options d’instrumentation

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.nil
distributed_tracingActive le tracing distribué de façon à associer les traces de ce service aux traces d’autres services si des en-têtes de tracing sont reçus.true
headersHash d’en-têtes de requête ou de réponse HTTP à ajouter en tant que tags à sinatra.request. Accepte les clés request et response des valeurs sous forme de tableau, par exemple ['Last-Modified']. Ajoute les tags http.request.headers.* et http.response.headers.* respectivement.{ response: ['Content-Type', 'X-Request-ID'] }
resource_script_namesAjouter le nom du script devant les noms des ressourcesfalse
service_nameNom de service utilisé pour l’instrumentation de sinatra'sinatra'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Sucker Punch

L’intégration sucker_punch permet de tracer toutes les tâches planifiées :

require 'ddtrace'

Datadog.configure do |c|
  c.use :sucker_punch, options
end

# L'exécution de cette opération est tracée
LogJob.perform_async('login')

options est un hash facultatif qui accepte les paramètres suivants :

CléDescriptionValeur par défaut
analytics_enabledActiver l’analyse des spans générées par cette intégration. Définir sur true pour l’activer, sur nil pour utiliser le paramètre global, ou sur false pour la désactiver.false
service_nameNom de service utilisé pour l’instrumentation de sucker_punch'sucker_punch'
tracerDatadog::Tracer utilisé pour effectuer l’instrumentation. Ce paramètre n’a généralement pas besoin d’être défini.Datadog.tracer

Configuration avancée

Paramètre du traceur

Pour modifier le comportement par défaut du traceur Datadog, vous pouvez spécifier des options personnalisées dans le bloc Datadog.configure comme suit :

# config/initializers/datadog-tracer.rb

Datadog.configure do |c|
  c.tracer.enabled = true
  c.tracer.hostname = 'my-agent'
  c.tracer.port = 8126
  c.tracer.partial_flush.enabled = false
  c.tracer.sampler = Datadog::AllSampler.new

  # Pour les cas d'utilisation avancés, vous pouvez spécifier votre propre traceur :
  c.tracer.instance = Datadog::Tracer.new

  # Pour activer le mode debugging :
  c.diagnostics.debug = true
end

Les options disponibles sont :

  • enabled : définir si le tracer est activé ou non. Si cette option est définie sur false, l’instrumentation sera exécutée mais aucune span ne sera envoyée à l’Agent de trace.
  • hostname : définir le hostname de l’Agent de trace.
  • instance : définir une instance de Datadog::Tracer personnalisée. Si cette option est définie, les autres paramètres de tracing sont ignorés (le traceur doit être configuré manuellement).
  • partial_flush.enabled : définir sur true pour vider les traces partielles (lorsque leur temps d’exécution est trop long). Désactivé par défaut. Option expérimentale.
  • port : définir le port d’écoute utilisé par l’Agent de trace.
  • sampler : définir une instance de Datadog::Sampler personnalisée. Si cette option est définie, le traceur utilisera cette instance pour déterminer le comportement d’échantillonnage.

Logging personnalisé

Par défaut, tous les logs sont traités par le logger Ruby de base. Lorsque vous utilisez Rails, les messages s’affichent dans le fichier de log de votre application.

Les messages de log du client Datadog sont indiqués par [ddtrace]. Vous pouvez donc les isoler des autres messages.

De plus, vous pouvez modifier le logger par défaut et le remplacer par un logger personnalisé. Pour ce faire, utilisez le paramètre log.

f = File.new("my-custom.log", "w+") # Les messages de log doivent être ajoutés ici
Datadog.configure do |c|
  c.logger = Logger.new(f) # Remplacer le logger par défaut
  c.logger.level = ::Logger::INFO
end

Datadog.logger.info { "Ceci est généralement appelé par le code de tracing" }

Environnement et tags

Par défaut, l’Agent de trace (c’est-à-dire le programme exécuté en arrière-plan pour recueillir les données des différents clients, et non cette bibliothèque) utilise les tags définis dans le fichier de configuration de l’Agent. Consultez notre tutoriel sur les environnements pour en savoir plus.

Vous pouvez configurer l’application de façon à taguer automatiquement vos traces et vos métriques à l’aide des variables d’environnement suivantes :

  • DD_ENV : l’environnement de votre application (p. ex. production, staging, etc.)
  • DD_SERVICE : le nom de service par défaut pour votre application (p. ex. billing-api)
  • DD_VERSION : la version de votre application (p. ex. 2.5, 202003181415, 1.3-alpha, etc.)
  • DD_TAGS : tags personnalisés sous forme de paires de valeurs séparées par des , (p. ex. layer:api,team:intake)
    • Si la variable DD_ENV, DD_SERVICE ou DD_VERSION est définie, tout tag env/service/version correspondant défini dans DD_TAGS sera remplacé.
    • Si la variable DD_ENV, DD_SERVICE ou DD_VERSION n’est pas définie, les tags définis dans DD_TAGS seront utilisés pour env/service/version respectivement.

Ces valeurs peuvent également être remplacées au niveau du traceur :

Datadog.configure do |c|
  c.service = 'billing-api'
  c.env = 'test'
  c.tags = { 'team' => 'qa' }
  c.version = '1.3-alpha'
end

Cela vous permet de définir une valeur différente pour chaque application. De cette façon, il est par exemple possible de recevoir des données à partir de plusieurs applications issues d’environnements différents sur un même host.

Il est également possible d’appliquer directement des tags à des spans spécifiques. En cas de conflit avec les tags définis au niveau de l’application, ces derniers seront remplacés.

Échantillonnage

ddtrace est capable d’échantillonner vos traces. Si l’Agent de trace procède déjà à un échantillonnage pour réduire la bande passante utilisée, l’échantillonnage effectué côté client permet quant à lui d’améliorer les performances.

Datadog::RateSampler effectue l’échantillonnage de vos traces selon le taux que vous avez défini. Par exemple :

# Le taux d'échantillonnage est compris entre 0 (aucune trace n'est conservée) et 1 (toutes les traces sont conservées).
sampler = Datadog::RateSampler.new(0.5) # 50 % des traces sont échantillonnées

Datadog.configure do |c|
  c.tracer.sampler = sampler
end

Échantillonnage prioritaire

L’échantillonnage prioritaire permet de déterminer si une trace doit être conservée ou non en fonction d’un attribut de priorité qui est appliqué aux traces distribuées. La valeur de cet attribut renseigne l’Agent et le backend sur l’importance de la trace.

Le service d’échantillonnage peut définir la priorité sur les valeurs suivantes :

  • Datadog::Ext::Priority::AUTO_REJECT : le service d’échantillonnage a automatiquement décidé de rejeter la trace.
  • Datadog::Ext::Priority::AUTO_KEEP : le service d’échantillonnage a automatiquement décidé de conserver la trace.

L’échantillonnage prioritaire est activé par défaut. Cette fonctionnalité vous permet de vous assurer que vos traces distribuées sont échantillonnées de façon exhaustive. Une fois activée, le service d’échantillonnage attribue automatiquement une priorité de 0 ou de 1 aux traces en fonction de leur service et de leur volume.

Vous pouvez également définir manuellement cette priorité pour supprimer une trace non pertinente ou conserver une trace importante. Pour ce faire, définissez context#sampling_priority sur :

  • Datadog::Ext::Priority::USER_REJECT : l’utilisateur a demandé à rejeter la trace.
  • Datadog::Ext::Priority::USER_KEEP : l’utilisateur a demandé à conserver la trace.

Lorsque vous n’utilisez pas le tracing distribué, vous pouvez modifier la priorité d’une trace à tout moment tant que celle-ci n’est pas finalisée. Cependant, pour que votre changement soit pertinent, vous devez l’effectuer avant toute propagation de contexte (p. ex. avant un fork ou des appels RPC). Dans le cas contraire, les éléments d’une trace distribuée n’auront pas tous la même priorité, et certains éléments seront conservés tandis que d’autres seront rejetés. La trace risquerait alors d’être partiellement stockée et de ne pas être finalisée.

Nous vous conseillons de modifier la priorité le plus tôt possible, dès la création de la span racine.

# On commence par récupérer la span active
span = Datadog.tracer.active_span

# Pour rejeter la trace
span.context.sampling_priority = Datadog::Ext::Priority::USER_REJECT

# Pour conserver la trace
span.context.sampling_priority = Datadog::Ext::Priority::USER_KEEP

Tracing distribué

Le tracing distribué permet à vos traces d’être propagées sur plusieurs applications instrumentées, de façon à ce qu’une requête forme une trace unique et non une trace séparée pour chaque service.

Pour tracer des requêtes sur plusieurs applications différentes, les données suivantes doivent se propager d’une application à l’autre :

PropriétéTypeDescription
Trace IDNombre entierID de la trace. Cette valeur doit être identique pour toutes les requêtes appartenant à la même trace.
Parent Span IDNombre entierID de la span dans le service à l’origine de la requête. Cette valeur est toujours différente pour chaque requête dans une trace.
Sampling PriorityNombre entierPriorité d’échantillonnage de la trace. Cette valeur doit être identique pour toutes les requêtes appartenant à la même trace.

Cette propagation peut être représentée ainsi :

Service A :
  ID Trace :  100000000000000001
  ID Parent : 0
  ID Span :   100000000000000123
  Priorité :  1

  |
  | Requête Service B :
  |   Métadonnées :
  |     ID Trace :  100000000000000001
  |     ID Parent : 100000000000000123
  |     Priorité :  1
  |
  V

Service B :
  ID Trace :  100000000000000001
  ID Parent : 100000000000000123
  ID Span :   100000000000000456
  Priorité :  1

  |
  | Requête Service C :
  |   Métadonnées :
  |     ID Trace :  100000000000000001
  |     ID Parent : 100000000000000456
  |     Priorité :  1
  |
  V

Service C :
  ID Trace :  100000000000000001
  ID Parent : 100000000000000456
  ID Span :   100000000000000789
  Priorité :  1

Via HTTP

Pour les requêtes HTTP distribuées sur plusieurs applications instrumentées, la propagation des métadonnées des traces se fait à l’aide d’en-têtes de requête HTTP :

PropriétéTypeNom de l’en-tête HTTP
Trace IDNombre entierx-datadog-trace-id
Parent Span IDNombre entierx-datadog-parent-id
Sampling PriorityNombre entierx-datadog-sampling-priority

Ainsi :

Service A :
  ID Trace :  100000000000000001
  ID Parent : 0
  ID Span :   100000000000000123
  Priorité :  1

  |
  | Requête HTTP Service B :
  |   En-têtes :
  |     x-datadog-trace-id :  100000000000000001
  |     x-datadog-parent-id : 100000000000000123
  |     x-datadog-sampling-priority :  1
  |
  V

Service B :
  ID Trace :  100000000000000001
  ID Parent : 100000000000000123
  ID Span :   100000000000000456
  Priorité :  1

  |
  | Requête HTTP Service C :
  |   En-têtes :
  |     x-datadog-trace-id :  100000000000000001
  |     x-datadog-parent-id : 100000000000000456
  |     x-datadog-sampling-priority :  1
  |
  V

Service C :
  ID Trace :  100000000000000001
  ID Parent : 100000000000000456
  ID Span :   100000000000000789
  Priorité :  1

Activer le tracing distribué pour des intégrations

De nombreuses intégrations incluses dans ddtrace prennent en charge le tracing distribué. Le tracing distribué est activé par défaut dans l’Agent v7 et la plupart des versions de l’Agent v6. Si nécessaire, il peut être activé via les paramètres de configuration.

  • Si votre application reçoit des requêtes envoyées par des services pour lesquels le tracing distribué est activé, vous devez activer le tracing distribué pour les intégrations qui gèrent ces requêtes (telles que Rails).
  • Si votre application envoie des requêtes à des services pour lesquels le tracing distribué est activé, vous devez activer le tracing distribué pour les intégrations qui envoient ces requêtes (telles que Faraday).
  • Si votre application envoie et reçoit des requêtes nécessitant un tracing distribué, elle doit activer toutes les intégrations qui gèrent ces requêtes.

Pour découvrir comment activer le tracing distribué pour ces intégrations, consultez leur documentation :

Utiliser le propagateur HTTP

Pour faciliter la propagation de ces métadonnées, vous pouvez utiliser le module Datadog::HTTPPropagator.

Côté client :

Datadog.tracer.trace('web.call') do |span|
  # Injecter le contexte de la span dans les en-têtes (`env` doit être un hash)
  Datadog::HTTPPropagator.inject!(span.context, env)
end

Côté serveur :

Datadog.tracer.trace('web.work') do |span|
  # Générer un contexte à partir des en-têtes (`env` doit être un hash)
  context = HTTPPropagator.extract(request.env)
  Datadog.tracer.provider.context = context if context.trace_id
end

Mise en file d’attente des requêtes HTTP

Les traces issues de requêtes HTTP peuvent être configurées de façon à inclure le temps passé par une requête dans la file d’attente d’un serveur Web frontend ou d’un répartiteur de charge avant d’atteindre l’application Ruby.

Cette fonctionnalité est expérimentale et désactivée par défaut.

Pour l’activer, vous devez ajouter un en-tête X-Request-Start ou X-Queue-Start depuis votre serveur Web (tel que Nginx). Voici un exemple de configuration pour Nginx :

# /etc/nginx/conf.d/ruby_service.conf
server {
    listen 8080;

    location / {
      proxy_set_header X-Request-Start "t=${msec}";
      proxy_pass http://web:3000;
    }
}

Ensuite, activez la fonction de mise en file d’attente des requêtes dans l’intégration qui gère la requête.

Si votre application est basée sur Rack, consultez la documentation pour découvrir comment activer cette fonctionnalité.

Pipeline de processing

Certaines applications nécessitent que les traces soient modifiées ou filtrées avant d’être envoyées en amont. Le pipeline de processing permet aux utilisateurs de créer des processeurs servant à mettre en place un tel comportement.

Un processeur peut être n’importe quel objet répondant à un #call et acceptant trace comme argument (qui est un array de Datadog::Spans).

Par exemple :

lambda_processor = ->(trace) do
  # Logique de processing…
  trace
end

class MyCustomProcessor
  def call(trace)
    # Logique de processing…
    trace
  end
end
custom_processor = MyFancyProcessor.new

Le bloc #call d’un processeur doit renvoyer l’objet trace. La valeur renvoyée est ensuite passée au processeur suivant dans le pipeline.

Ces processeurs doivent ensuite être ajoutés au pipeline via Datadog::Pipeline.before_flush :

Datadog::Pipeline.before_flush(lambda_processor, custom_processor)

Vous pouvez également définir ces processeurs en utilisant la syntaxe de bloc abrégée pour Datadog::Pipeline.before_flush :

Datadog::Pipeline.before_flush do |trace|
  trace.delete_if { |span| span.name =~ /forbidden/ }
end

Filtrage

Vous pouvez utiliser le processeur Datadog::Pipeline::SpanFilter pour supprimer les spans lorsque le bloc renvoie une valeur truthy :

Datadog::Pipeline.before_flush(
  # Supprimer les spans associées à une ressource spécifique
  Datadog::Pipeline::SpanFilter.new { |span| span.resource =~ /PingController/ },
  # Supprimer les spans acheminées vers localhost
  Datadog::Pipeline::SpanFilter.new { |span| span.get_tag('host') == 'localhost' }
)

Processing

Vous pouvez utiliser le processeur Datadog::Pipeline::SpanProcessor pour modifier des spans :

Datadog::Pipeline.before_flush(
  # Supprimer le texte correspondant du champ ressource
  Datadog::Pipeline::SpanProcessor.new { |span| span.resource.gsub!(/password=.*/, '') }
)

Mise en corrélation des traces

Dans de nombreux cas, par exemple pour le logging, il peut s’avérer utile de mettre en corrélation les ID de trace à d’autres événements ou flux de données afin de comparer ces différentes sources plus facilement. Le traceur peut générer un identifiant de corrélation pour la trace active via active_correlation, et cet identifiant peut ensuite être utilisé pour décorer les autres sources de données.

# Lorsqu'une trace est active…
Datadog.tracer.trace('correlation.example') do
  # Renvoie #<Datadog::Correlation::Identifier>
  correlation = Datadog.tracer.active_correlation
  correlation.trace_id # => 5963550561812073440
  correlation.span_id # => 2232727802607726424
  correlation.env # => 'production' (récupéré à partir de DD_ENV)
  correlation.service # => 'billing-api' (récupéré à partir de DD_SERVICE)
  correlation.version # => '2.5.17' (récupérée à partir de DD_VERSION)
end

# Lorsqu'une trace n'est pas active…
correlation = Datadog.tracer.active_correlation
# Renvoie #<Datadog::Correlation::Identifier>
correlation = Datadog.tracer.active_correlation
correlation.trace_id # => 0
correlation.span_id # => 0
correlation.env # => 'production' (récupéré à partir de DD_ENV)
correlation.service # => 'billing-api' (récupéré à partir de DD_SERVICE)
correlation.version # => '2.5.17' (récupérée à partir de DD_VERSION)

Logging dans les applications Rails avec Lograge (méthode conseillée)

Après avoir configuré Lograge dans une application Rails, modifiez le bloc custom_options dans le fichier de configuration de votre environnement (p. ex., config/environments/production.rb) pour ajouter les ID de trace :

config.lograge.custom_options = lambda do |event|
  # Récupère les informations de trace pour le thread actuel
  correlation = Datadog.tracer.active_correlation

  {
    # Ajoute les ID en tant que tags au log généré
    :dd => {
      # Pour maintenir le même niveau de précision durant la sérialisation JSON, utiliser des chaînes pour les grands nombres
      :trace_id => correlation.trace_id.to_s,
      :span_id => correlation.span_id.to_s,
      :env => correlation.env.to_s,
      :service => correlation.service.to_s,
      :version => correlation.version.to_s
    },
    :ddsource => ["ruby"],
    :params => event.payload[:params].reject { |k| %w(controller action).include? k }
  }
end

Logging dans les applications Rails

Les applications Rails qui sont configurées avec un logger ActiveSupport::TaggedLogging peuvent ajouter des ID de corrélation en tant que tags aux logs générés. Le logger Rails par défaut applique ce logging avec tags, ce qui simplifie l’ajout de tags de corrélation.

Ajoutez ce qui suit au fichier de configuration de votre environnement Rails :

Rails.application.configure do
  config.log_tags = [proc { Datadog.tracer.active_correlation.to_s }]
end

# Pour :
# DD_ENV = 'production' (Le nom de l'environnement dans lequel votre application est exécutée.)
# DD_SERVICE = 'billing-api' (Le nom de service par défaut de votre application.)
# DD_VERSION = '2.5.17' (La version de votre application.)

# Les requêtes Web vont générer :
# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Started GET "/articles" for 172.22.0.1 at 2019-01-16 18:50:57 +0000
# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Processing by ArticlesController#index as */*
# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206]   Article Load (0.5ms)  SELECT "articles".* FROM "articles"
# [dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=7110975754844687674 dd.span_id=7518426836986654206] Completed 200 OK in 7ms (Views: 5.5ms | ActiveRecord: 0.5ms)

Logging dans les applications Ruby

Pour ajouter des ID de corrélation à votre logger, ajoutez un formateur de log qui récupère les ID de corrélation avec Datadog.tracer.active_correlation, puis ajoutez les ID au message.

Pour vous assurer que vos logs Datadog sont bien mis en corrélation, vérifiez que les éléments suivants sont inclus dans chaque message de log (l’ordre doit être le même) :

  • dd.env=<ENV> : où <ENV> correspond à Datadog.tracer.active_correlation.env. N’incluez pas cet élément si aucun environnement n’est configuré.
  • dd.service=<SERVICE> : où <SERVICE> correspond à Datadog.tracer.active_correlation.service. N’incluez pas cet élément si aucun nom de service par défaut n’est configuré.
  • dd.version=<VERSION> : où <VERSION> correspond à Datadog.tracer.active_correlation.version. N’incluez pas cet élément si aucune version de l’application n’est configurée.
  • dd.trace_id=<ID_TRACE> : <ID_TRACE> a pour valeur Datadog.tracer.active_correlation.trace_id ou 0 en l’absence de trace active lors de la journalisation.
  • dd.span_id=<ID_SPAN> : <ID_SPAN> a pour valeur Datadog.tracer.active_correlation.span_id ou 0 en l’absence de trace active lors de la journalisation.

Par défaut, Datadog::Correlation::Identifier#to_s renvoie dd.env=<ENV> dd.service=<SERVICE> dd.version=<VERSION> dd.trace_id=<ID_TRACE> dd.span_id=<ID_SPAN>.

Si une trace n’est pas active et que ni l’environnement ni la version de l’application ne sont configurés, il renvoie dd.trace_id=0 dd.span_id=0 dd.env= dd.version=.

Voici un exemple pour illustrer cela :

require 'ddtrace'
require 'logger'

ENV['DD_ENV'] = 'production'
ENV['DD_SERVICE'] = 'billing-api'
ENV['DD_VERSION'] = '2.5.17'

logger = Logger.new(STDOUT)
logger.progname = 'my_app'
logger.formatter  = proc do |severity, datetime, progname, msg|
  "[#{datetime}][#{progname}][#{severity}][#{Datadog.tracer.active_correlation}] #{msg}\n"
end

# Lorsqu'aucune trace n'est active
logger.warn('This is an untraced operation.')
# [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=0 dd.span_id=0] This is an untraced operation.

# Lorsqu'une trace est active
Datadog.tracer.trace('my.operation') { logger.warn('This is a traced operation.') }
# [2019-01-16 18:38:41 +0000][my_app][WARN][dd.env=production dd.service=billing-api dd.version=2.5.17 dd.trace_id=8545847825299552251 dd.span_id=3711755234730770098] This is a traced operation.

Configurer la couche de transport

Par défaut, le traceur envoie les données de tracing via Net::HTTP à 127.0.0.1:8126, l’emplacement par défaut du processus de l’Agent de trace Datadog. Toutefois, il est possible de configurer le traceur de façon à ce que ses données soient envoyées vers un autre emplacement ou via un autre protocole.

Certains paramètres par défaut, tels que le hostname et le port, peuvent être configurés via les Paramètres du traceur.

Utiliser l’adaptateur Net::HTTP

L’adaptateur Net envoie les traces via TCP avec Net::HTTP. Il s’agit de l’adaptateur de transport par défaut.

Datadog.configure do |c|
  c.tracer.transport_options = proc { |t|
    # Hostname, port et options supplémentaires. :timeout est défini en secondes.
    t.adapter :net_http, '127.0.0.1', 8126, { timeout: 1 }
  }
end

Utiliser l’adaptateur UnixSocket

L’adaptateur UnixSocket envoie les traces via un socket Unix avec Net::HTTP.

Pour l’utiliser, commencez par configurer votre Agent de trace de façon à ce qu’il effectue son écoute via un socket Unix. Ensuite, configurez le traceur avec :

Datadog.configure do |c|
  c.tracer.transport_options = proc { |t|
    # Spécifier le chemin vers le socket Unix de l'Agent de trace
    t.adapter :unix, '/tmp/ddagent/trace.sock'
  }
end

Utiliser l’adaptateur de test de transport

L’adaptateur Test est un système de transport no-op qui vous permet également de définir un buffer pour les requêtes. Il est idéal pour les procédures de test et les environnements hors production.

Datadog.configure do |c|
  c.tracer.transport_options = proc { |t|
    # Mettre le transport en mode no-op. Les traces ne sont pas conservées.
    t.adapter :test

    # Vous pouvez également spécifier un buffer pour examiner les traces générées.
    # Le buffer doit répondre à '<<'.
    t.adapter :test, []
  }
end

Utiliser un adaptateur de transport personnalisé

Les adaptateurs personnalisés peuvent être configurés ainsi :

Datadog.configure do |c|
  c.tracer.transport_options = proc { |t|
    # Initialiser et passer une instance de l'adaptateur
    custom_adapter = CustomAdapter.new
    t.adapter custom_adapter
  }
end

Métriques

Le traceur et ses intégrations peuvent produire des métriques supplémentaires offrant des informations utiles sur les performances de votre application. Ces métriques sont collectées avec dogstatsd-ruby, et peuvent être envoyées au même Agent Datadog que celui auquel vous envoyez vos traces.

Pour configurer la collecte de métriques pour votre application :

  1. Configurez votre Agent Datadog pour StatsD
  2. Ajoutez gem 'dogstatsd-ruby' à votre Gemfile

Métriques runtime d’application

Si les métriques runtime sont configurées, la bibliothèque de tracing recueille et envoie automatiquement des métriques sur la santé de votre application.

Pour configurer les métriques runtime, ajoutez la configuration suivante :

# config/initializers/datadog.rb
require 'datadog/statsd'
require 'ddtrace'

Datadog.configure do |c|
  # Définir sur `true` pour activer la collecte de métriques runtime. Valeur par défaut : `false`
  # Ce paramètre peut également être défini avec DD_RUNTIME_METRICS_ENABLED=true
  c.runtime_metrics.enabled = true

  # Facultatif : vous pouvez configurer l'instance DogStatsD utilisée pour envoyer les métriques runtime.
  # Statsd est automatiquement configuré avec les paramètres par défaut si `dogstatsd-ruby` est disponible.
  # Vous pouvez utiliser le host et le port de l'Agent Datadog pour la configuration. Valeur par défaut : 'localhost:8125'.
  c.runtime_metrics.statsd = Datadog::Statsd.new
end

Consultez la documentation sur Dogstatsd pour en savoir plus sur la configuration de Datadog::Statsd.

Les statistiques envoyées comprennent :

NomTypeDescription
runtime.ruby.class_countgaugeNombre de classes dans l’espace mémoire.
runtime.ruby.thread_countgaugeNombre de threads.
runtime.ruby.gc.*.gaugeStatistiques de nettoyage de la mémoire (une par valeur dans GC.stat)

En outre, toutes les métriques comprennent les tags suivants :

NomDescription
languageLangage de programmation tracé. (Ex. : ruby)
serviceListe des services associés à cette métrique.

OpenTracing

Pour en savoir plus sur la configuration de Datadog avec OpenTracing, consultez la section Démarrage rapide pour OpenTracing.

Configurer les paramètres du traceur Datadog

Le traceur Datadog sous-jacent peut être configuré en passant des options (qui correspondent à Datadog::Tracer) lors de la configuration du traceur global :

# Où `options` correspond à un hash d'options spécifiées à Datadog::Tracer
OpenTracing.global_tracer = Datadog::OpenTracer::Tracer.new(options)

Il peut également être configuré en utilisant Datadog.configure, tel que décrit dans la section Paramètres du traceur.

Activer et configurer des intégrations

Par défaut, la configuration d’OpenTracing avec Datadog n’active aucune instrumentation supplémentaire assurée par Datadog. Vous ne recevrez que les spans et les traces provenant de l’instrumentation OpenTracing intégrée à votre application.

Toutefois, des instrumentations supplémentaires fournies par Datadog peuvent être activées conjointement à OpenTracing via Datadog.configure, afin d’optimiser encore plus votre tracing. Pour ce faire, consultez la section Instrumenter des intégrations pour obtenir plus de détails.

Formats de sérialisation pris en charge

TypePrise en chargeInformations supplémentaires
OpenTracing::FORMAT_TEXT_MAPOui
OpenTracing::FORMAT_RACKOuiNotez qu’en raison de la perte de résolution liée au format Rack, les majuscules dans les noms d’éléments transmis lors de l’aller-retour doivent être remplacées par des minuscules, et le caractère - par le caractère _. Nous vous conseillons d’éviter d’utiliser ces caractères ou de prévoir une étape pour les gérer à la réception.
OpenTracing::FORMAT_BINARYNon