Instrumenter une méthode personnalisée pour analyser en détail votre logique opérationnelle

Docs > APM > Guides de tracing > Instrumenter une méthode personnalisée pour analyser en détail votre logique opérationnelle

Temps de lecture : 8 minutes

Afin de vous offrir une visibilité optimale sur votre logique opérationnelle, l’APM Datadog vous permet de personnaliser les spans qui composent vos traces en fonction de vos besoins et de votre implémentation. Vous êtes ainsi libre de tracer n’importe quelle méthode utilisée dans votre code, ou même des composants spécifiques au sein d’une méthode. Utilisez cette fonctionnalité pour optimiser et surveiller les zones critiques de votre application avec le niveau de granularité qui vous convient.

En plus d’instrumenter un vaste nombre de frameworks par défaut, tels que des services Web, des bases de données et des caches, Datadog vous permet d’instrumenter votre propre logique opérationnelle afin d’obtenir exactement le niveau de visibilité dont vous avez besoin. En créant des spans pour des méthodes, vous pouvez optimiser les calculs de temps et surveiller les erreurs à l’aide du flamegraph et des monitors de l’APM.

Instrumenter votre code

Suivez cet exemple pour instrumenter votre code.

Ces exemples vous montreront comment tracer l’intégralité de la méthode BackupLedger.write afin de mesurer son temps d’exécution et son statut. BackupLedger.write est une action qui enregistre le statut actuel d’un registre de transactions en mémoire avant d’effectuer un appel vers une base de données de paiements pour publier une nouvelle facturation client. Cette action se produit lorsque l’endpoint charge du service de paiements est atteint :

La span http.request POST /charge/ prend beaucoup de temps et ne présente aucune span enfant directe : une instrumentation plus poussée est donc probablement nécessaire pour mieux comprendre son comportement. Selon le langage de programmation que vous utilisez, vous devez décorer vos fonctions différemment :

Dans le langage Java, l’APM Datadog vous permet d’instrumenter votre code pour générer des spans personnalisées en utilisant des décorateurs de méthode ou en instrumentant des blocs de code spécifiques.

Instrumenter une méthode avec un décorateur :

Cet exemple ajoute une span à la méthode BackupLedger.write, qui ajoute de nouvelles lignes à un registre de transactions. Une span est ajoutée pour suivre toutes les transactions publiées en tant qu’une seule unité.

import datadog.trace.api.Trace

public class BackupLedger {

  // Utiliser l'annotation @Trace pour tracer des méthodes personnalisées
  @Trace
  public void write(List<Transaction> transactions) {
    for (Transaction transaction : transactions) {
      ledger.put(transaction.getId(), transaction);
    }

    // [...]
  }
}

Instrumenter un bloc de code spécifique :

Cet exemple ajoute des spans enfant à la span BackupLedger.write créée ci-dessus. Cette méthode ajoute une span enfant pour chaque transaction dans le registre et un tag personnalisé avec l’ID de transaction spécifique.

import datadog.trace.api.Trace;
import io.opentracing.Scope;
import io.opentracing.Tracer;
import io.opentracing.util.GlobalTracer;

public class BackupLedger {

  // Utiliser l'annotation `@Trace` pour tracer des méthodes personnalisées
  @Trace
  public void write(List<Transaction> transactions) {
    for (Transaction transaction : transactions) {
      // Utilisez la fonction `GlobalTracer` pour tracer des blocs de code en ligne
      Tracer tracer = GlobalTracer.get();
      try (Scope scope = tracer.buildSpan("BackupLedger.persist").startActive(true)) {
        // Ajoutez des métadonnées personnalisées à la span
        scope.span().setTag("transaction.id", transaction.getId());
        ledger.put(transaction.getId(), transaction);
      }
    }

    // [...]
  }
}

Dans le langage Python, l’APM Datadog vous permet d’instrumenter votre code pour générer des spans personnalisées en utilisant des décorateurs de méthode ou en instrumentant des blocs de code spécifiques.

Instrumenter une méthode avec un décorateur :

from ddtrace import tracer

class BackupLedger:

    # Utiliser le décorateur `tracer.wrap` pour tracer des méthodes personnalisées
    @tracer.wrap()
    def write(self, transactions):
        for transaction in transactions:
            self.ledger[transaction.id] = transaction

        # [...]

Instrumenter un bloc de code spécifique :

from ddtrace import tracer

class BackupLedger:

    # Utiliser le décorateur `tracer.wrap` pour tracer des méthodes personnalisées
    @tracer.wrap()
    def write(self, transactions):
        for transaction in transactions:
            # Utiliser le gestionnaire de contexte `tracer.trace` pour tracer directement des blocs de code
            with tracer.trace('BackupLedger.persist') as span:
                # Ajouter des métadonnées à la span persist_transaction
                span.set_tag('transaction.id', transaction.id)
                self.ledger[transaction.id] = transaction

        # [...]

Dans le langage Ruby, l’APM Datadog vous permet d’instrumenter votre code pour générer des spans personnalisées en instrumentant des codes de bloc spécifiques.

Cet exemple crée une span pour l’appel de la méthode BackupLedger.write et une span enfant pour chaque transaction publiée dans le registre avec un tag personnalisé spécifiant l’ID de transaction spécifique.

require 'ddtrace'

class BackupLedger

  def write(transactions)
    # Utiliser la méthode globale `Datadog::Tracing.trace` pour tracer directement des blocs de code
    Datadog::Tracing.trace('BackupLedger.write') do |method_span|
      transactions.each do |transaction|
        Datadog::Tracing.trace('BackupLedger.persist') do |span|
          # Ajouter des métadonnées personnalisées à la span "persist_transaction" span
          span.set_tag('transaction.id', transaction.id)
          ledger[transaction.id] = transaction
        end
      end
    end

    # [...]
  end
end

Dans le langage Go, l’APM Datadog vous permet d’instrumenter votre code pour générer des spans personnalisées en instrumentant des codes de bloc spécifiques.

Cet exemple crée une span pour chaque transaction publiée dans le registre et ajoute un tag personnalisé avec l’ID de transaction spécifique à la span.

package ledger

import "gopkg.in/DataDog/dd-trace-go.v1/ddtrace/tracer"

// [...]

func (bl *BackupLedger) write(ctx context.Context, transactions []*Transaction) (err error) {
  // Tracer la fonction `write` et capturer l'erreur le cas échéant
  span, ctx := tracer.StartSpanFromContext(ctx, "BackupLedger.write")
  defer func() {
    span.Finish(tracer.WithError(err))
  }()

  for _, t := range transactions {
    if err := bl.persistTransaction(ctx, t); err != nil {
      return err
    }
  }
  return nil
}

// persistTransaction est une fonction interne que vous pouvez tracer. Vous pouvez utiliser la
// même méthode que précédemment, car le `ctx` transmis inclut des références de span par défaut
// pour créer une relation parent/enfant.
func (bl *BackupLedger) persistTransaction(ctx context.Context, transaction *Transaction) error {
  id := transaction.ID
  span, _ := tracer.StartSpanFromContext(ctx, "BackupLedger.persist", tracer.Tag("transaction_id", id))
  defer span.Finish()

  if t, ok := bl.transactions[id]; ok {
    return errors.New("duplicate entry")
  }
  bl.transactions[id] = transaction
  return nil
}

Dans le langage Node.js, l’APM Datadog vous permet d’instrumenter votre code pour générer des spans personnalisées en instrumentant des codes de bloc spécifiques.

Cet exemple crée une span pour l’appel de la méthode BackupLedger.write et une span enfant pour chaque transaction publiée dans le registre, avec un tag personnalisé spécifiant l’ID de transaction spécifique.

const tracer = require('dd-trace')

function write (transactions) {
  // Utiliser le gestionnaire de contextes `tracer.trace` pour tracer directement des blocs de code
  tracer.trace('BackupLedger.write', () => {
    for (const transaction of transactions) {
      // Ajouter des métadonnées personnalisées à la span persist_transaction
      span.setTag('transaction.id', transaction.id)
      this.ledger[transaction.id] = transaction
    }
  })

  // [...]
}

Dans le langage .NET, l’APM Datadog vous permet d’instrumenter votre code pour générer des spans personnalisées en instrumentant des codes de bloc spécifiques.

Cet exemple crée une span pour chaque transaction publiée dans le registre et ajoute un tag personnalisé avec l’ID de transaction spécifique à la span.

using Datadog.Trace;

public void Write(List<Transaction> transactions)
{
    // Utiliser le traceur global pour tracer directement des blocs de code
    using (var scope = Tracer.Instance.StartActive("BackupLedger.write"))
    {
        foreach (var transaction in transactions)
        {
            using (var scope = Tracer.Instance.StartActive("BackupLedger.persist"))
            {
                // Ajouter des métadonnées personnalisées à la span
                scope.Span.SetTag("transaction.id", transaction.Id);
                this.ledger[transaction.Id] = transaction;
            }
        }
    }

    // [...]
}

Dans le langage PHP, l’APM Datadog vous permet d’instrumenter votre code pour générer des spans personnalisées en utilisant des wrappers de méthode ou en instrumentant des blocs de code spécifiques.

Instrumenter une méthode avec un wrapper :

<?php
  class BackupLedger {

    public function write(array $transactions) {
      foreach ($transactions as $transaction) {
        $this->transactions[$transaction->getId()] = $transaction;
      }

      # [...]
    }
  }

  // Pour ddtrace < v0.47.0 utiliser \dd_trace_method()
  \DDTrace\trace_method('BackupLedger', 'write', function (\DDTrace\SpanData $span) {
    // SpanData::$name correspond à 'ClassName.methodName' par défaut si non défini (>= v0.47.0)
    $span->name = 'BackupLedger.write';
    // SpanData::$resource correspond à SpanData::$name par défaut si non défini (>= v0.47.0)
    $span->resource = 'BackupLedger.write';
    $span->service = 'php';
  });
?>

Instrumenter un bloc de code spécifique :

<?php
  class BackupLedger {

    public function write(array $transactions) {
      foreach ($transactions as $transaction) {
        // Utiliser le traceur global pour tracer directement des blocs de code
        $scope = \DDTrace\GlobalTracer::get()->startActiveSpan('BackupLedger.persist');

        // Ajouter des métadonnées personnalisées à la span
        $scope->getSpan()->setTag('transaction.id', $transaction->getId());
        $this->transactions[$transaction->getId()] = $transaction;

        // Fermer la span
        $scope->close();
      }

      # [...]
    }
  }

  // Pour ddtrace < v0.47.0 utilisez \dd_trace_method()
  \DDTrace\trace_method('BackupLedger', 'write', function (\DDTrace\SpanData $span) {
    // SpanData::$name correspond à 'ClassName.methodName' par défaut si non défini (>= v0.47.0)
    $span->name = 'BackupLedger.write';
    // SpanData::$resource correspond à SpanData::$name par défaut si non défini (>= v0.47.0)
    $span->resource = 'BackupLedger.write';
    $span->service = 'php';
  });
?>

Visualiser vos nouvelles spans personnalisées depuis l’interface de Datadog

Maintenant que vous avez instrumenté votre logique opérationnelle, il est temps de découvrir les résultats dans l’interface de l’APM Datadog.

Accédez à la liste des services, identifiez le service auquel vous avez ajouté des spans personnalisées, puis accédez à la page Service. Sur la page Service, cliquez sur la ressource spécifique que vous avez ajoutée, modifiez le filtre d’intervalle sur The past 15 minutes et faites défiler la page jusqu’au tableau Span Summary :
Vous devriez maintenant apercevoir les nouvelles spans que vous avez ajoutées

Le tableau Span Summary affiche des informations agrégées concernant les spans qui composent vos traces. Utilisez-le pour identifier les spans qui se répètent pendant des durées anormales, ce qui peut être le signe de boucles ou de mauvaises performances d’accès à la base de données (comme le problème n+1).

Faites défiler la page jusqu’à la liste des traces et cliquez sur l’une de vos traces.

Vous avez maintenant réussi à ajouter des spans personnalisées à votre code, et celles-ci sont désormais visibles sur le flamegraph ainsi que sur la page App Analytics. Pour les rendre encore plus performantes et continuer à tirer pleinement parti des outils Datadog, vous pouvez maintenant ajouter des tags personnalisés à vos spans.