Présentation

L’enrichissement des traces APM joint automatiquement les données d’évaluation des feature flags à vos traces APM. Lorsqu’un feature flag est évalué au cours d’une requête tracée, le SDK enregistre quels feature flags ont été évalués et quelles variants ont été retournées. Ces données sont écrites dans le span racine et traitées côté serveur afin que vous puissiez :

• Filtrer les traces par flag variant dans Trace Explorer à l’aide de facettes @feature_flags.<flag_key>:<variant>.
• Déboguer les problèmes liés aux feature flags en visualisant quels feature flags étaient actifs lorsqu’une erreur s’est produite.

L’enrichissement des traces APM est disponible dans les SDK suivants :

Prérequis

Avant de configurer l’enrichissement des traces APM, confirmez les points suivants :

• Les feature flags côté serveur sont déjà configurés et les feature flags sont évalués dans votre application.
• APM tracing est activé et les traces sont transmises à Datadog.

Fonctionnement de l’enrichissement des traces APM

Lorsque l’enrichissement des traces APM est activé, le fournisseur OpenFeature de Datadog s’intègre au cycle de vie de l’évaluation :

1. Chaque fois qu’un feature flag est évalué, le SDK capture les métadonnées d’évaluation (flag serial ID, targeting key et default fallback value).
2. Les métadonnées sont accumulées sur le span racine de la trace actuelle.
3. Lorsque le span racine se termine, le SDK écrit les données accumulées sous forme de span tags compacts (ffe_flags_enc, ffe_subjects_enc, ffe_runtime_defaults).
4. Le backend Datadog décode ces tags et écrit des facettes @feature_flags.<flag_key> lisibles par l’homme dans le span, ce qui les rend consultables dans Trace Explorer.

Les tags côté SDK sont uniquement destinés au transport et sont supprimés côté serveur. Les tags visibles dans Trace Explorer sont les facettes @feature_flags.<flag_key> décodées.

Activer l’enrichissement des traces APM

Définissez la variable d’environnement suivante pour activer l’enrichissement des spans :

DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED=true

La variable d’environnement d’enrichissement est prise en charge par tous les SDK côté serveur compatibles. Aucune modification de code n’est requise. L’activation de la variable active automatiquement le hook d’enrichissement lors de l’initialisation du fournisseur Datadog OpenFeature. Node.js prend également en charge la configuration au niveau du code, comme indiqué dans les onglets de langage ci-dessous.

Configuration spécifique au langage

package main

import (
    "log"

    "github.com/DataDog/dd-trace-go/v2/ddtrace/tracer"
    ddopenfeature "github.com/DataDog/dd-trace-go/v2/openfeature"
    "github.com/open-feature/go-sdk/openfeature"
)

func main() {
    tracer.Start()
    defer tracer.Stop()

    provider, err := ddopenfeature.NewDatadogProvider(ddopenfeature.ProviderConfig{})
    if err != nil {
        log.Fatalf("Failed to create provider: %v", err)
    }
    if ddProvider, ok := provider.(*ddopenfeature.DatadogProvider); ok {
        defer ddProvider.Shutdown()
    }

    if err := openfeature.SetProviderAndWait(provider); err != nil {
        log.Fatalf("Failed to set provider: %v", err)
    }

    client := openfeature.NewClient("my-service")
    // Flag evaluations now enrich APM spans automatically
}

import dev.openfeature.sdk.OpenFeatureAPI;
import dev.openfeature.sdk.Client;
import datadog.trace.api.openfeature.Provider;

OpenFeatureAPI api = OpenFeatureAPI.getInstance();
api.setProviderAndWait(new Provider());
Client client = api.getClient("my-app");
// Flag evaluations now enrich APM spans automatically

import tracer from 'dd-trace';

tracer.init({
  experimental: {
    flaggingProvider: {
      enabled: true,
      spanEnrichment: {
        enabled: true,
      },
    },
  },
});

Vérifier l’enrichissement des traces APM

Après le déploiement avec l’enrichissement des spans activé :

1. Déclenchez des requêtes dans votre application qui évaluent les feature flags.
2. Accédez à Trace Explorer et recherchez une trace récente de votre service.
3. Ouvrez une trace et recherchez les attributs @feature_flags.<flag_key> sur le span racine.

Le SDK écrit des tags encodés compacts (ffe_flags_enc, ffe_subjects_enc, ffe_runtime_defaults) sur le span racine. Le backend Datadog les décode et produit des facettes @feature_flags.<flag_key> lisibles par l’homme. Ce traitement prend quelques secondes après l’ingestion du span.

Après le traitement backend, le span racine contient des attributs tels que les exemples suivants :

Chaque clé d’attribut est @feature_flags.<flag_key> et la valeur est la variante renvoyée par l’évaluation.

Dépannage

Si les attributs @feature_flags.<flag_key> n’apparaissent pas sur vos traces :

• Confirmez que l’enrichissement des spans est activé (DD_EXPERIMENTAL_FLAGGING_PROVIDER_SPAN_ENRICHMENT_ENABLED=true).
• Vérifiez que votre application évalue les feature flags pendant les requêtes tracées. L’enrichissement ne se produit que lorsqu’un feature flag est évalué alors qu’une trace est active.
• Attendez quelques secondes après l’ingestion du span. Les facettes @feature_flags.<flag_key> sont dérivées par le traitement backend et n’apparaissent pas dans les métadonnées brutes du span.
• Pour le débogage, inspectez les métadonnées brutes du span pour le tag ffe_flags_enc. Si ce tag est présent, le SDK émet des données d’enrichissement. Soit le backend ne l’a pas encore traité, soit le feature flag gate n’est pas activé pour votre organisation.
• Si les feature flags ne sont pas évalués du tout, consultez Server-Side Feature Flags pour la configuration et le dépannage spécifique au langage.

Recherchez et filtrez par flag variant

Ces exemples utilisent les facettes @feature_flags.<flag_key> pour filtrer les traces dans Trace Explorer:

Utilisez des traces enrichies dans Datadog

Les attributs des feature flags sur les traces sont disponibles dans Datadog :

• Monitors : Alertez lorsque le nombre d’erreurs pour un flag variant spécifique dépasse un seuil afin de détecter les régressions spécifiques à ce flag variant.
• Dashboards : Ajoutez un widget de série temporelle comparant la latence p99 entre les flag variants en utilisant @feature_flags.<flag_key> comme dimension de regroupement.
• Notebooks : Créez un notebook d’investigation comparant les performances entre les variantes de flag de fonctionnalité.
• Visualizations : Utilisez la vue Top List dans Trace Explorer pour vérifier que la distribution du trafic de déploiement correspond à vos règles de ciblage.

Limites

Le SDK applique les limites suivantes par span pour limiter la taille de la charge utile :

Les évaluations dépassant ces limites sont supprimées pour ce span.

Pour aller plus loin

Documentation, liens et articles supplémentaires utiles:

Feature Flags côté serveurDOCUMENTATION Configurer les métriques d'évaluation des Feature Flags côté serveurGUIDE Trace ExplorerDOCUMENTATION