Clarify how gorouter handles W3C tracing headers

[jriguera]

Documentation states:

* If the `traceparent` and `tracestate` HTTP headers are present in the request, the Gorouter forwards them unmodified.

But that is not what is happening. Gorouter creates a new SPAN ID and updates the tracestate with the tenant, as it is tested in its integration tests:

https://github.com/cloudfoundry/gorouter/blob/9ee77f4fdebd038c1978ecd5982aa2d3ae88b503/integration/w3c_tracing_test.go#L158

[pspinrad]

Thanks @jriguera - would it be correct and helpful to instead say this?:

If the traceparent and tracestate HTTP headers are present in the request, the Gorouter updates the tracestate value to a new SPAN ID in the HTTP headers before forwarding the request.

And if so (or either way) how is the new SPAN ID value derived?

Thanks again.

[jriguera]

Maybe something like this?

If the traceparent and tracestate HTTP headers are present in the request, the Gorouter generates a new spanid and updates the tracestate with the new value in the parent-id field and adds its tenantid to tracestate header before forwarding the request.

I know we are introducing a new concept parent-id ... but, this is what it does.

The way I understand it, is:

The new spanid is generated by the Gorouter, it is a 8 byte array which represents an operation (in this case would be "reverse-proxy") in the chain of request calls (eg. one microservice calling other in the same PAAS). The Gorouter adds the tenantid to the tracestate (the other W3C tracing header) representing itself processing the request. Then next app/microservice generates another spanid representing its operation in the request chain

In my opinion, is expected that the Gorouter generates a new spanid and adds the tenant to tracestate because it is an actor in the communication, which can fail (eg. the route is gone) and it adds latency to the chain of requests, this information can help to understand the entire chain of request.

The traceid ( 16 byte array) for each request, remains the same, across all calls to different microservices. It is the way to link all the children spans generated by each actor involved in the chain. Gorouter only generates trace

You have more here: https://www.w3.org/TR/trace-context/#mutating-the-traceparent-field