This is an automated email from the ASF dual-hosted git repository.
lidavidm pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/arrow-adbc.git
The following commit(s) were added to refs/heads/main by this push:
new 7c1af9705 docs: document Flight SQL telemetry and logging (#4500)
7c1af9705 is described below
commit 7c1af970508ef882406f1ea1379d4319176085a2
Author: Artur Rakhmatulin <[email protected]>
AuthorDate: Mon Jul 13 09:23:11 2026 +0100
docs: document Flight SQL telemetry and logging (#4500)
## Summary
Document Flight SQL telemetry and structured logging configuration.
## What changed
- document `adbc.telemetry.traces_exporter`
- document `adbc.telemetry.traces_folder_path`
- document `adbc.telemetry.trace_parent`
- document `OTEL_TRACES_EXPORTER`
- document default `adbcfile` trace output locations
- document `ADBC_DRIVER_FLIGHTSQL_LOG_LEVEL`
## Verification
- rendered locally from the generated docs site
---
docs/source/driver/flight_sql.rst | 87 +++++++++++++++++++++++++++++++++++++++
1 file changed, 87 insertions(+)
diff --git a/docs/source/driver/flight_sql.rst
b/docs/source/driver/flight_sql.rst
index 6c1ba7e9a..75513a6da 100644
--- a/docs/source/driver/flight_sql.rst
+++ b/docs/source/driver/flight_sql.rst
@@ -192,6 +192,93 @@ The options used for creating the Flight RPC client can be
customized.
Python:
:attr:`adbc_driver_flightsql.DatabaseOptions.WITH_COOKIE_MIDDLEWARE`
+OpenTelemetry Tracing
+---------------------
+
+The Go-based Flight SQL driver can emit OpenTelemetry traces for
+connection and statement activity.
+
+Tracing can be configured with database options or with environment
+variables.
+
+Database options
+~~~~~~~~~~~~~~~~
+
+``adbc.telemetry.traces_exporter``
+ Selects the traces exporter to use when the driver initializes its
+ tracer provider.
+
+ Supported values:
+
+ - ``none``: disable driver-managed trace exporting
+ - ``otlp``: export traces via OpenTelemetry OTLP exporters
+ - ``console``: write traces to standard output
+ - ``adbcfile``: write traces to rotated ``.jsonl`` files
+
+ When this option is set, it takes precedence over the
+ ``OTEL_TRACES_EXPORTER`` environment variable. If neither is set,
+ the driver falls back to the process-global OpenTelemetry tracer
+ provider.
+
+``adbc.telemetry.traces_folder_path``
+ Overrides the output folder used by the ``adbcfile`` exporter.
+ This option is ignored for other exporters.
+
+ If unset, the ``adbcfile`` exporter writes traces under the user's
+ configuration directory in:
+
+ - Windows: ``%APPDATA%\.adbc\traces``
+ - macOS: ``~/Library/Application Support/.adbc/traces``
+ - Linux: ``$XDG_CONFIG_HOME/.adbc/traces`` or ``~/.config/.adbc/traces``
+
+ .. note::
+
+ These default paths reflect the current implementation. See
+ `issue #4501 <https://github.com/apache/arrow-adbc/issues/4501>`_
+ for the planned config-path redesign.
+
+``adbc.telemetry.trace_parent``
+ Sets the W3C Trace Context ``traceparent`` value used as the parent
+ for spans started by the driver.
+
+Environment variables
+~~~~~~~~~~~~~~~~~~~~~
+
+``OTEL_TRACES_EXPORTER``
+ Selects the traces exporter when
+ ``adbc.telemetry.traces_exporter`` is not set. Supported values are
+ ``none``, ``otlp``, ``console``, and ``adbcfile``.
+
+ When ``otlp`` is selected, the driver follows the standard
+ OpenTelemetry OTLP environment configuration for endpoints,
+ headers, and related exporter settings. Common variables include:
+
+ - ``OTEL_EXPORTER_OTLP_ENDPOINT``
+ - ``OTEL_EXPORTER_OTLP_TRACES_ENDPOINT``
+ - ``OTEL_EXPORTER_OTLP_HEADERS``
+ - ``OTEL_EXPORTER_OTLP_TRACES_HEADERS``
+ - ``OTEL_EXPORTER_OTLP_PROTOCOL``
+ - ``OTEL_EXPORTER_OTLP_TRACES_PROTOCOL``
+
+ For the complete set of supported OTLP environment variables, see
+ the `OpenTelemetry exporter configuration documentation
+
<https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/>`_.
+
+There is no dedicated environment variable for the ``adbcfile`` output
+folder. Use ``adbc.telemetry.traces_folder_path`` to override the
+default location.
+
+Structured Logging
+------------------
+
+The Go-based Flight SQL driver also supports structured client-side
+logging via:
+
+``ADBC_DRIVER_FLIGHTSQL_LOG_LEVEL``
+ Supported values are ``debug``, ``info``, ``warn``, and ``error``.
+
+The logging setting is independent from trace exporter configuration.
+
Custom Call Headers
-------------------
