このドキュメントでは、 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のような属性を追加して、特定の顧客を含むトレースをグローバルに検索できるようにすることができます。 - スパンは複数のカテゴリに属することができます。たとえば、
externalはdatastoreよりも一般的なカテゴリであるため、スパンがexternalとdatastoreの両方に分類される場合、UI でデータストア スパンとして示されます。
JSONの例
ここでは、属性を使ってスパンのプロパティを設定する方法を示すJSONの例を紹介します。
複数のタイプの属性が追加されたNew Relic 形式の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 形式の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." } }]