feat: instruments finagle's netty-based stack

[dmarkwat]

Instruments the twitter finagle http (netty-based) stack for otel tracing, building on the existing netty-4 instrumentation. This includes the necessary bits in finagle-netty4, finagle-http2, and finagle-base-http modules. finagle-http is the aggregate module and so this segments along those lines.

Covered explicitly:

• server & client http/1.1 tracing
• server & client http/2 tracing (limited -- see doc in code)
• netty-4 HTTP 101 (Switching Protocols) handling

Covered implicitly (by other instrumentations, e.g.), and therefore not explicitly instrumented:

• twitter's Futures (doc) are covered by the existing Java Executor instrumentations, as everything bound for a Future via all the typical twitter/finagle means end up in appropriately-wrapped Callables, Runnables, etc.
• down-stack Netty integration is already thoroughly covered; no attempt was made here to reimplement any of the existing otel bits or yield yet another full-blown framework instrumentation

Not covered:

• finagle's other protocol integrations, such as thrift
• http/2-specific finagle tests: the armeria-based underlying framework seems to handle only http/1.1 and would otherwise have required quite the overhaul; as finagle uses the http2-to-1 netty codec (already assumed by netty's own instrumentation), this seemed like an OK thing to omit at the onset -- to be handled, perhaps, at a later time

A word on netty HTTP 101 support

I'm no HTTP ref spec expert, but based on the documentation for Protocol upgrade mechanism provided by MDN I pieced together the handling of the response code as presented by a netty-based server and experienced by a netty-based client to not end the span when 101 is seen as the existing netty instrumentation would normally do.

Why: simple reason is because status code 101 -- unlike the others, afaict -- represents a response continuation (preamble?) rather than a termination, and the existing netty instrumentation treats all status codes as terminations. IOW, the existing netty instrumentation unsuccessfully handles these 101s, which finagle emits (afaict, correctly), and afterwards -- upon seeing the final response -- tries to set attributes on already-ended Spans, resulting in test failures.

So given the situation, there seemed to me to be two options: a) try to rewrite things to handle this condition a bit more fancily (i.e. statefully), or b) simply emit this as an event. I chose the latter, simply because in the course of creating and consuming 101s, it strikes me as more a preamble -- and this can't be stressed enough -- without any client acknowledgement, or reciprocation with, the server. And while it's indeed bytes sent back from a server to a client, it's more "cumulative metadata" than trace-worthy and so warranted capturing as something -- just not a full span.

Very much curious about any thoughts regarding this, as option (a) to rewrite things seemed far less straightforward.

[dmarkwat]

Looking into netty test failures before considering this ready for review.

[dmarkwat]

Netty errors addressed -- was my bad. Ready for review.

[dmarkwat]

@laurit I made changes according to your suggestions. At this point, to my eye the finagle side looks good, lean, and hopefully more intelligible.

There's still the open netty questions. When you get a chance, can you provide some direction on what you might like to see wrt those? Specifically:

• would you like to see the netty server/client wrappers moved over to netty proper, or simply leave them as is? (per my above question in this comment)
• simply remove the event I'm creating? (your question here) This would tidy up the code and avoid (perhaps needlessly) creating an event which is as of now undocumented.

[laurit]

Could you also update https://github.com/open-telemetry/opentelemetry-java-instrumentation/blob/main/docs/supported-libraries.md

[dmarkwat]

Review feedback applied, doc updated, and rebased. Just need an answer to #10141 (comment) and possibly recommendations on how to proceed.

[dmarkwat]

Thank you for the time and attention 🙏. I've rebased and checked back on all the docs and notes I've left -- happy with where this landed. I'll get over to semantic-conventions with the question about HTTP 101, but otherwise eager to see this finally make it if there's nothing left you want me to address.