feat(csharp/src/Drivers): instrument tracing exporters for BigQuery/Apache drivers

csharp/src/Drivers/Apache/Apache.Arrow.Adbc.Drivers.Apache.csproj

@@ -14,6 +14,7 @@
 
   <ItemGroup>
     <ProjectReference Include="..\..\Apache.Arrow.Adbc\Apache.Arrow.Adbc.csproj" />
+    <ProjectReference Include="..\..\Telemetry\Traces\Exporters\Apache.Arrow.Adbc.Telemetry.Traces.Exporters.csproj" />
   </ItemGroup>
 
 </Project>

csharp/src/Drivers/Apache/Hive2/HiveServer2Connection.cs

@@ -27,10 +27,12 @@
 using System.Threading.Tasks;
 using Apache.Arrow.Adbc.Drivers.Apache.Thrift;
 using Apache.Arrow.Adbc.Extensions;
+using Apache.Arrow.Adbc.Telemetry.Traces.Exporters;
 using Apache.Arrow.Adbc.Tracing;
 using Apache.Arrow.Ipc;
 using Apache.Arrow.Types;
 using Apache.Hive.Service.Rpc.Thrift;
+using OpenTelemetry.Trace;
 using Thrift.Protocol;
 using Thrift.Transport;
 
@@ -49,6 +51,9 @@ internal abstract class HiveServer2Connection : TracingConnection
         private readonly Lazy<string> _vendorVersion;
         private readonly Lazy<string> _vendorName;
         private bool _isDisposed;
+        private static readonly object s_tracerProviderLock = new object();
+        private static TracerProvider? s_tracerProvider;
+        private static bool s_isFileExporterEnabled = false;
 
         readonly AdbcInfoCode[] infoSupportedCodes = [
             AdbcInfoCode.DriverName,
@@ -278,6 +283,8 @@ internal HiveServer2Connection(IReadOnlyDictionary<string, string> properties)
         {
             Properties = properties;
 
+            TryInitTracerProvider();
+
             // Note: "LazyThreadSafetyMode.PublicationOnly" is thread-safe initialization where
             // the first successful thread sets the value. If an exception is thrown, initialization
             // will retry until it successfully returns a value without an exception.
@@ -294,6 +301,48 @@ internal HiveServer2Connection(IReadOnlyDictionary<string, string> properties)
             }
         }
 
+        private void TryInitTracerProvider()
+        {
+            // Avoid locking if the tracer provider is already set.
+            if (s_tracerProvider != null)
+            {
+                return;
+            }
+            // Avoid locking if the exporter option would not activate.
+            Properties.TryGetValue(ExportersOptions.Exporter, out string? exporterOption);
+            ExportersBuilder exportersBuilder = ExportersBuilder.Build(this.ActivitySourceName, addDefaultExporters: true).Build();
+            if (!exportersBuilder.WouldActivate(exporterOption))
+            {
+                return;
+            }
+
+            // Will likely activate the exporter, so we need to lock to ensure thread safety.
+            lock (s_tracerProviderLock)
+            {
+                // Due to race conditions, we need to check again if the tracer provider is already set.
+                if (s_tracerProvider != null)
+                {
+                    return;
+                }
+
+                // Activates the exporter specified in the connection property (if exists) or environment variable (if is set).
+                if (exportersBuilder.TryActivate(exporterOption, out string? exporterName, out TracerProvider? tracerProvider, ExportersOptions.Environment.Exporter) && tracerProvider != null)
+                {
+                    s_tracerProvider = tracerProvider;
+                    s_isFileExporterEnabled = ExportersOptions.Exporters.AdbcFile.Equals(exporterName);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Conditional used to determines if it is safe to trace
+        /// </summary>
+        /// <remarks>
+        /// It is safe to write to some output types (ie, files) but not others (ie, a shared resource).
+        /// </remarks>
+        /// <returns></returns>
+        internal static bool IsSafeToTrace => s_isFileExporterEnabled;
+
         internal TCLIService.IAsync Client
         {
             get { return _client ?? throw new InvalidOperationException("connection not open"); }
@@ -733,6 +782,7 @@ protected override void Dispose(bool disposing)
             {
                 DisposeClient();
                 _isDisposed = true;
+                s_tracerProvider?.ForceFlush();
             }
             base.Dispose(disposing);
         }
@@ -1540,7 +1590,7 @@ public override IArrowArrayStream GetInfo(IReadOnlyList<AdbcInfoCode> codes)
                             nullCount++;
                             break;
                     }
-                    ActivityExtensions.AddTag(activity, tagKey, tagValue);
+                    Tracing.ActivityExtensions.AddTag(activity, tagKey, tagValue);
                 }
 
                 StructType entryType = new StructType(

csharp/src/Drivers/BigQuery/Apache.Arrow.Adbc.Drivers.BigQuery.csproj

@@ -13,6 +13,7 @@
   </ItemGroup>
   <ItemGroup>
     <ProjectReference Include="..\..\Apache.Arrow.Adbc\Apache.Arrow.Adbc.csproj" />
+    <ProjectReference Include="..\..\Telemetry\Traces\Exporters\Apache.Arrow.Adbc.Telemetry.Traces.Exporters.csproj" />
   </ItemGroup>
   <ItemGroup>
     <Content Include="readme.md">

csharp/src/Drivers/BigQuery/BigQueryConnection.cs

@@ -25,13 +25,15 @@
 using System.Text.RegularExpressions;
 using System.Threading.Tasks;
 using Apache.Arrow.Adbc.Extensions;
+using Apache.Arrow.Adbc.Telemetry.Traces.Exporters;
 using Apache.Arrow.Adbc.Tracing;
 using Apache.Arrow.Ipc;
 using Apache.Arrow.Types;
 using Google.Api.Gax;
 using Google.Apis.Auth.OAuth2;
 using Google.Apis.Bigquery.v2.Data;
 using Google.Cloud.BigQuery.V2;
+using OpenTelemetry.Trace;
 
 namespace Apache.Arrow.Adbc.Drivers.BigQuery
 {
@@ -45,6 +47,9 @@ public class BigQueryConnection : TracingConnection, ITokenProtectedResource
         bool includePublicProjectIds = false;
         const string infoDriverName = "ADBC BigQuery Driver";
         const string infoVendorName = "BigQuery";
+        private static readonly object s_tracerProviderLock = new();
+        private static TracerProvider? s_tracerProvider;
+        private static bool s_isFileExporterEnabled;
 
         private readonly string infoDriverArrowVersion = BigQueryUtils.GetAssemblyVersion(typeof(IArrowArray));
 
@@ -66,6 +71,8 @@ public BigQueryConnection(IReadOnlyDictionary<string, string> properties) : base
                 this.properties = properties.ToDictionary(k => k.Key, v => v.Value);
             }
 
+            TryInitTracerProvider();
+
             // add the default value for now and set to true until C# has a BigDecimal
             this.properties[BigQueryParameters.LargeDecimalsAsString] = BigQueryConstants.TreatLargeDecimalAsString;
             this.httpClient = new HttpClient();
@@ -85,6 +92,48 @@ public BigQueryConnection(IReadOnlyDictionary<string, string> properties) : base
             }
         }
 
+        private void TryInitTracerProvider()
+        {
+            // Avoid locking if the tracer provider is already set.
+            if (s_tracerProvider != null)
+            {
+                return;
+            }
+            // Avoid locking if the exporter option would not activate.
+            this.properties.TryGetValue(ExportersOptions.Exporter, out string? exporterOption);
+            ExportersBuilder exportersBuilder = ExportersBuilder.Build(this.ActivitySourceName, addDefaultExporters: true).Build();
+            if (!exportersBuilder.WouldActivate(exporterOption))
+            {
+                return;
+            }
+
+            // Will likely activate the exporter, so we need to lock to ensure thread safety.
+            lock (s_tracerProviderLock)
+            {
+                // Due to race conditions, we need to check again if the tracer provider is already set.
+                if (s_tracerProvider != null)
+                {
+                    return;
+                }
+
+                // Activates the exporter specified in the connection property (if exists) or environment variable (if is set).
+                if (exportersBuilder.TryActivate(exporterOption, out string? exporterName, out TracerProvider? tracerProvider, ExportersOptions.Environment.Exporter) && tracerProvider != null)
+                {
+                    s_tracerProvider = tracerProvider;
+                    s_isFileExporterEnabled = ExportersOptions.Exporters.AdbcFile.Equals(exporterName);
+                }
+            }
+        }
+
+        /// <summary>
+        /// Conditional used to determines if it is safe to trace
+        /// </summary>
+        /// <remarks>
+        /// It is safe to write to some output types (ie, files) but not others (ie, a shared resource).
+        /// </remarks>
+        /// <returns></returns>
+        internal static bool IsSafeToTrace => s_isFileExporterEnabled;
+
         /// <summary>
         /// The function to call when updating the token.
         /// </summary>
@@ -470,7 +519,7 @@ internal void UpdateClientToken()
 
             return this.TraceActivity(activity =>
             {
-                activity?.AddConditionalTag(SemanticConventions.Db.Query.Text, sql, BigQueryUtils.IsSafeToTrace());
+                activity?.AddConditionalTag(SemanticConventions.Db.Query.Text, sql, BigQueryConnection.IsSafeToTrace);
 
                 Func<Task<BigQueryResults?>> func = () => Client.ExecuteQueryAsync(sql, parameters ?? Enumerable.Empty<BigQueryParameter>(), queryOptions, resultsOptions);
                 BigQueryResults? result = ExecuteWithRetriesAsync<BigQueryResults?>(func, activity).GetAwaiter().GetResult();
@@ -1273,6 +1322,7 @@ public override void Dispose()
             Client?.Dispose();
             Client = null;
             this.httpClient?.Dispose();
+            s_tracerProvider?.ForceFlush();
         }
 
         private static Regex sanitizedInputRegex = new Regex("^[a-zA-Z0-9_-]+");

csharp/src/Drivers/BigQuery/BigQueryStatement.cs

@@ -91,7 +91,7 @@ private async Task<QueryResult> ExecuteQueryInternalAsync()
             {
                 QueryOptions queryOptions = ValidateOptions(activity);
 
-                activity?.AddConditionalTag(SemanticConventions.Db.Query.Text, SqlQuery, BigQueryUtils.IsSafeToTrace());
+                activity?.AddConditionalTag(SemanticConventions.Db.Query.Text, SqlQuery, BigQueryConnection.IsSafeToTrace);
 
                 BigQueryJob job = await Client.CreateQueryJobAsync(SqlQuery, null, queryOptions);
 
@@ -231,7 +231,7 @@ private async Task<UpdateResult> ExecuteUpdateInternalAsync()
                     activity?.AddBigQueryParameterTag(BigQueryParameters.GetQueryResultsOptionsTimeout, seconds);
                 }
 
-                activity?.AddConditionalTag(SemanticConventions.Db.Query.Text, SqlQuery, BigQueryUtils.IsSafeToTrace());
+                activity?.AddConditionalTag(SemanticConventions.Db.Query.Text, SqlQuery, BigQueryConnection.IsSafeToTrace);
 
                 // Cannot set destination table in jobs with DDL statements, otherwise an error will be prompted
                 Func<Task<BigQueryResults?>> func = () => Client.ExecuteQueryAsync(SqlQuery, null, null, getQueryResultsOptions);
@@ -344,7 +344,7 @@ private IArrowType GetType(TableFieldSchema field, IArrowType type)
         {
             // Ideally we wouldn't need to indirect through a stream, but the necessary APIs in Arrow
             // are internal. (TODO: consider changing Arrow).
-            activity?.AddConditionalBigQueryTag("read_stream", streamName, BigQueryUtils.IsSafeToTrace());
+            activity?.AddConditionalBigQueryTag("read_stream", streamName, BigQueryConnection.IsSafeToTrace);
             BigQueryReadClient.ReadRowsStream readRowsStream = client.ReadRows(new ReadRowsRequest { ReadStream = streamName });
             IAsyncEnumerator<ReadRowsResponse> enumerator = readRowsStream.GetResponseStream().GetAsyncEnumerator();
 

csharp/src/Drivers/BigQuery/BigQueryUtils.cs

@@ -42,18 +42,5 @@ public static bool TokenRequiresUpdate(Exception ex)
         internal static string GetAssemblyName(Type type) => type.Assembly.GetName().Name!;
 
         internal static string GetAssemblyVersion(Type type) => FileVersionInfo.GetVersionInfo(type.Assembly.Location).ProductVersion ?? string.Empty;
-
-        /// <summary>
-        /// Conditional used to determines if it is safe to trace
-        /// </summary>
-        /// <remarks>
-        /// It is safe to write to some output types (ie, files) but not others (ie, a shared resource).
-        /// </remarks>
-        /// <returns></returns>
-        internal static bool IsSafeToTrace()
-        {
-            // TODO: Add logic to determine if a file writer is listening
-            return false;
-        }
     }
 }

csharp/src/Drivers/BigQuery/readme.md

@@ -204,3 +204,36 @@ Some environments may also require:
 - [Running jobs programmatically | BigQuery | Google Cloud](https://cloud.google.com/bigquery/docs/running-jobs)
 - [Create datasets | BigQuery | Google Cloud](https://cloud.google.com/bigquery/docs/datasets#required_permissions)
 - [Use the BigQuery Storage Read API to read table data |  Google Cloud](https://cloud.google.com/bigquery/docs/reference/storage/#permissions)
+
+## Tracing
+
+### Tracing Exporters
+
+To enable tracing messages to be observed, a tracing exporter needs to be activated.
+Use either the environment variable `OTEL_TRACES_EXPORTER` or the parameter `adbc.traces.exporter` to select one of the
+supported exporters. The parameter has precedence over the environment variable.
+
+The following exporters are supported:
+
+| Exporter | Description |
+| --- | --- |
+| `otlp` | Exports traces to an OpenTelemetry Collector or directly to an Open Telemetry Line Protocol (OTLP) endpoint. |
+| `adbcfile` | Exports traces to rotating files in a folder. |
+| `console` | Exports traces to the console output. |
+| `none` | Disables trace exporting. |
+
+Note: _The first connection to activate tracing will enable tracing for
+any later connections that are created in that process._ (This behavior may change in future implementations.)
+
+#### File Exporter (adbcfile)
+
+Rotating trace files are written to a folder. The file names are created with the following pattern:
+`apache.arrow.adbc.drivers.bigquery-<YYYY-MM-DD-HH-mm-ss-fff>-<process-id>.log`.
+
+The folder used depends on the platform.
+
+| Platform | Folder |
+| --- | --- |
+| Windows | `%LOCALAPPDATA%/Apache.Arrow.Adbc/Traces` |
+| macOS   | `$HOME/Library/Application Support/Apache.Arrow.Adbc/Traces` |
+| Linux   | `$HOME/.local/share/Apache.Arrow.Adbc/Traces` |