Clarification of HTTP_HEADERS format requirements

[bhs]

... continued from https://github.com/opentracing/opentracing.io/issues/113

cc: @yurishkuro @bensigelan @cwe1ss

[pauldraper]

I'm just not sure why we have to throw up our hands in the HTTP case.

One easy approach to key-value encoding is UTF-8 percent-encoding, like

X-Opentracing: key1=value1
X-Opentracing: %6b%65%79%32=%76%61%6c%75%65%32
X-Opentracing: key3=value3,key4=value4

Requiring certain keys or values just for HTTP propagation is entirely unnecessary and brings up lots of questions.

[yurishkuro]

There are three ways to deal with HTTP transport in the current API.

Option 1 - let the Carrier to the encoding. This is generally a non-starter, because the carriers are often provided by the frameworks being instrumented for tracing. For example, if I instrument Dropwizard and someone else instruments Apache HTTP, then we are almost certain to use different carriers, and if each of us needs to do the encoding, there's a high probability it will not be compatible across different instrumentations, even if the same tracer is used.

Option 2 - provide utils in opentracing to do the encoding (we used to have that). There are two problems with that. The first problem is procedural, we need everyone to agree on what that encoding is. So far we tried to stay away from having OT dictate any sorts of encodings. The second problem is that the encoding has to work with essentially unknown data, meaning it would have to be the most restrictive. That just introduces unnecessary overhead, both procedural (OT has to maintain the encoding in different languages) and performance (many tracers use key/values that are safe for http, so why penalize them through the most restrictive encoding).

Option 3 - what we have currently, which is to leave the problem to the tracer implementation. This moves the compatibility concerns onto the tracer implementors, allows them freedom of encoding, and not the least makes the end user code the most straightforward (options 1 and 2 require more work from the end user).

[yurishkuro]

@bensigelman ^^^ might be a good candidate for the FAQ, wdyt?

[bhs]

@yurishkuro definitely, yeah... this is the N'th time it's come up :)

[pauldraper]

Option 3 seems appropriate.

But the documentation goes further and talks vaguely about what key and values can and can't be used. It's a partial regression in the desire to not specify transport format; we've just constrained the Tracers to respect a particular transport format (and an ambiguously defined one at that).

    // Unlike TextMap, the HTTPHeaders format requires that the keys and values
    // be valid as HTTP headers as-is (i.e., character casing may be unstable
    // and special characters are disallowed in keys, values should be
    // URL-escaped, etc).

My opinion is that the documentation for the HTTPHeaders format shouldn't have such disclaimers.

[pauldraper]

Actually, I've reconsidered. It's still a sticky point, but it seems reasonable.

[yurishkuro]

It's a partial regression in the desire to not specify transport format; we've just constrained the Tracers to respect a particular transport format (and an ambiguously defined one at that).

Yes, it's a concession to HTTP guarantees being a highly popular regression to common sense :-)