feat(internal/trace): add OpenTelemetry support

[quartzmo]

Add GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING env var for opt-in OpenTelemetry tracing.

refs: #2205

OpenCensus sunsetting and OpenTelemetry support

The OpenCensus project is obsolete and was archived on July 31st, 2023. This means that any security vulnerabilities that are found will not be patched. We recommend that you begin migrating to OpenCensus tracing to OpenTelemetry, the successor project.

One year after the Google Cloud Go client libraries release the experimental, opt-in OpenTelemetry tracing support in this PR (mid-Q4 2023), the prior experimental OpenCensus tracing will be removed.

Using the OpenTelemetry-Go - OpenCensus Bridge, you can immediately begin exporting your traces with OpenTelemetry, even while dependencies remain instrumented with OpenCensus. If you do not use the bridge, you will need to migrate your entire application and all of its instrumented dependencies at once. For simple applications, this may be possible, but we expect the bridge to be helpful if multiple libraries with instrumentation are used.

Please refer to the following resources:

• Sunsetting OpenCensus
• OpenTelemetry-Go - OpenCensus Bridge
• What is OpenTelemetry?
• Cloud Trace - Go and OpenTelemetry
• On GCE, use Ops Agent and OpenTelemetry

Testing support for library maintainers

PTAL at internal/testutil/trace_otel.go and the update to trace_test.go. I wasn't able to match the existing testutil api perfectly, so testing support for OpenTelemetry will not be completely transparent. However, the new testutil functions are very close:

OpenCensus

te := testutil.NewTestExporter()
defer te.Unregister()
...
spans := te.Spans

OpenTelemetry

ctx := context.Background()
te := testutil.NewOpenTelemetryTestExporter()
defer te.Unregister(ctx)
...
spans := te.Spans()

[codyoss]

Should this just be an APIError now? Everything should return those now, right? Same with the above toStatus stuff

[quartzmo]

I'll look into this, thanks!

[quartzmo]

I think this logic in bigtable shows a situation where the err closing the span could be an unwrapped Status or even a io.EOF:

https://github.com/googleapis/google-cloud-go/blob/bigtable/v1.20.0/bigtable/bigtable.go#L182-L215

[codyoss]

sure, but I just meant L117 here. Other cases can still be left.

[quartzmo]

ah sorry, i misunderstood

[quartzmo]

After trying this, I think it's best to just extract the googleapi.Error (if found), since it exposes the HTTP error message. With APIError, that message is only exposed by Error() but it gets some added prefix:

 trace_test.go:131: got googleapi: Error 400: INVALID ARGUMENT, want INVALID ARGUMENT

[codyoss]

I think that would be fine to call Error and all HTTP APIError *should have wrap a googleapis.Error. But I am fine with this for now. We can always make that change later.

[bhshkh]

Sorry, marked as draft by mistake

[quartzmo]

I tested this manually using only an OpenTelemetry exporter and the cloud.google.com/go/storage client, and observed the storage span in Cloud Trace console when GOOGLE_API_GO_EXPERIMENTAL_TELEMETRY_PLATFORM_TRACING=opentelemetry.

/cc @cjcotter