Transformation to Zipkin

specification/exporter-zipkin.md

@@ -0,0 +1,112 @@
+# OpenTelemetry to Zipkin Transformation
+
+This document defines the transformation between OpenTelemetry and Zipkin Spans.
+Zipkin's v2 API is defined in the
+[zipkin.proto](https://github.com/openzipkin/zipkin-api/blob/master/zipkin.proto)
+
+## Summary
+
+The following table summarizes the major transformations between OpenTelemetry
+and Zipkin.
+
+| OpenTelemetry            | Zipkin           | Notes                                                        |
+| ------------------------ | ---------------- | ------------------------------------------------------------ |
+| Span.TraceID             | Span.TraceID     |                                                              |
+| Span.ParentID            | Span.ParentID    |                                                              |
+| Span.SpanID              | Span.ID          |                                                              |
+| Span.TraceState          | TODO             | TODO                                                         |
+| Span.Name                | Span.Name        |                                                              |
+| Span.Kind                | Span.Kind        | See [SpanKind](#span-kind) for values mapping                |
+| Span.StartTime           | Span.Timestamp   | See [Unit of time](#unit-of-time)                            |
+| Span.EndTime             | Span.Duration    | Duration is calculated based on StartTime and EndTime. See also [Unit of time](#unit-of-time) |
+| Span.Attributes          | Span.Tags        | See [Attributes](#attributes) for data types for the mapping. |
+| Span.Events              | Span.Annotations | See [Events](#events) for the mapping format.                |
+| Span.Links               | TODO             | TODO                                                         |
+| Span.Status              | Add to Span.Tags | See [Status](#status) for tag names to use.                  |
+| Span.LocalChildSpanCount | TODO             | TODO                                                         |
+
+TODO: This is work in progress document and it is currently doesn't specify
+mapping for these fields:
+
+OpenTelemetry fields:
+
+- Resource attributes
+- Tracestate
+- Links
+- LocalChildSpanCount
+- dropped attributes count
+- dropped events count
+- dropped links count
+
+Zipkin fields:
+
+- Service name
+- Local_endpoint
+- Remote_endpoint
+- debug
+- Shared
+
+## Mappings
+
+This section discusses the details of the transformations between OpenTelemetry
+and Zipkin.
+
+### SpanKind
+
+The following table lists all the `SpanKind` mappings between OpenTelemetry and
+Zipkin.
+
+| OpenTelemetry | Zipkin | Note |
+| ------------- | ------ | ---- |
+| `SpanKind.CLIENT`|`SpanKind.CLIENT`||
+| `SpanKind.SERVER`|`SpanKind.SERVER`||
+| `SpanKind.CONSUMER`|`SpanKind.CONSUMER`||
+| `SpanKind.PRODUCER`|`SpanKind.PRODUCER` ||
+|`SpanKind.INTERNAL`|`null` |must be omitted (set to `null`)|
+
+### Attribute
+
+OpenTelemetry Span `Attribute`(s) MUST be reported as `tags` to Zipkin.
+Primitive types MUST be converted to string using en-US culture settings.
+Boolean values must use lower case strings `"true"` and `"false"`.
+
+Array values MUST be serialized to string like a JSON list.
+
+TODO: add examples
+
+### Status
+
+Span `Status` MUST be reported as a key-value pair in `tags` to Zipkin.
+
+The following table defines the OpenTelemetry `Status` to Zipkin `tags` mapping.
+
+| Status|Tag Key| Tag Value |
+|--|--|--|
+|Code | `ot.status_code` | Name of the code, for example: `OK` |
+|Message *(optional)* | `ot.status_description` | `{message}` |
+
+The `ot.status_code` tag value MUST follow the [Standard GRPC Code
+Names](https://github.com/grpc/grpc/blob/master/doc/statuscodes.md).
+
+### Events
+
+OpenTelemetry `Event` has an optional `Attribute`(s) which is not supported by
+Zipkin. Events MUST be converted to the Annotations with the names which will
+include attribute values like this:
+
+```
+"my-event-name": { "key1" : "value1", "key2": "value2" }
+```
+
+### Unit of Time
+
+Zipkin times like `timestamp`, `duration` and `annotation.timestamp` MUST be
+reported in microseconds with decimal accuracy.
+
+## Request Payload
+
+For performance considerations, Zipkin fields that can be absent SHOULD be
+omitted from the payload when they are empty in the OpenTelemetry `Span`.
+
+For example, an OpenTelemetry `Span` without any `Event` should not have an
+`annotations` field in the Zipkin payload.