feat(bigquery): added error attributes to span tracing (#12115)

This adds capture of error attributes to BigQuery span tracing. 

[Example with
GoogleJsonResponseException](https://screenshot.googleplex.com/54scDAtJYwhijST.png)
[Example with
exception](https://screenshot.googleplex.com/7X787su6MSP8v3T.png)
see note
[here](https://github.com/GoogleCloudPlatform/opentelemetry-operations-java/blob/85b304b4916f2775a6f06b582fc866b24b8cea44/exporters/trace/README.md?plain=1#L125)
about exception.type mapping to error/name

Author: ldetmer

java-bigquery/google-cloud-bigquery/pom.xml

@@ -133,6 +133,10 @@
       <groupId>io.opentelemetry</groupId>
       <artifactId>opentelemetry-context</artifactId>
     </dependency>
+    <dependency>
+      <groupId>com.google.api-client</groupId>
+      <artifactId>google-api-client</artifactId>
+    </dependency>
 
     <dependency>
       <groupId>com.google.api</groupId>

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/spi/v2/HttpBigQueryRpc.java

@@ -21,6 +21,7 @@
 import static java.net.HttpURLConnection.HTTP_OK;
 import static java.net.HttpURLConnection.HTTP_UNAUTHORIZED;
 
+import com.google.api.client.googleapis.json.GoogleJsonResponseException;
 import com.google.api.client.http.ByteArrayContent;
 import com.google.api.client.http.GenericUrl;
 import com.google.api.client.http.HttpRequest;
@@ -65,6 +66,7 @@
 import com.google.cloud.Tuple;
 import com.google.cloud.bigquery.BigQueryException;
 import com.google.cloud.bigquery.BigQueryOptions;
+import com.google.cloud.bigquery.telemetry.BigQueryTelemetryTracer;
 import com.google.cloud.bigquery.telemetry.HttpTracingRequestInitializer;
 import com.google.cloud.http.HttpTransportOptions;
 import com.google.common.base.Function;
@@ -1769,6 +1771,16 @@ private <T> T executeWithSpan(Span span, SpanOperation<T> operation) throws IOEx
     }
     try (Scope scope = span.makeCurrent()) {
       return operation.execute(span);
+    } catch (Exception e) {
+      if (isHttpTracingEnabled()) {
+        if (e instanceof GoogleJsonResponseException) {
+          BigQueryTelemetryTracer.addServerErrorResponseToSpan(
+              ((GoogleJsonResponseException) e), span);
+        } else {
+          BigQueryTelemetryTracer.addExceptionToSpan(e, span);
+        }
+      }
+      throw e;
     } finally {
       span.end();
     }

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/telemetry/BigQueryTelemetryTracer.java

@@ -16,10 +16,13 @@
 
 package com.google.cloud.bigquery.telemetry;
 
+import com.google.api.client.googleapis.json.GoogleJsonError;
+import com.google.api.client.googleapis.json.GoogleJsonResponseException;
 import com.google.api.core.BetaApi;
 import com.google.api.core.InternalApi;
 import io.opentelemetry.api.common.AttributeKey;
 import io.opentelemetry.api.trace.Span;
+import io.opentelemetry.api.trace.StatusCode;
 
 /** BigQuery Telemetry class that stores generic telemetry attributes and values */
 @BetaApi
@@ -70,4 +73,55 @@ public static void addCommonAttributeToSpan(Span span) {
         .setAttribute(GCP_CLIENT_LANGUAGE, BQ_GCP_CLIENT_LANGUAGE);
     // TODO: add version
   }
+
+  /**
+   * Adds the following error attributes to trace span: STATUS_MESSAGE: the name of the exception +
+   * message if available EXCEPTION_TYPE: full name of exception ex: java.net.UnknownHostException
+   * ERROR_TYPE: mapped string based on {@link ErrorTypeUtil#getClientErrorType(Exception)}
+   */
+  public static void addExceptionToSpan(Exception e, Span span) {
+    span.recordException(e);
+    String message = e.getMessage();
+    String simpleName = e.getClass().getSimpleName();
+    String statusMessage = simpleName + (message != null ? ": " + message : "");
+    span.setAttribute(BigQueryTelemetryTracer.EXCEPTION_TYPE, e.getClass().getName());
+    span.setAttribute(
+        BigQueryTelemetryTracer.ERROR_TYPE, ErrorTypeUtil.getClientErrorType(e).toString());
+    span.setAttribute(BigQueryTelemetryTracer.STATUS_MESSAGE, statusMessage);
+    span.setStatus(StatusCode.ERROR, statusMessage);
+  }
+
+  /**
+   * Adds the following error attributes to trace span from GoogleJsonResponseException:
+   * STATUS_MESSAGE: user readable error message ERROR_TYPE: reason if available otherwise the
+   * status code
+   */
+  public static void addServerErrorResponseToSpan(
+      GoogleJsonResponseException errorResponse, Span span) {
+    span.setStatus(StatusCode.ERROR);
+    // set default values in case details aren't available below
+    if (errorResponse.getDetails() != null) {
+      span.setAttribute(
+          BigQueryTelemetryTracer.STATUS_MESSAGE, errorResponse.getDetails().getMessage());
+    } else {
+      span.setAttribute(BigQueryTelemetryTracer.STATUS_MESSAGE, errorResponse.getStatusMessage());
+    }
+    span.setAttribute(
+        BigQueryTelemetryTracer.ERROR_TYPE, Integer.toString(errorResponse.getStatusCode()));
+
+    // reads error details from GoogleJsonResponseException and override any available error details
+    if (errorResponse.getDetails() != null
+        && errorResponse.getDetails().getErrors() != null
+        && !errorResponse.getDetails().getErrors().isEmpty()) {
+      GoogleJsonError.ErrorInfo errorInfo = errorResponse.getDetails().getErrors().get(0);
+      String message = errorInfo.getMessage();
+      if (message != null) {
+        span.setAttribute(BigQueryTelemetryTracer.STATUS_MESSAGE, message);
+      }
+      String reason = errorInfo.getReason();
+      if (reason != null) {
+        span.setAttribute(BigQueryTelemetryTracer.ERROR_TYPE, reason);
+      }
+    }
+  }
 }

java-bigquery/google-cloud-bigquery/src/main/java/com/google/cloud/bigquery/telemetry/ErrorTypeUtil.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright 2026 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package com.google.cloud.bigquery.telemetry;
+
+import com.google.api.core.BetaApi;
+
+/**
+ * Utility class for identifying exception types for telemetry tracking. TODO: this class should get
+ * replaced with gax version when ready work tracked in
+ * https://github.com/googleapis/google-cloud-java/issues/12105
+ */
+@BetaApi
+class ErrorTypeUtil {
+
+  enum ErrorType {
+    CLIENT_TIMEOUT,
+    CLIENT_CONNECTION_ERROR,
+    CLIENT_REQUEST_ERROR,
+    CLIENT_RESPONSE_DECODE_ERROR,
+    CLIENT_UNKNOWN_ERROR;
+
+    @Override
+    public String toString() {
+      return name();
+    }
+  }
+
+  static boolean isClientTimeout(Exception e) {
+    return e instanceof java.net.SocketTimeoutException;
+  }
+
+  static boolean isClientConnectionError(Exception e) {
+    return e instanceof java.net.ConnectException
+        || e instanceof java.net.UnknownHostException
+        || e instanceof javax.net.ssl.SSLHandshakeException
+        || e instanceof java.nio.channels.UnresolvedAddressException;
+  }
+
+  static boolean isClientResponseDecodeError(Exception e) {
+    return e instanceof com.google.gson.JsonParseException;
+  }
+
+  static boolean isClientRequestError(Exception e) {
+    return e instanceof java.lang.IllegalArgumentException;
+  }
+
+  static ErrorType getClientErrorType(Exception e) {
+    if (isClientTimeout(e)) {
+      return ErrorType.CLIENT_TIMEOUT;
+    } else if (isClientConnectionError(e)) {
+      return ErrorType.CLIENT_CONNECTION_ERROR;
+    } else if (isClientResponseDecodeError(e)) {
+      return ErrorType.CLIENT_RESPONSE_DECODE_ERROR;
+    } else if (isClientRequestError(e)) {
+      return ErrorType.CLIENT_REQUEST_ERROR;
+    } else {
+      return ErrorType.CLIENT_UNKNOWN_ERROR;
+    }
+  }
+}