Define zipkin compatibility

[pavolloffay]

I would like to more formally define Zipkin compatibility. What is currently supported and what will be supported in the future.

Currently we accept zipkin spans in thrift format over HTTP. Default endpoint is http://localhost:14268/api/traces?format=zipkin.thrift.

Default Zipkin endpoint is http://localhost:9411/api/v1/spans with Content-Type thrift or json and optional gzip encoding.

The difference makes it hard to send data from zipkin instrumentations to jaeger server. In some cases it requires changes in zipkin tracers because of the hardcoded path (/api/v1/spans) and often it's not possible to configure sender with a custom query param (format=zipkin.thrift).

We should consider supporting the same endpoint on the jaeger side to make migrations easier.

[codefromthecrypt]

FWIW, zipkin defines its api compatibility here http://zipkin.io/zipkin-api/#/ You could say that you are compatible with the POST api unless you are trying to support readback as well. There is one known limitation which is that the current OpenApi spec doesn't handle anyOf, which means we cannot accurately define a schema for the binaryAnnotation type openzipkin/zipkin-api#27 This will be remedied when the OpenApi v3 tooling catches up https://github.com/OAI/OpenAPI-Specification/blob/OpenAPI.next/IMPLEMENTATIONS.md There's also a simpler json reporting format you may want to pay attention to (which will be landing in the coming weeks) openzipkin/zipkin#1644

[pavolloffay]

@yurishkuro do you see any blockers why not to expose port 9411 and use the same URL mapping as zipkin uses? Currently it's hard/inconvenient to switch from zipkin to jaeger. In most cases it requires changes in tracers/reporters.

[yurishkuro]

Yes, I think that's the right thing to do. It could be an optional setting. And code-wise it should be fairly straightforward, just a shim handler that will delegate to the existing logic (I'm only referring to writing spans, don't know why it would be worth the time supporting read API).

What about posting spans in zipkin's JSON format, was there any ask / use cases for that?

[codefromthecrypt]

Some users are probably unaware what format is being used, so sooner or later I would expect json to be requested. It could make sense to anticipate demand for this one (since json is widely used and not supporting it would be a bad experience for those trying jaeger)

[pavolloffay]

I can have a look at this. You can assign it to me.

[mabn]

What about posting spans in zipkin's JSON format, was there any ask / use cases for that?

https://github.com/uber/jaeger/issues/225 - "Allow Istio to report Zipkin span data to Jaeger"