Added url.template to HTTP client attributes

[klauco]

Fixes #899
Semantic conventions should allow working with the concept of routes / path templates on the HTTP client side as well. Such support allows usage of http.route on i.e. HTTP client metrics, when the underlying HTTP Client infrastructure provides a way to define a low-cardinality route/path template alongside the path.

Changes

• http.route attribute definition is modified to allow defining the path template also for outgoing HTTP requests
• http.route is added as an opt-in attribute to the http client attributes

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• CHANGELOG.md updated for non-trivial changes.
• schema-next.yaml updated with changes to existing conventions.

[linux-foundation-easycla]

The committers listed above are authorized under a signed CLA.

• ✅ login: klauco (02ee3c2, 384a230, fecc7ea, f3584ff, 4586315, 8cbb7d2, d5c3a53, 17e7366, 0dd5aab, 36913ad, 21c3d9d, b040abe, 4f9deb9, 549e633, ed69c63, 4c184a8, d7f5183, 148b46e, 03a5e66)
• ✅ login: lmolkova / name: Liudmila Molkova (14f1612, 7ec0443, 13cf2ea, 540237d, 2e18b03, e76a144)
• ✅ login: trask / name: Trask Stalnaker (ac532b6)

[trask]

hi @klauco! can you sign the CLA?

[trask]

linking related discussion: #899

[trask]

/easycla

[trask]

linking to related: #899

[joaopgrassi]

The metrics are already marked as stable, it's Opt-In but I wonder if this classifies as a breaking change?

[trask]

The metrics are already marked as stable, it's Opt-In but I wonder if this classifies as a breaking change?

my understanding is that adding Opt-In attributes is not a breaking change

[joaopgrassi]

Hi @klauco !

We changed how the CHANGELOG.md is managed. Please take a look at main/CONTRIBUTING.md#adding-a-changelog-entry to see what needs to be done. Sorry for the disruption.

[trask]

another option to consider would be introducing something like url.template on the client side

this could help avoid a potential confusion that http.route captured on a CLIENT span should correlate with http.route captured on a SERVER span

[klauco]

another option to consider would be introducing something like url.template on the client side

this could help avoid a potential confusion that http.route captured on a CLIENT span should correlate with http.route captured on a SERVER span

I like that proposal, but I have two questions to it:

1. assuming Add translation of nginx HTTP code 499? opentelemetry-specification#676 would be merged, do we need to distinguish path from template? The url.path could be theoretically used as well, as long as the low-cardinality is ensured either via scrubbing or providing it's template counterpart.
2. the url.template does not specify which part of the URL you wanted to include. is it path template, or full URL template? If it should be path template, then it points me back to question 1 - whether we need a separate dimension in url to handle low-cardinality.

[jsuereth]

So one of the PRIMARY reasons we want http.route on server side metrics is because it helps us tie the knot of "Issue detected in metric" to "What line of code may be responsible". The instrumentation of http.route is meant to give you, as close as possible, the expansion of http handling logic, so you can see latency/error rates of each split out. This is much better than splitting by URL where the cardinality may blow up many metric systems and it's harder to see trends in code behavior.

What's the use case for HTTP Client http.route? Today I can see existing client metrics identifying a slow/broken dependency. Is there also a chance for "tying to code logic" in the same way there?

[klauco]

The primary use case is to enable higher granularity of the metric for outgoing HTTP traffic. Typically you measure health/availability/success rate/latency of the dependencies per endpoint called. But due to high cardinality, you typically use a template representing the path portion of the dependency call's URL.

Example of a made-up dependency which handles user-related data:

GET /users/{userId}
POST /users
GET /something/else/for/{userId}

You would want to know latency and success rate for each endpoint separately, not for a whole depenndency (which is a current state of semantic conventions, which do not include higher granularity path/template dimension, which would be required to have low cardinality.

[trask]

here's a prototype of how we would like to use this in Java instrumentation: open-telemetry/opentelemetry-java-instrumentation#10506

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[trask]

another option to consider would be introducing something like url.template on the client side
this could help avoid a potential confusion that http.route captured on a CLIENT span should correlate with http.route captured on a SERVER span

I like that proposal, but I have two questions to it:

1. assuming Allow url.path sanitization #676 would be merged, do we need to distinguish path from template? The url.path could be theoretically used as well, as long as the low-cardinality is ensured either via scrubbing or providing it's template counterpart.
2. the url.template does not specify which part of the URL you wanted to include. is it path template, or full URL template? If it should be path template, then it points me back to question 1 - whether we need a separate dimension in url to handle low-cardinality.

if we overload url.path in this way, would we be able to capture both the full path and the low-cardinality template (e.g. in open-telemetry/opentelemetry-java-instrumentation#10506)?

[trask]

Thanks @klauco!

[sjparkinson]

What's the use case for HTTP Client http.route?

I didn't see it in the discussion, but a use case we have for a bit of route information in HTTP client metrics is to provide more useful insights on requests to centralised API gateways running under one host (e.g. api.example.com) that has several underlying APIs/services published in it (e.g. api.example.com/users is the users service and api.example.com/content is the content service).

Pleased to see url.template cover this use case. Now to figure out how to capture the information!