Demystifying Instrumenter API route() method

[robododge]

Just wanted to share, if you are an instrumentation author, or aspire to be one, the route() method may confuse you. I think I finally understand the purpose of the route() method in the instrumenter API for HttpAttributesExtractor

When implemented on a server side, it makes sense to me, client-side it does not make sense to me (yet). See the Jaeger viewer image below, I used the Armeria server 1.9.x and set up a simple service in armeria listening to the path /greet{:name}. The route was picked up from the internal logical paths that the armeria responded to the request with.

[iNikem]

It is actually explained in semantic conventions: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/http.md#http-server-semantic-conventions

Do you find that explanation confusing? How can we make it more clear?

[robododge]

@iNikem Thanks for pointing that out and thanks for your interest in helping avoid confusion. Yes I see it is explained there in the base opentelementry spec. When I worked on the jetty-client instrumentation, I didn't know to look in the semantics, I missed that some how. I guess the reason I made this post is because I was having trouble relating in a tangible way concept of route during creation of new instrumentation. I can see how it works now in a tangible way.

For me, route() stands out because it is not a part of the normal HTTP/Servlet nomenclature, a comment would be nice on the abstract method itself to link directly to the semantic conventions page for route.

[anuraaga]

I think we'll definitely want to separate out client and server side for HTTP since there is quite a bit of difference in what applies to each. #3700 is one issue to decide on for doing so.

[robododge]

Thanks, I agree. And to add.. If client libraries are supporting a technique where you configure a single request with path variables like /greet/{pathVar1}/{pathVar2} , I could see the route() semantic usecase for HTTP clients. But, I don't know of support for that type of higher-order, declarative path variable in HTTP client libraries at the moment. It may exist.