feat(csharp/src/Apache.Arrow.Adbc): add OpenTelemetry compatible tracing support

[birschick-bq]

This PR adds OpenTelemetry-compatible tracing support on the CSharp library.

Under the hood it uses Activity and ActivitySource from the net System.Diagnostics.DiagnosticSource package.

Create an instance of the ActivityTrace object.

public class YourDriver : AdbcDriver
{
    public YourDriver(string? activitySourceName = default, string? traceParent = default)
    {
        Trace = new ActivityTrace(activitySourceName, traceParent);
    }
    protected ActivityTrace Trace { get; }
}

By default, the activitySourceName will be created from the driver assembly name.

Then to instrument tracing, use one of the following overrides of

• TraceActivity
• TraceActivityAsync

Example:

 public void Connect(...)
 {
    Trace.TraceActivity((activity) =>
    {
        driver.OpenSession(...);
    });
 }

Each of these overrides starts a new Activity which will be non-null only if there is an active ActivityListener or OpenTelemetry exporter. The Activity is passed to the delegate Func/Action in case it need to add ActivityEvent, ActivityLink or Tags (KeyValuePair). When instrumenting tracing, you should always use the null-conditional operator (?. ) when accessing members on the passed delegate parameter, activity.

Example:

public void GetObjects(...)
{
    TraceActivity((activity) =>
    {
        activity?.AddEvent("db.operation.name.start", [new("db.operation.name", nameof(Client.GetCatalogs))]);
        var result = driver.GetCatalogs(...);
        var eventActivity = activity?.AddEvent("db.operation.name.end",
            [
                new("db.operation.name", nameof(Client.GetCatalogs)),
                new("db.response.status_code", getCatalogsResp.Status.StatusCode.ToString())
            ]);
    });
}

The default behavior is to invoke the delegate and if successful (i.e., no exception thrown), the Activity.SetStatus is set to Ok. If an exception is observed, then the Activity.SetStatus is set to Error and the exception is traced (Activity.AddException) as an event in the current Activity.

Callers can pass a traceparent string to any of the TraceActivity[Async] methods using the optional traceParent parameter. The parameter takes precedence over the property. The traceId from the traceParent parameter or TraceParent property will be adopted as the rootId for all trace Activity on that call or object. If TraceParent is null (initial or set later), then the Activity creates a new rootId for the beginning of the initial Activity in the stack.

Example:

public void Connect(..., string? traceParent = default)
{
    TraceActivity((activity) =>
    {
        activity?.AddEvent("opensession.start");
        var result = driver.OpenSession(...);
        activity?.AddEvent("opensession.end", ["status", result.Status]);
    }, traceParent: traceParent);
}

Identifiers used for events and tags should follow the OpenTelemetry semantic guidance ..
https://opentelemetry.io/docs/specs/semconv/database/database-spans/
https://opentelemetry.io/docs/specs/semconv/database/database-metrics/

[birschick-bq]

This class is explicitly necessary, but helps with testing. It also "could" be useful a serialized version of Activity

[birschick-bq]

Passing reference to Trace object to child object for consistent activity source name and handling of trace parent.

[birschick-bq]

Helps to trace the begin/end of fetching results from the server so the duration can be calculated from the difference.

[birschick-bq]

Allow the caller to set the trace_parent on the connection.