Conventions sémantiques OpenTelemetry

Cette skill gouverne la sélection correcte, le placement et la validation des attributs de télémétrie et des instruments de métrique selon la spécification Conventions sémantiques OpenTelemetry. Pour le nommage des spans, les types de spans et les codes de statut des spans, voir la skill otel-instrumentation.

Le Attribute Registry est la source unique de vérité pour tous les attributs définis.

Rules

Documentation officielle

• Attribute Registry
• Semantic Conventions Specification
• Semantic Conventions Repository
• Dash0 Semantic Conventions
• Dash0 Semantic Conventions Explainer

Comment sélectionner le bon attribut

1. Recherchez d'abord dans le registre — Recherchez le concept dans le Attribute Registry. Utilisez le nom standard s'il existe (par exemple, préférez http.request.method à un attribut personnalisé custom.http.verb). Les noms personnalisés fragmentent les requêtes et cassent les outils — ne créez un attribut personnalisé que si aucune entrée du registre ne couvre le concept.
2. Vérifiez la stabilité — Préférez les attributs stable ; notez tout attribut experimental qui pourrait changer. Voir versioning.
3. Placez au niveau correct — Les attributs de ressource décrivent l'entité produisant la télémétrie ; les attributs de span/log décrivent l'opération individuelle. Ne dupliquez pas entre les niveaux. Une fois qu'un attribut est à un niveau donné, conservez-le là de façon cohérente dans tous les services.
4. Vérifiez la cardinalité — Les valeurs des attributs de métrique doivent être de faible cardinalité (ensemble limité). Les données variables (IDs utilisateur, chemins de requête avec paramètres) appartiennent aux attributs de span, non aux attributs de métrique.
5. Attribut personnalisé en dernier recours — Ne créez un attribut personnalisé que si aucune entrée du registre ne couvre le concept. Documentez la décision et suivez le schéma de nommage org.namespace.attribute_name.

Exemple : sélection d'attribut correcte vs incorrecte

# Correct — utilise l'attribut du registre pour la méthode HTTP
span.set_attribute("http.request.method", "GET")

# Incorrect — invente un attribut personnalisé pour un concept déjà dans le registre
span.set_attribute("custom.http.verb", "GET")

Exemple : placement de l'attribut de ressource vs span

# Correct — l'identité du service est un attribut de ressource
resource = Resource({"service.name": "checkout-service", "service.version": "2.1.0"})

# Correct — les données spécifiques à l'opération sont un attribut de span
span.set_attribute("http.request.method", "POST")
span.set_attribute("http.response.status_code", 201)

# Incorrect — placer un attribut de niveau ressource sur chaque span
span.set_attribute("service.name", "checkout-service")  # appartient à la ressource

Exemple : violation de cardinalité dans les attributs de métrique

# Correct — l'attribut de métrique utilise une valeur limitée et de faible cardinalité
histogram.record(duration_ms, {"http.request.method": "GET", "http.response.status_code": 200})

# Incorrect — des valeurs illimitées comme attributs de métrique font exploser le coût du stockage et des requêtes
histogram.record(duration_ms, {"user.id": "u-839201", "url.path": "/orders/839201"})
# Fix: placez plutôt les valeurs de haute cardinalité dans les attributs de span
span.set_attribute("user.id", "u-839201")
span.set_attribute("url.path", "/orders/839201")