はじめに〜なぜこの記事が必要か
分散トレーシングシステムによってSpanフォーマットが違う。Spanに付与できるメタデータ/タグにはシステムによって予約済み/Well-Knownなキーがあって、そのタグに設定された値はそれぞれWeb UI上で表示するときに特別扱いされたりするらしい。
zipkin-go-opentracingやdd-zipkin-proxyのように、クライアントライブラリ、プロキシエージェントのような形で、様々な分散トレーシングシステムのSpanフォーマットを透過的に変換してくれるようなソフトウェアは存在する。
しかし、ソフトウェアによって、予約済みのSpanタグキーを適切に読み替えてくれたりくれなかったりします。もし、そのようなソフトウェアを利用して期待通りの結果にならなかったときは、このページの内容を思い出してみると解決の糸口がつかめるかもしれません。
OpenTracing
Data Conventions · Opentracing
specification/semantic_conventions.md at master · opentracing/specification
- component
- db.instance
- db.statement
- db.type
- db.user
- error
- ...
Datadog APM
Trace APIの仕様書には書いてない。Pythonライブラリに定義されている定数が参考になる。
dd-trace-py/ddtrace/ext at master · DataDog/dd-trace-py
-
DB関係
- db.name (OTのdb.typeに相当?)
- db.user
-
SQL関係
- sql.db (OTのdb.instanceに相当?)
- sql.query (OTのstatementに相当?)
- sql.rows (OTには相当するものがない)
-
ネットワーク一般
- out.host
- out.port
- net.out.bytes
- ...
Zipkin
タグというのはなくて、binary annotationのkeyがタグ名、valueが値に相当する。
Data Model · OpenZipkin
example zipkin trace with 3 spans
- jdbc.query (otのdb.statement、ddのsql.queryに相当)
- とか...
参考までに、Envoyが送るbinary annotation keyは以下。
- guid:x-request-id
- http.url
- http.method
- downstream_cluster
- user_agent
- http.protocol
- guid:x-client-trace-id
- request_size
- upstream_cluster
- http.status_code
- response_size
- response_flags
- error
annotation typeはなぜかすべてBOOL(STRINGではなく)
https://github.com/envoyproxy/envoy/blob/e0c6eaa3945a501e7a74bb41a92f00daf8fb4581/source/common/tracing/http_tracer_impl.cc#L123-L158
https://github.com/envoyproxy/envoy/blob/cbff0f7fc56c53e3aac383081021856c8dbcb732/source/common/tracing/zipkin/zipkin_core_constants.h
https://github.com/envoyproxy/envoy/blob/04d2f9b129075705d1c0416a5b120d56b442f210/source/common/tracing/zipkin/zipkin_core_types.cc#L257
dd-zipkin-proxy
Zipkinスパン(b3-propagation, thrift)をDatadog APM Spanに変換してくれるやつだが、データモデルの違いを吸収するために一部拡張がある。
具体的には、以下のようなkeyのzipkin binary annotationがあると、そのannotationをDatadog APM Spanのフィールドに読み替えてくれる。
dd-zipkin-proxy/main.go at master · flachnetz/dd-zipkin-proxy
- dd.resource -> dd spanのresource
- dd.name -> dd spanのname
その他、zipkinのbinary annotationはそのままkey=valueのタグとしてdd spanのmetadataにいれてくれる。
なお、zipkinｂのjdbc.queryをddのsql.queryに変換・・してくれたりはしないので、Zipkinでjdbc.queryを表示するときに特別扱いされてたようなケースでも、DatadogのWeb UIでは特別扱いしてくれないかもしれない。
その点については、dd-zipkin-proxyを改良して、dd側にwell-knownなタグキーがあればzipkin->ddのキーに読み替えるようにするとよさそうではある。