X-Request-ID Header Replacement / Conflict

[travisgosselin]

FROM @greylurk

We’ve been discussing Atlas and HTTP headers in the Parcel Service team today, and we kind of were looking at the conflicts between the DeFacto standard of X-Request-ID headers and https://datatracker.ietf.org/doc/html/rfc7239 . Has there been much thinking about this on the Atlas/Guardrails level?

Is there a replacement for the X-Request-ID? It sounds like currently Atlas isn’t blocking the X-Foo headers, but might in the future. Is there a planned replacement for the Request ID in that world?

[greylurk]

Thanks,

A few background pieces of information:
https://istio.io/latest/docs/tasks/observability/distributed-tracing/overview/

Related, but different:
https://docs.aws.amazon.com/xray/latest/devguide/xray-concepts.html#xray-concepts-tracingheader

[nicholas-s-perkins]

Reading the SIP35 a bit, I wonder if there's some conflation between "custom" headers and "non-standard" headers.

I don't think it makes sense for Atlas to actively think about X- headers in the foreseeable future. X- was a pretty common header convention and a lot of things will likely continue to use it for a long time.

It could be interesting to propose our own tracing header, like SPS-Breadcrumb-Id or something, that maybe people could rally around if we're considering having a common way to add tracing across apps. Though, some of the utility in having a breadcrumb header is limited without some cohesion of what it means.

In parcel-service we added X-Request-Id as an experiment to hook Workflow tracing to it. WOS apps use Apache Camel and Camel has a concept of tracing through a shared Breadcrumb-ID that their apps can add as a requestId to parcel-service and it shows up in our logs.

[travisgosselin]

Thanks for spawning some clarifying questions on this topic. I think Nick's sentiment was the intended direction in SIP35. More specifically, the desire is not to get away from using all X-* headers in our platform. Rather the intention is that we should be creating non-infrastructure specific, SPS custom headers that would be documented for usage in REST API specifications. As a point of clarity, there are many aspects of HTTP that are intentionally not covered by the standards and it is difficult boundary to determine at times. Moving forward, I do not forsee a circumstance where headers such as X-Request-ID, X-Forwarded-Host, X-Forwarded-* are disallowed in Atlas. The Forwarded headers specifically are necessary as part of the platform and infrastructure (https://docs.platform.spscommerce.com/runtime/lifecycle/#ingress-gateways) (but for example ARE NOT REST related considerations or contracts to the consumers of the API - they materialize as headers added upon request). There is some existing text about clarification of what this list is for: CLARIFICATION: The following list of headers IS NOT meant as a complete list of headers that you as an API Consumer may send and/or receive. Rather it is intended as general guidelines of headers API Implementations are specifically meant to support for RESTful purposes.. I'll add an additional note to the Custom Headers section too.

Some of the discussions happening in help-atlas channel as of late have focused on custom headers required by the API to be passed by originating consumers/clients. These are the intended consumers of patterns relating to custom headers defined here: https://atlassian.spscommerce.com/wiki/pages/viewpage.action?pageId=331998946#APIRequest&Response-CustomHeaders . Atlas does not actually block these headers for normal operations, any valid header format would work... except when dealing with CORS. As a result future designs next PI will allow for customization of CORS allowed headers and origins, but intentionally block customization to methods as a platform opinion stemming from API standards that you should never invent a custom HTTP verb (no deviations between HTTP infrastructure, proxies with REST standards in this case). More design details here if interested: https://atlassian.spscommerce.com/wiki/display/GE/Atlas+-+CORS+Platform+Defaults . There is perhaps a future where CORS blocks allowed headers from the client. But that is out of scope for upcoming work, and is an opinion yet to be ratified in a meaningful way yet.

X-Request-ID is actually returned by Atlas platform on all requests today, and there is no desire I'm aware of to abandon it. In fact, we are seeing a cross-over with request ID, at least in error scenarios, where that should materialize as part of the API Standard error model as "requestId" for purposes of convenience and logging: https://atlassian.spscommerce.com/wiki/display/SIP/API+-+Errors . Tracing is alive and well with some recent work from last PI making use of X-B3 headers and also parent traces all using X-Request-ID. There is much to do to mature in our tracing capability, storage, but found using OpenTelemetry best practices in Atlas pretty easy to setup and get running! I think it would be reasonably helpful to engage tracing for most apps in Atlas today for delivery teams (up to them to enable forwarding the headers, etc.). I am exploring how this would be added in the .NET Shared Library (possibility for other libraries I hope, though I know its initialized much differently in Java for example). More info on Atlas Tracing: https://docs.platform.spscommerce.com/runtime/distributed-tracing/ (find some demos in the open session in Feb as well).