Add TracingConnection decorator for creating Open Telemetry spans

[scotthart]

The component services for bigquerycontrol and bigquery_storage provide their own *TracingConnection classes, but those only create spans for their individual RPCs that we may call and thus there's no overarching parent span for methods that call a combination of RPCs. Adding a TracingConnection decorator for the bigquery_unified::Connection would provide a place to create such a parent span.

There may be some complications if both the bigquery_unified::TracingConnection and the component TracingConnection create spans, so it needs some investigation. If it turns out only one of the decorators can create the span, then we may need a more creative solution.

[dbolduc]

So in general, this should be fine. I think there is one thing that will be tricky.

Straight forward APIs

For unary APIs (that return some StatusOr<Message>), we can do what generated code would do:

https://github.com/googleapis/google-cloud-cpp/blob/6055c7025d1c98625fbcbbe7a7eb4a74577a1c9b/generator/integration_tests/golden/v1/internal/golden_kitchen_sink_tracing_connection.cc#L38-L40

For async APIs (that return some future<T>) we need to add a little extra sauce (internal::OTelScope):

https://github.com/googleapis/google-cloud-cpp/blob/6055c7025d1c98625fbcbbe7a7eb4a74577a1c9b/generator/integration_tests/golden/v1/internal/golden_thing_admin_tracing_connection.cc#L47-L50

For stream ranges, we have a tracing wrapper + we need the internal::OTelScope:

https://github.com/googleapis/google-cloud-cpp/blob/6055c7025d1c98625fbcbbe7a7eb4a74577a1c9b/generator/integration_tests/golden/v1/internal/golden_kitchen_sink_tracing_connection.cc#L59-L63

ReadArrow

Now the complicated case will be ReadArrow.

google-cloud-cpp-bigquery/google/cloud/bigquery_unified/connection.h

Lines 90 to 93 in 602972b

	virtual StatusOr<ReadArrowResponse> ReadArrow(
	google::cloud::bigquery::storage::v1::CreateReadSessionRequest const&
	read_session,
	Options opts);

This has a complicated return type. The return type can "do it's own work", i.e. iterate over the streams.

It will be hard to represent the work in a waterfall. I think the workflow is to break these streams across multiple threads. Ideally we would have some way to link the streams back to the parent span (set at the unified tracing connection level).

It will take thought, and remember that tracing can be best effort. The individual streams will still be traced... they just might not get linked back to the parent call.

Unit Testing

We can get a long way by copying the unit tests for our golden tracing decorator:

https://github.com/googleapis/google-cloud-cpp/blob/main/generator/integration_tests/tests/golden_kitchen_sink_tracing_connection_test.cc

[cuiy0006]

The tracing decorator is added to all APIs except ReadArrow, next step is to investigate what we can do to ReadArrow.