Add instrumentation API and native OpenTelemetry implementation

[AlexanderWert]

Adds an instrumentation API with request & response lifecycle callbacks, and an implementation based on OpenTelemetry that is used by default.

To be able to implement the OpenTelemetry semantic conventions, this PR also adds a pathParameters method to Endpoint that provides access to the values in URL template placeholders.

[swallez]

Thanks! Overall it looks nice.

Rather than the route (i.e. path template), using the API endpoint identifier would make things easier. This identifier comes from the API specification (see e.g. IndexRequest) and is available as endpoint.id().

Benefits:

• a single endpoint can have several routes and different http methods depending on which optional path parameters are set,
• using endpoint id avoids doing some pattern matching on the route for things like document id extraction.
• naming the span with the endpoint id ensures a 1:1 mapping from APIs to span names regardless of the path parameters set.

Note: I suggested this to @estolfo in a recent discussion.

[AlexanderWert]

Thanks! Overall it looks nice.

Rather than the route (i.e. path template), using the API endpoint identifier would make things easier. This identifier comes from the API specification (see e.g. IndexRequest) and is available as endpoint.id().

Benefits:

• a single endpoint can have several routes and different http methods depending on which optional path parameters are set,
• using endpoint id avoids doing some pattern matching on the route for things like document id extraction.
• naming the span with the endpoint id ensures a 1:1 mapping from APIs to span names regardless of the path parameters set.

Note: I suggested this to @estolfo in a recent discussion.

I agree that we could improve some of the internal detection of request types by using the endpoint ID. I'll change that to make it more efficient and reliable.

However, from an APM point of view, we would like to be able to differentiate the different patterns even within a single endpoint. For instance, we'd like to have different span names for requests to /_search vs. /{index}/_search.
Also from a user perspective it seems more natural to show the actual pattern being used instead of abstracting it away through a request name.

Regarding regex matching:

• it's not required in the native instrumentation anyways
• for the auto-instrumentation in the agent (for older client versions) we would still need to do it because we need to extract the index and doc_id as we provide this as explicit attributes.

So my suggestion would be to use the endpoint id for internal optimization of the instrumentation but still exposing the actual pattern as the span names.

WDYT?

\cc @estolfo

[AlexanderWert]

@swallez

As open-telemetry/semantic-conventions#23 has been merged, I updated this PR accordingly and also incorporated your suggestions.
I think it's safe now to finalize this PR.

[swallez]

LGTM