API de trace : décorer les étendues avec un attribut

Ce document explique comment ajouter un attribut aux données trace envoyées à l' API de trace afin que les étendues affichent des propriétés spécifiques dans l'UI.

Pourquoi décorer vos travées ?

Lorsque vous envoyez des données à notre API de trace, vous pouvez ajouter un attribut personnalisé aux étendues. Par exemple, vous pouvez décider d'ajouter un attribut tel que customer.id ou user.id afin de vous aider à analyser vos données trace .

Certaines valeurs d'attribut attendues amènent notre UI de tracing distribué à afficher certaines propriétés et détailstrace spécifiques. Par exemple, si une plage possède un attribut avec un préfixe error., l'UI affiche cette plage avec une erreur. Par exemple, une étendue avec un attribut ayant un préfixe db. sera affichée comme une étendue datastore dans l'UI et sa requête datastore sera mise en surbrillance.

Décorer vos travées pour afficher des propriétés spécifiques dans notre UI peut vous aider à :

Mieux comprendre la structure de vos données de trace.
Résolvez les problèmes plus facilement.

Comment décorer vos travées avec des attributs

Ce tableau explique comment faire en sorte que les étendues envoyées à l'API de trace s'affichent avec des propriétés spécifiques dans l'UI. Pour les descriptions de propriétés, voir span properties.

Propriété de portée souhaitée	Indicateur UI	Comment ajouter une propriété
Erreurs		Utilisez un attribut avec un préfixe `error.` . Par exemple : `error.message`.
Externe		Utilisez un attribut avec un préfixe `http.` . Par exemple : `http.method`. Un span apparaîtra également comme externe s'il a un enfant provenant d'une entité différente. Pour être indexé sur la page Services externes, `http.url` ou `net.peer.name` doit être fourni.
Datastore		Utilisez un attribut avec un préfixe `db.` . Par exemple : `db.statement`.
Service		Cela ne peut pas être fait avec un attribut. Une étendue est classée comme une étendue de service si elle est l'étendue racine ou si son parent provient d'une entité différente. Si une étendue possède plusieurs propriétés, la classification de l'étendue de service est prioritaire dans l'UI.
En cours de réalisation		Cela ne peut pas être fait avec un attribut. Une étendue est classée comme en cours de traitement si elle n'a pas été classée comme étendue de service, étendue datastore ou étendue externe.

Pour en savoir plus sur la manière dont ces propriétés d'étendue sont déterminées et stockées, voir Structure de trace.

Conseils pour ajouter un attribut :

Vous pouvez ajouter n’importe quel attribut à une plage. Par exemple : vous pouvez ajouter un attribut comme customer.id afin de pouvoir rechercher globalement une trace contenant un client spécifique.
Une portée peut appartenir à plusieurs catégories. Par exemple, external est une catégorie plus générale que datastore. Ainsi, si une étendue est classée à la fois comme external et datastore, elle sera indiquée comme une étendue datastore dans l'UI.

Exemples JSON

Voici quelques exemples JSON montrant comment utiliser l’attribut pour définir les propriétés span :

Nouveau format JSON Relic avec plusieurs types d'attributs ajoutés. La signification de l'attribut personnalisé est décrite dans customAttribute.

[
  {
    "common": {
      "attributes": {
        "hostname": "cattle456.example.com",
        "environment": "staging"
      }
    },
    "spans": [
      {
        "id": "1-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "duration.ms": 3.5,
          "error.name": "StackOverflowException",
          "name": "/placeOrder [POST]",
          "customer.id": "datanerd@newrelic.com",
          "description": "This span is the root of the whole trace. It has no parent.id. Custom attributes like 'customer.id' can have any name. Using these kinds of attributes will allow you to do a global search across all traces for desired traces."
        }
      },
      {
        "id": "2-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "duration.ms": 1,
          "parent.id": "1-abcdefg",
          "db.query": "foo selection",
          "db.statement": "SELECT FOO FROM BAR",
          "name": "DB Span",
          "description": "This is a datastore span. The presence of one or more attributes prefixed with db. makes this display as a datastore span in the UI."
        }
      },
      {
        "id": "3-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "parent.id": "1-abcdefg",
          "duration.ms": 1.5,
          "http.method": "POST",
          "name": "HTTP Span",
          "description": "An external (HTTP) span. Spans with one or more attributes prefixed with http. are treated as external spans."
        }
      },
      {
        "id": "4-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "duration.ms": 1.2,
          "error.text": "404 file not found",
          "parent.id": "1-abcdefg",
          "http.method": "GET",
          "http.statusCode": 404,
          "name": "Error Http Span",
          "description": "Spans with error. prefixed attributes are displayed in red text in the UI. Errors can coexist with other span categories."
        }
      },
      {
        "id": "5-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "error.message": "404 file not found",
          "duration.ms": 1.2,
          "parent.id": "1-abcdefg",
          "http.method": "GET",
          "http.statusCode": 404,
          "db.query": "SELECT FOO FROM BAR",
          "name": "Error Http DB Span",
          "description": "Spans can have multiple properties. Relevant attributes are highlighted when you select a span to view its details."
        }
      },
      {
        "id": "6-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "duration.ms": 1.6,
          "parent.id": "1-abcdefg",
          "http.method": "GET",
          "db.query": "SELECT FOO FROM BAR",
          "name": "Http DB Span",
          "description": "External (HTTP) is a more general category than is datastore, so a span with both http.- and db.-prefixed attributes is displayed as a datastore span in the UI."
        }
      },
      {
        "id": "7-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "duration.ms": 2.0,
          "parent.id": "1-abcdefg",
          "description": "Spans with no explicit types that belong to the same entity as its parent and children are considered in-process spans.",
          "name": "In-process span 1"
        }
      },
      {
        "id": "8-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "duration.ms": 1.7,
          "parent.id": "7-abcdefg",
          "name": "In-process span 2",
          "description": "In-process spans can represent a breakdown of work being done within a process."
        }
      },
      {
        "id": "9-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "duration.ms": 1.0,
          "parent.id": "8-abcdefg",
          "name": "In-process span 3",
          "description": "The number and granularity of in-process spans vary depending on instrumentation and frameworks being used."
        }
      },
      {
        "id": "10-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "duration.ms": 2.2,
          "parent.id": "1-abcdefg",
          "name": "In-process span"
        }
      },
      {
        "id": "11-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Service",
          "duration.ms": 2.2,
          "parent.id": "10-abcdefg",
          "name": "External determined by entity change",
          "description": "A span that’s a parent to a span from another entity is displayed as an external span in the UI."
        }
      },
      {
        "id": "12-abcdefg",
        "trace.id": "abc123-xyz789",
        "attributes": {
          "service.name": "Order Notification Service",
          "duration.ms": 1.8,
          "parent.id": "11-abcdefg",
          "name": "Entry span determined by entity change",
          "description": "The attribute 'service.name' is used to detect process boundaries in the UI. For compatibility with data from Lambda monitoring and APM agents, the attribute 'entity.name' can be used to search across all traces."
        }
      }
    ]
  }
]

JSON au format Zipkin avec plusieurs types d'attributs ajoutés. La signification de l'attribut (valeur clé paires) est décrite dans customAttribute.

[
  {
    "traceId": "zipkinSampleTrace",
    "id": "1",
    "kind": "SERVER",
    "name": "Error Span",
    "duration": 35000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "customAttribute": "This span is the root of the whole trace. It has no parent.id"
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "2",
    "parentId": "1",
    "kind": "SERVER",
    "name": "post",
    "duration": 10000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "customAttribute": "This is a datastore span. The presence of one or more attributes prefixed with db. makes this display as a datastore span in the UI."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "2",
    "parentId": "1",
    "kind": "CLIENT",
    "name": "DB Span",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "db.query": "foo selection",
      "db.statement": "SELECT FOO FROM BAR",
      "customAttribute": "This is a datastore span. The presence of one or more attributes prefixed with db. makes this display as a datastore span in the UI."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "3",
    "parentId": "1",
    "kind": "CLIENT",
    "name": "HTTP Span",
    "duration": 15000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "http.method": "POST",
      "customAttribute": "AAn external (HTTP) span. Spans with one or more attributes prefixed with http. are treated as external spans."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "4",
    "parentId": "1",
    "kind": "CLIENT",
    "name": "Error Span",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "error.message": "404 file not found",
      "http.method": "GET",
      "http.statusCode": 404,
      "customAttribute": "Spans with error. prefixed attributes are displayed in red text in the UI. Errors can coexist with other span categories."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "5",
    "parentId": "1",
    "kind": "CLIENT",
    "name": "HTTP Error DB Span",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "error.message": "404 file not found",
      "http.method": "GET",
      "http.statusCode": 404,
      "db.query": "SELECT FOO FROM BAR",
      "customAttribute": "Spans can have multiple properties. Relevant attributes are highlighted when you select a span to view its details."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "6",
    "parentId": "1",
    "kind": "CLIENT",
    "name": "HTTP DB Span",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "http.method": "GET",
      "db.query": "SELECT FOO FROM BAR",
      "customAttribute": "External (HTTP) is a more general category than is datastore, so a span with both http.- and db.-prefixed attributes is displayed as a datastore span in the UI."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "7",
    "parentId": "1",
    "kind": "SERVER",
    "name": "In process span 1",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "customAttribute": "Spans with no explicit types that belong to the same entity as its parent and children are considered in-process spans."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "8",
    "parentId": "7",
    "kind": "SERVER",
    "name": "In process span 2",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "customAttribute": "In-process spans can represent a breakdown of work being done within a process."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "9",
    "parentId": "8",
    "kind": "SERVER",
    "name": "In process span 2",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "customAttribute": "The number and granularity of in-process spans vary depending on instrumentation and frameworks being used."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "10",
    "parentId": "1",
    "kind": "CLIENT",
    "name": "In process remote parent",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "name": "in process remote parent"
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "10",
    "parentId": "1",
    "kind": "CLIENT",
    "name": "In process remote parent",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "sampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "customAttribute": "A span that is a parent to a span from another entity will be displayed as an external span."
    }
  },
  {
    "traceId": "zipkinSampleTrace",
    "id": "11",
    "parentId": "10",
    "kind": "SERVER",
    "name": "Downstream entry span",
    "duration": 12000,
    "localEndpoint": {
      "serviceName": "downstreamSampleApp",
      "ipv4": "127.0.0.1",
      "port": 8080
    },
    "tags": {
      "customAttribute": "The attribute 'service.name' is used to detect process boundaries in the UI. For compatibility with data from Lambda monitoring and APM agents, the attribute 'entity.name' can be used to search across all traces."
    }
  }
]

Cette traduction automatique est fournie pour votre commodité.

API de trace : décorer les étendues avec un attribut

Pourquoi décorer vos travées ?

Comment décorer vos travées avec des attributs

Exemples JSON

Nouveaux exemples d'attributs au format Relic

Exemples d'attributs au format Zipkin

Cette traduction automatique est fournie pour votre commodité.

API de trace : décorer les étendues avec un attribut

Pourquoi décorer vos travées ? .css-21sua1{background:none;border:none;width:0;padding:0;}

Comment décorer vos travées avec des attributs

Exemples JSON

Exemples d'attributs au format Zipkin

Pourquoi décorer vos travées ?