Attributs OpenTelemetry Dynatrace : service.name, enrichissement et allow-list

Attributs OpenTelemetry Dynatrace : posez service.name, enrichissez avec k8sattributes, gérez l’allow-list des spans et vérifiez en SaaS comme en Managed.
Attributs OpenTelemetry Dynatrace : service.name, enrichissement et allow-list

Trois services nommés unknown_service:python, des traces impossibles à rattacher à un pod, des attributs métier invisibles dans les requêtes : la plupart des déceptions après une première ingestion OTLP viennent des attributs. Bien poser les attributs OpenTelemetry Dynatrace utilise pour construire ses entités, c’est la différence entre une carte de services lisible et un tas de spans orphelins.

Objectif : à la fin de ce tutoriel, vos services OTel portent les attributs de ressource standard, le Collector les enrichit avec le contexte Kubernetes et hôte, et vous savez vérifier quels attributs sont réellement stockés et requêtables. Le contenu vaut pour Dynatrace SaaS (Grail, DQL) et Dynatrace Managed. La gestion des attributs de span diffère entre les deux : c’est signalé dans l’étape concernée.

Pour l’architecture du Collector, voir le Collector OpenTelemetry sur Kubernetes.

Le problème : des données sans identité

Un span sans service.name correct ne se rattache à aucun service utile. Un span sans attributs Kubernetes ne mène pas au pod qui a crashé. Pendant un incident, l’astreinte perd des minutes à deviner « qui » a produit la donnée, et le MTTR s’en ressent. Les attributs de ressource répondent à cette question une fois pour toutes.

Prérequis

  • Des applications instrumentées avec un SDK OpenTelemetry (par exemple l’agent OpenTelemetry Java).
  • Un Collector otelcol-contrib ou une distribution incluant k8sattributes, resourcedetection, resource et transform. Dans les versions récentes du Collector contrib, k8sattributes et resourcedetection s’appellent k8s_attributes et resource_detection ; les anciens noms, utilisés ci-dessous, restent acceptés comme alias dépréciés.
  • Un token Dynatrace avec les scopes d’ingestion OTLP (traces, métriques, logs).

Ressource ou span : deux niveaux d’attributs

  • Attributs de ressource : décrivent l’émetteur et valent pour toute la télémétrie d’un processus. Exemples : service.name, service.version, deployment.environment, k8s.pod.name, host.name.
  • Attributs de span : décrivent une opération. Exemples : http.request.method, db.system, order.id.

Règle simple : ce qui ne change pas pendant la vie du processus va dans la ressource. Les traces, les métriques et les logs partagent alors les mêmes clés, ce qui rend la corrélation possible.

Configurer les attributs OpenTelemetry Dynatrace attend

Étape 1 : poser les attributs de ressource dans l’application

# extrait d'un Deployment Kubernetes
env:
  - name: OTEL_SERVICE_NAME
    value: "checkout"
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: OTEL_RESOURCE_ATTRIBUTES
    value: "service.version=2.3.0,service.namespace=shop,deployment.environment=prod,k8s.pod.name=$(POD_NAME)"

Lignes critiques : OTEL_SERVICE_NAME l’emporte sur un service.name placé dans OTEL_RESOURCE_ATTRIBUTES. La syntaxe $(POD_NAME) est résolue par Kubernetes, à condition que la variable soit déclarée avant. Note : les conventions sémantiques récentes renomment deployment.environment en deployment.environment.name ; choisissez une clé et gardez-la partout.

Étape 2 : enrichir dans le Collector

Le Collector ajoute ce que l’application ignore : namespace, nœud, workload, cloud.

processors:
  k8sattributes:
    auth_type: serviceAccount
    passthrough: false
    extract:
      metadata:
        - k8s.namespace.name
        - k8s.deployment.name
        - k8s.pod.name
        - k8s.pod.uid
        - k8s.node.name
    pod_association:
      - sources:
          - from: resource_attribute
            name: k8s.pod.uid
      - sources:
          - from: connection
  resourcedetection:
    detectors: [env, system]
    timeout: 2s
    override: false
  resource:
    attributes:
      - key: k8s.cluster.name
        value: "prod-eu-1"
        action: upsert

k8sattributes exige un ServiceAccount avec les droits get, list et watch sur les pods, namespaces et ReplicaSets. override: false empêche la détection d’écraser des valeurs déjà posées par l’application.

Étape 3 : enrichissement Dynatrace sur les hôtes avec OneAgent

Si OneAgent tourne sur l’hôte, il peut fournir des fichiers d’enrichissement contenant des attributs comme dt.entity.host, qui rattachent la télémétrie OTel aux entités découvertes par OneAgent. Le chemin et le format de ces fichiers sont décrits dans la documentation Dynatrace (rubrique sur l’enrichissement des données OpenTelemetry) : vérifiez-les pour votre version plutôt que de les coder en dur. Sans OneAgent, l’identité repose uniquement sur les attributs des étapes 1 et 2.

Étape 4 : nettoyer les attributs sensibles et inutiles

Supprimez les données personnelles et les attributs à forte cardinalité avant l’export :

processors:
  transform/clean:
    error_mode: ignore
    trace_statements:
      - context: span
        statements:
          - delete_key(attributes, "user.email")
          - replace_pattern(attributes["url.full"], "token=[^&]+", "token=***")
  batch: {}

service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [k8sattributes, resourcedetection, resource, transform/clean, batch]
      exporters: [otlphttp/dynatrace]

Étape 5 : comprendre l’allow-list des attributs de span

Dynatrace ne traite pas tous les attributs de span de la même façon selon le déploiement :

  • Dynatrace Managed (et SaaS sans stockage des spans dans Grail) : les attributs de span personnalisés doivent être autorisés explicitement dans les réglages de l’environnement (une liste d’attributs autorisés dans la section de surveillance des services côté serveur ; le libellé exact dépend de la version). Un attribut absent de la liste n’est pas conservé. Des options de masquage existent aussi.
  • Dynatrace SaaS avec Grail : les attributs sont en général stockés avec les spans et requêtables en DQL, sous réserve des règles de traitement et de masquage configurées (OpenPipeline, réglages de confidentialité).

Le comportement exact évolue : vérifiez la page de la documentation Dynatrace consacrée aux attributs de span pour votre environnement. Les attributs de ressource standard, eux, servent dans les deux cas à identifier le service.

Comment vérifier que ça fonctionne

  1. Côté Collector : ajoutez temporairement l’exporteur debug avec verbosity: detailed et lisez les attributs de ressource dans les logs du Collector.
  2. Dynatrace SaaS : vérifiez la présence des attributs dans un notebook :
    fetch spans, from: now() - 30m
    | filter service.name == "checkout"
    | fields start_time, span.name, service.version, k8s.namespace.name, k8s.pod.name
    | limit 20
    

    Une colonne vide signale un attribut non posé ou non conservé.

  3. Dynatrace Managed : ouvrez une trace distribuée du service et consultez les attributs du span ; un attribut personnalisé absent doit d’abord être ajouté à la liste autorisée.
  4. Nom du service : si unknown_service apparaît, OTEL_SERVICE_NAME n’est pas lu par le processus.

Bonnes pratiques

  • Un nom de service stable et unique par composant ; la version dans service.version, jamais dans le nom.
  • Mêmes attributs de ressource sur traces, métriques et logs, pour passer d’un signal à l’autre (voir logs OpenTelemetry avec trace_id).
  • Pas d’identifiant utilisateur ni de valeur à forte cardinalité dans les attributs de ressource.
  • Filtrez vos SLO par deployment.environment pour ne pas mélanger test et production (voir SLO OpenTelemetry en DQL).
  • Documentez la convention d’attributs de l’équipe : moins de toil à chaque nouveau service.

Questions fréquentes

Pourquoi mon service apparaît-il deux fois ?

Souvent parce que deux valeurs de service.name coexistent, ou parce qu’OneAgent et le SDK OTel instrumentent le même processus. Harmonisez le nom et vérifiez les doublons.

Faut-il préfixer mes attributs métier ?

Oui, un espace de noms propre (shop.order.id) évite les collisions avec les conventions sémantiques présentes et futures.

Le processeur k8sattributes fonctionne-t-il hors Kubernetes ?

Non. Hors Kubernetes, utilisez resourcedetection avec les détecteurs adaptés (système, cloud) et le processeur resource.

Conclusion

Les attributs de ressource sont l’identité de votre télémétrie. Posez-les dans l’application, enrichissez-les dans le Collector, nettoyez-les avant l’export et vérifiez ce que Dynatrace conserve, en SaaS comme en Managed. Références : les conventions sémantiques de ressource et la documentation Dynatrace OpenTelemetry.

span.observer est un blog indépendant de la communauté, non affilié à Dynatrace LLC. Dynatrace est une marque de son propriétaire.

Total
0
Shares
Laisser un commentaire

Votre adresse e-mail ne sera pas publiée. Les champs obligatoires sont indiqués avec *

Previous Post
Tail sampling OpenTelemetry avant Dynatrace : maîtriser coûts et volume de traces

Tail sampling OpenTelemetry avant Dynatrace : maîtriser coûts et volume de traces

Next Post
Superviser collector OpenTelemetry : sa télémétrie interne dans Dynatrace (SaaS et Managed)

Superviser collector OpenTelemetry : sa télémétrie interne dans Dynatrace (SaaS et Managed)

Related Posts