このドキュメントでは、 Trace API に送信されるトレースデータに属性を追加し、スパンが UI に特定のプロパティを表示する方法について説明します。
なぜスパンを飾るのか？
Trace API にデータを送信する際、カスタム 属性 をスパンに追加することができます。たとえば、 customer.id や user.id のような属性を追加することで、トレースデータの分析に役立てることができます。
いくつかの期待される属性値は、私たちの分散型トレースUIに、いくつかの特定の トレースプロパティ と詳細を表示させます。例えば、 error. 接頭辞を持つ属性を持つスパンは、UIがそのスパンにエラーを表示します。別の例として、 db. 接頭辞を持つ属性を持つスパンは、UIにおいてデータストア・スパンとして表示され、そのデータストア・クエリがハイライトされます。
スパンを装飾して、UIの特定のプロパティを表示することができます。
- トレースデータの 構造の理解を深める 。
- より簡単にトラブルシューティングができるようになりました。
属性でスパンを装飾する方法
このテーブルでは、Trace API に送信されたスパンを、UI の特定のプロパティで表示させる方法を説明します。プロパティの説明については、 span properties を参照してください。
希望するスパンのプロパティ | UIインジケータ | プロパティの追加方法 |
|---|---|---|
エラー |
|
|
外部 |
|
|
データストア |
|
|
サービス |
| これは、属性ではできません。スパンは、それがルートスパンであるか、またはその親が異なるエンティティのものである場合、サービススパンとして分類されます。スパンに複数のプロパティがある場合、UIではサービススパンの分類が優先されます。 |
インプロセス |
| これは、属性ではできません。スパンは、サービススパン、データストアスパン、または外部スパンとして分類されていない場合、処理中として分類されます。 |
これらのスパンのプロパティがどのように決定され、保存されるかについては、 Trace structure を参照してください。
属性を追加するためのヒント
- スパンには任意の属性を追加できます。例えば、
customer.idのような属性を追加することで、 世界中のトレースを検索 特定の顧客を含むトレースを検索することができます。 - 1つのスパンが複数のカテゴリーに分類されることがあります。例えば、
externalは、datastoreよりも一般的なカテゴリであるため、あるスパンがexternalとdatastoreの両方に分類されている場合、UIではdatastoreスパンとして表示されます。
JSONの例
ここでは、属性を使ってスパンのプロパティを設定する方法を示すJSONの例を紹介します。
New Relic-format 複数の種類の属性が追加されたJSONです。カスタム属性の意味は、 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." } } ] }]Zipkin-format 複数の属性タイプを追加したJSONです。属性（キーと値のペア）の意味は、 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." } }]