feat: add OpenTelemetry tracing

[olavloite]

Adds OpenTelemetry tracing to the JDBC driver. The OpenTelemetry instance that should be used for tracing should be either be set as the global OpenTelemetry instance, or set in the Properties map that is used to create a JDBC connection. In the latter case, the specific OpenTelemetry instance will only be used for that connection.

[surbhigarg92]

Should we also enableApiTracing in the code snipper

[olavloite]

Added (although we need to wait for googleapis/java-spanner#3166 to be merged before we can use it here)

[surbhigarg92]

We are not registering global OT object here.

nit: I feel we can simplify this example by not repeating the whole code .

We can create OpenTelemetrySdkBuilder object and then show different usage of it.

for eg.

 OpenTelemetrySdkBuilder openTelemetrySdkBuilder =
        OpenTelemetrySdk.builder()
            .setTracerProvider(
                SdkTracerProvider.builder()
                    .setSampler(Sampler.traceIdRatioBased(0.05))
                    .setResource(
                        Resource.builder()
                            .put("service.name", "my-unique-service-name")
                            .build())
                    .addSpanProcessor(BatchSpanProcessor.builder(traceExporter).build())
                    .build());
 // Example Using Global OpenTelemetry
 openTelemetrySdkBuilder.buildAndRegisterGlobal()
// Example Using an OpenTelemetry instance in Properties 
     OpenTelemetry openTelemetry = openTelemetrySdkBuilder.build()

[olavloite]

Thanks for noting. Removed the text regarding registering a global OTEL object.

I also simplified the second example a bit, assuming that readers will understand that they can use the same OpenTelemetry instance as in the example above.

[surbhigarg92]

We also have metrics which is helpful in debugging latency issues. Should that info also be added here https://cloud.google.com/spanner/docs/latency-points

[olavloite]

Added a link to the page. The intention is to also add this guide to the documentation (probably to the same submenu)

[surbhigarg92]

Yes, we currently don't have a very good observability documentation. I am working with documentation team to add documentation for Spanner Traces as well along with metrics. Once we have that we can further expand it to add documentation for JDBC as well

[surbhigarg92]

Here as well. global OT is not used here

[olavloite]

Removed

[surbhigarg92]

This only talks about JDBC traces, but in reality customer would see way more traces coming from spanner library.

[olavloite]

This text 'pretends' that all the traces come from the JDBC driver (although some of the text also mentions the client lib). I think that for a customer it is easier to read/understand if we mainly talk about JDBC here, as most users who use the JDBC driver are not using the client library. The fact that they are layered is not necessarily a known fact for everyone.
The traces that are described here also include the traces from the client library (e.g. everything in point 2 and 3 are actually collected by the client library)

[surbhigarg92]

What I meant is customer would also see CloudSpanner.ReadWriteTransaction as a child span to JDBC.ReadWriteTransaction which is not mentioned here.

But I understand adding too much details here can also be confusing for customers.

[olavloite]

Actually, those are the ones that are described in point 2 below, but the text did not call out what they are named. I added that to the text to make it easier for a reader to make the link.

[surbhigarg92]

We can remove this code from here as we have done in readme-partials file.

[olavloite]

I actually kept the full code here intentionally, as having a full copy-pastable example for each of the use cases makes it easier for a reader to quickly get started if they want to use one or the other.

[surbhigarg92]

What I meant is customer would also see CloudSpanner.ReadWriteTransaction as a child span to JDBC.ReadWriteTransaction which is not mentioned here.

But I understand adding too much details here can also be confusing for customers.

[surbhigarg92]

Yes, we currently don't have a very good observability documentation. I am working with documentation team to add documentation for Spanner Traces as well along with metrics. Once we have that we can further expand it to add documentation for JDBC as well