How can I add tags per request?

[jeffthompson1971]

I have this working, but i need to pass in a couple specific tags like username etc so i know who the trace is for. I don't see a way to do that. I am referring to the express implementation. i will have custom fields added to the request object...

was thinking maybe I could do a pull request that looks for a 'tags' object on the request object, and if that's there it adds to the span? if not then nobody breaks and it's backwards compatible?

[codefromthecrypt]

are these tags http headers?

[codefromthecrypt]

or are you looking for a way for us to propagate something beyond the traceId?

[jeffthompson1971]

yes.. this are like username and an organization identifier.. i add them to every trace on client-side with the axios implementation. but some of our node services will not have their corresponding web apps instrumented... but still want to get those tags in the express traces

[jeffthompson1971]

i can fork this and try some stuff out?

[codefromthecrypt]

consider stuffing it in the traceID object because you aren't guaranteed to not have any spans between http in and http out. that's my advice.

in the java side, we have this thing called "extra" which is basically a field inside TraceId to store stuff. it is intentionally opaque list to allow multiple plugins to not clobber eachother. one plugin is called "extra fields" which allows you to propagate something from headers to the other side.

[jeffthompson1971]

hmm.. so i already just use the defaultTags so that the fields are stand-alone and can be queried. if I have stuff in a traceID object how could i query for all spans from user thompjg@business.com for example?
this is what i have.
`const tracer = new Tracer({
sampler: theSampler,
ctxImpl: new CLSContext('zipkin'),
recorder: new BatchRecorder({
logger: new HttpLogger({
endpoint: TRACER_ENDPOINT,
jsonEncoder: jsonEncoder.JSON_V2,
}),
}),
localServiceName: SERVICE_NAME,
defaultTags: { component: 'TracerMiddleware', project: 'aip-core-ui' },
});

export const TracerMiddleware = zipkinMiddleware.expressMiddleware({ tracer });`

[codefromthecrypt]

I maybe guessed wrong on what you need. you are not asking to propagate tags, rather just add request-specific tags (ex parsing). I think this would be a change to httpServerInstrumentation, to add a parsing function which will then sink the tags into the span.

[jcchavezs]

My only concern about passing a function is that passing the arguments to such functions might be per request and not globals. If such information comes from the request (like in headers if you translate the jwt into actual info by a proxy) then I would suggest something like `requestReader` similar to `responseHeader` in #432. Definitively something that should end up in httpInstrumentation.

[jeffthompson1971]

Yes definately what I need are tags that are per-request and NOT global. basically it's simple - we just want to know that user and tenantID (the customer identifier in our system)...

So what I would prefer to do is have some upstream express middlware that sets the name=value pairs i need ONTO the request object (in header?) and then we can have zipkin (where I need help with) look for a known header element and if it's there it adds the tags to the span.
Why not have a header key like 'trace-tags' and that value can be a JSON string like
{user: 'jeffthompson@gmail.com', tenantId: '23423432432432'}

then it's very simple and innocuous change in zipkin-js somewhere that just looks for this header and then just do this right before sending the span:
a) convert the JSON string element in the header 'trace-tags' to a JSON object
b) iterate over the keys and log an annotation on the span for each one

thoughts?

[codefromthecrypt]

I don't think we want to get opinionated on the representation in headers, but I don't think you'd need this layer to do that anyway. If I understand correctly, you aren't needing to propagate anything, just parse the headers into the span. In this case a request-based parser function seems to be the best solution. While this would already be a feature of a future "v2" api as we already do this in later tracing design, it wouldn't be hard to make a tactical one here. Let's just try to get the syntax right. I think the last thing I asked was.. which parts of the request are needed? In this case you are only looking at the headers. If you think about parsing in general, we at least also look at the method, status and path. So, I think that instead of adding a whack-a-mole which only covers headers (then having to break that api later), it is best to actually enclose all the parsing logic, with a function of the request (or response) and also a span object (which accepts tag or name). The fact that the implementation of this object would iterate over tags and add annotations internally is fine because it allows the design to be forwards compatible to a v2 api which doens't use binary annotations anymore anyway. is this too abstract??

[jeffthompson1971]

Thanks for the help Adrian. I'm trying to wrap my head completely around it. I'm kinda new - like for example I'm not even clear what the distinction is between a tag and an annotation ;) .

It is a bit abstract - can you like jot down a little psuedo-code for how this API will be extended etc.? That would help me better understand what you are proposing. are you saying you will add a new parameter that will be a function that does the parsing of the request object that I need - be it header or other bits? can you spec that out a little?

[codefromthecrypt]

@jeffthompson1971 sorry.. yeah we are years overdue getting this api overhauled. One main reason is that annotation jargon is so confusing. In real life people almost never need annotations in the v2 model. tags are for lookup etc https://github.com/openzipkin/zipkin-api/blob/master/zipkin2-api.yaml#L307

In the java library, we expose a parser object people can override, only used to parse name and tags ex. https://github.com/openzipkin/brave/blob/master/instrumentation/http/src/main/java/brave/http/HttpParser.java#L59-L64

you can see we do similar in zipkin-js now, just we don't expose a parsing function