feat(jdbc): basic OpenTelemetry tracing integration for BigQuery JDBC Statement

[keshavdandeva]

b/491239772
b/491239773

Changes

• New connection properties:

  • EnableOpenTelemetry (Boolean, default: false): This property turns tracing on or off within the JDBC driver. It can be provided as a URL parameter connection property (e.g., jdbc:bigquery://...;EnableOpenTelemetry=true) or via the DataSource API.
  • customOpenTelemetry (Instance): This is not a URL property, but a programmatic configuration available exclusively via the DataSource object. It allows developers to inject their fully initialized OpenTelemetry instance (with their custom Exporters, Context Propagators, etc.), ensuring the driver cleanly hooks into their existing tracing backends.

• Added the core initialization logic for OpenTelemetry. During connection setup, it evaluates whether tracing is enabled and constructs an OpenTelemetry Tracer instance. Then, it passes this newly minted tracer strictly downward into the core BigQueryOptions.Builder via .setOpenTelemetryTracer()

• Intercepted the execution functions (execute, executeQuery, executeLargeUpdate, executeBatch) to spawn child spans wrapping each database call.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request establishes the foundational OpenTelemetry tracing capabilities within the BigQuery JDBC driver. It allows for detailed observability of database interactions by automatically creating spans for JDBC query, update, and batch operations, enriching them with query details, execution times, and error information. This integration is designed to be non-disruptive, providing valuable insights into driver performance and behavior without altering existing workflows.

Highlights

• OpenTelemetry Tracing Integration: Integrated foundational OpenTelemetry tracing into the BigQuery JDBC driver to provide observability for database interactions.
• JDBC Execution Interception: Implemented interception for standard JDBC executions, including queries, updates, and batch operations, to create and manage OpenTelemetry spans.
• Span Enrichment: Enhanced OpenTelemetry spans with details such as query text, execution latencies, and exception tagging for comprehensive performance monitoring.
• Configuration Properties: Introduced new connection properties, EnableOpenTelemetry and OpenTelemetryExporter, allowing users to enable and configure tracing behavior.
• Dependency Management: Updated Maven dependencies to include OpenTelemetry libraries and configured shading exclusions to prevent conflicts with OpenTelemetry API and Context classes.
• Dedicated OpenTelemetry Utility: Added a new utility class, BigQueryJdbcOpenTelemetry, to centralize the initialization and management of OpenTelemetry instances and tracers.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces foundational OpenTelemetry tracing for the BigQuery JDBC driver's statement execution, which is a valuable addition for observability. The implementation correctly handles context propagation for asynchronous operations like pagination and streaming, and follows standard OpenTelemetry patterns for creating spans and recording exceptions. I have provided a couple of suggestions: one is a minor correction for a copyright year, and the other is a recommendation to unify the exception handling logic within the new tracing code for improved consistency and maintainability. Overall, this is a solid contribution.

[keshavdandeva]

/gemini review

[gemini-code-assist]

Code Review

This PR introduces OpenTelemetry tracing for JDBC statements, which is a great feature for observability. The implementation correctly wraps statement execution methods to create spans, and it handles context propagation to asynchronous tasks. My review includes two main suggestions for improvement: refactoring duplicated tracing logic in BigQueryStatement to improve maintainability, and enhancing exception logging in BigQueryJdbcOpenTelemetry to retain stack traces for better diagnostics. Overall, the changes are well-structured and provide a solid foundation for tracing.

[logachev]

open telemetry exporter can't be a string.
We should allow custom exporter with lifecycle managed on the customer side (similar to how SDK is handling it); Additionally, we can enable default exporter (gcp one).

So from data source POV, it can be "enableDefaultTemetryExporter" property + datasource way of accepting external exporter.

[keshavdandeva]

Implemented the change, like SDK does. Removed the GCP exporting logic from this PR as it requires new dependency. Will implement it in separate PR.