Zipkin OTEL 0.1.0

We’re excited to announce the first release of Zipkin Otel, version 0.1.0! This project provides integration between Zipkin and OpenTelemetry by introducing two main components:

1. Brave Encoder for OTLP
   A Brave (client-side) encoder that transforms Zipkin Spans into OTLP Spans. This encoder currently supports only HTTP/protobuf.

2. Zipkin Collector for OTLP
   A collector for the Zipkin server that receives traces in OTLP format over HTTP/protobuf.

Usage

Encoder

Add the dependency:

		<dependency>
			<groupId>io.zipkin.contrib.otel</groupId>
			<artifactId>encoder-brave</artifactId>
			<version>0.1.0</version>
		</dependency>

The following demonstrates using the encoder:

// 'sender' is directed at the OTLP tracing endpoint (e.g., http://localhost:4318/v1/traces)
spanHandler = AsyncZipkinSpanHandler.newBuilder(sender).build(OtlpProtoV1Encoder.create());

Collector

To start the Zipkin OTLP collector, use the following Docker command:

# The endpoint for OTLP/HTTP is http://localhost:9411/v1/traces
docker run --rm -p 9411:9411 -e UI_ENABLED=true ghcr.io/openzipkin-contrib/zipkin-otel:0.1.0

For a complete example, please refer to the sample repository.

Zipkin ↔ OTLP Transformation Details

While this project mostly aligns with the OpenTelemetry to Zipkin Transformation documentation, here are a few additional notes.

Zipkin to OTLP (Brave)

• Mapping to Resource Attributes: Direct mapping from Zipkin Spans to resource attributes is not provided, but resource attributes can be set on the encoder as follows:

  OtlpProtoV1Encoder.newBuilder().resourceAttributes(map).build()

• Zipkin Span Annotations: Zipkin Span annotations are mapped to OpenTelemetry Span Event names. Currently, there’s no support for mapping annotation details to event attributes, but future support is under consideration.

OTLP to Zipkin (Collector)

• Resource Attributes as Span Tags: OpenTelemetry resource attributes are included as Span tags in Zipkin. The zipkin2.collector.otel.http.OtelResourceMapper interface can be implemented to customize the mapping from OTLP resources to Zipkin Spans.
• OpenTelemetry Span Events: Events are mapped to Zipkin annotations. If event attributes are present, the format is:
  "my-event-name": { "key1": "value1", "key2": "value2" }.
  If no event attributes are present, the annotation simply becomes my-event-name (without quotes).
• Remote Endpoint: Only peer.name attribute or network.peer.address attribute are considered as remote endpoint candidates.