Repository navigation
feat(spanner): Add OpenTelemetry Cloud Trace exporter sample #14871
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: feat/spanner-disable-builtin-metrics
Are you sure you want to change the base?
Changes from all commits
fd0b92b
a1cf30e
7d07c98
15e30cd
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,109 @@ | ||||||||||||||||||||||||||
| # 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. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| # [START spanner_opentelemetry_traces_cloudtrace_usage] | ||||||||||||||||||||||||||
| import sys | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| from google.api_core import exceptions | ||||||||||||||||||||||||||
| from google.cloud import spanner | ||||||||||||||||||||||||||
| from opentelemetry.exporter.cloud_trace import CloudTraceSpanExporter | ||||||||||||||||||||||||||
| from opentelemetry.propagate import set_global_textmap | ||||||||||||||||||||||||||
| from opentelemetry.sdk.trace import TracerProvider | ||||||||||||||||||||||||||
| from opentelemetry.sdk.trace.export import BatchSpanProcessor | ||||||||||||||||||||||||||
| from opentelemetry.sdk.trace.sampling import ALWAYS_ON | ||||||||||||||||||||||||||
| from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| def configure_cloud_trace_tracing( | ||||||||||||||||||||||||||
| project_id: str, instance_id: str, database_id: str | ||||||||||||||||||||||||||
| ) -> None: | ||||||||||||||||||||||||||
| """Exports client-side and end-to-end Spanner traces to Google Cloud Trace. | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| Args: | ||||||||||||||||||||||||||
| project_id: The Google Cloud project ID. | ||||||||||||||||||||||||||
| instance_id: The Spanner instance ID. | ||||||||||||||||||||||||||
| database_id: The Spanner database ID. | ||||||||||||||||||||||||||
| """ | ||||||||||||||||||||||||||
| set_global_textmap(TraceContextTextMapPropagator()) | ||||||||||||||||||||||||||
| tracer_provider = TracerProvider(sampler=ALWAYS_ON) | ||||||||||||||||||||||||||
| trace_exporter = CloudTraceSpanExporter(project_id=project_id) # type: ignore[no-untyped-call] | ||||||||||||||||||||||||||
| tracer_provider.add_span_processor(BatchSpanProcessor(trace_exporter)) | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| observability_options = { | ||||||||||||||||||||||||||
| "tracer_provider": tracer_provider, | ||||||||||||||||||||||||||
| "enable_extended_tracing": True, | ||||||||||||||||||||||||||
| "enable_end_to_end_tracing": True, | ||||||||||||||||||||||||||
| } | ||||||||||||||||||||||||||
| client = spanner.Client( | ||||||||||||||||||||||||||
| project=project_id, | ||||||||||||||||||||||||||
| observability_options=observability_options, | ||||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||||
| database = client.instance(instance_id).database(database_id) | ||||||||||||||||||||||||||
| tracer = tracer_provider.get_tracer("spanner-cloudtrace-sample") | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| try: | ||||||||||||||||||||||||||
| with tracer.start_as_current_span("VerifyCloudTraceRead"): | ||||||||||||||||||||||||||
| with database.snapshot() as snapshot: | ||||||||||||||||||||||||||
| row = list(snapshot.execute_sql("SELECT 1"))[0] | ||||||||||||||||||||||||||
| except exceptions.NotFound as err: | ||||||||||||||||||||||||||
| print( | ||||||||||||||||||||||||||
| f"error: database '{database_id}' on instance '{instance_id}' " | ||||||||||||||||||||||||||
| f"was not found: {err.message}", | ||||||||||||||||||||||||||
| file=sys.stderr, | ||||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||||
|
Comment on lines
+60
to
+64
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use
Suggested change
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks for the suggestion! We are intentionally keeping |
||||||||||||||||||||||||||
| except exceptions.GoogleAPICallError as err: | ||||||||||||||||||||||||||
| print( | ||||||||||||||||||||||||||
| f"error: Cloud Trace query failed on database '{database_id}' " | ||||||||||||||||||||||||||
| f"in instance '{instance_id}': {err.message}", | ||||||||||||||||||||||||||
| file=sys.stderr, | ||||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||||
|
Comment on lines
+65
to
+70
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Use
Suggested change
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks for the suggestion! We are intentionally keeping |
||||||||||||||||||||||||||
| else: | ||||||||||||||||||||||||||
| print(f"Resource ID: {database_id}") | ||||||||||||||||||||||||||
| print(f"Check Result: {row[0]}") | ||||||||||||||||||||||||||
| finally: | ||||||||||||||||||||||||||
| tracer_provider.shutdown() | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| # [END spanner_opentelemetry_traces_cloudtrace_usage] | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| if __name__ == "__main__": | ||||||||||||||||||||||||||
| import argparse | ||||||||||||||||||||||||||
| import os | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| parser = argparse.ArgumentParser( | ||||||||||||||||||||||||||
| description="Export OpenTelemetry Spanner traces directly to Cloud Trace." | ||||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||||
| parser.add_argument( | ||||||||||||||||||||||||||
| "--project-id", | ||||||||||||||||||||||||||
| default=os.environ.get("GOOGLE_CLOUD_PROJECT", "example-project-id"), | ||||||||||||||||||||||||||
| help="Google Cloud project ID (default: $GOOGLE_CLOUD_PROJECT)", | ||||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||||
| parser.add_argument( | ||||||||||||||||||||||||||
|
Comment on lines
+89
to
+93
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Make the parser.add_argument(
"--project-id",
default=os.environ.get("GOOGLE_CLOUD_PROJECT"),
help="Google Cloud project ID (default: $GOOGLE_CLOUD_PROJECT)",
)References
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks for the suggestion! We are intentionally keeping |
||||||||||||||||||||||||||
| "--instance-id", | ||||||||||||||||||||||||||
| default=os.environ.get("SPANNER_INSTANCE_ID", "example-instance"), | ||||||||||||||||||||||||||
| help="Spanner instance ID (default: $SPANNER_INSTANCE_ID)", | ||||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||||
| parser.add_argument( | ||||||||||||||||||||||||||
| "--database-id", | ||||||||||||||||||||||||||
| default=os.environ.get("SPANNER_DATABASE_ID", "example-db"), | ||||||||||||||||||||||||||
| help="Spanner database ID (default: $SPANNER_DATABASE_ID)", | ||||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||||
| args = parser.parse_args() | ||||||||||||||||||||||||||
|
|
||||||||||||||||||||||||||
| configure_cloud_trace_tracing( | ||||||||||||||||||||||||||
| project_id=args.project_id, | ||||||||||||||||||||||||||
| instance_id=args.instance_id, | ||||||||||||||||||||||||||
| database_id=args.database_id, | ||||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||||
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,155 @@ | ||||||||||||||||||||||||
| # 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. | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| import runpy | ||||||||||||||||||||||||
| from unittest import mock | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| from google.api_core import exceptions | ||||||||||||||||||||||||
| from google.cloud import spanner | ||||||||||||||||||||||||
| from opentelemetry.sdk.trace.export import SpanExportResult | ||||||||||||||||||||||||
| import pytest | ||||||||||||||||||||||||
| from spanner_observability import opentelemetry_traces_cloudtrace | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| from . import conftest | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| PROJECT_ID = "example-project-id" | ||||||||||||||||||||||||
| INSTANCE_ID = "example-instance" | ||||||||||||||||||||||||
| DATABASE_ID = "example-db" | ||||||||||||||||||||||||
| DATABASE_NAME = f"projects/{PROJECT_ID}/instances/{INSTANCE_ID}/databases/{DATABASE_ID}" | ||||||||||||||||||||||||
| SPANNER_CLIENT = "google.cloud.spanner.Client" | ||||||||||||||||||||||||
| CT_EXPORTER = ( | ||||||||||||||||||||||||
| "spanner_observability.opentelemetry_traces_cloudtrace.CloudTraceSpanExporter" | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
| CT_EXPORTER_SRC = "opentelemetry.exporter.cloud_trace.CloudTraceSpanExporter" | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| @mock.patch(CT_EXPORTER) | ||||||||||||||||||||||||
| @mock.patch(SPANNER_CLIENT) | ||||||||||||||||||||||||
| def test_configure_cloud_trace_tracing_success( | ||||||||||||||||||||||||
| mock_client_class: mock.MagicMock, | ||||||||||||||||||||||||
| mock_exporter_class: mock.MagicMock, | ||||||||||||||||||||||||
| capsys: pytest.CaptureFixture[str], | ||||||||||||||||||||||||
| ) -> None: | ||||||||||||||||||||||||
| mock_exporter_class.return_value.export.return_value = SpanExportResult.SUCCESS | ||||||||||||||||||||||||
| database = ( | ||||||||||||||||||||||||
| mock_client_class.return_value.instance.return_value.database.return_value | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
| database.name = DATABASE_NAME | ||||||||||||||||||||||||
|
Comment on lines
+44
to
+48
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Set the
Suggested change
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks! Because we intentionally omit project identifiers ( |
||||||||||||||||||||||||
| snapshot = database.snapshot.return_value.__enter__.return_value | ||||||||||||||||||||||||
| snapshot.execute_sql.return_value = [(1,)] | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| opentelemetry_traces_cloudtrace.configure_cloud_trace_tracing( | ||||||||||||||||||||||||
| PROJECT_ID, INSTANCE_ID, DATABASE_ID | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| mock_exporter_class.assert_called_once_with(project_id=PROJECT_ID) | ||||||||||||||||||||||||
| out, err = capsys.readouterr() | ||||||||||||||||||||||||
| assert f"Resource ID: {DATABASE_ID}" in out | ||||||||||||||||||||||||
| assert PROJECT_ID not in out | ||||||||||||||||||||||||
| assert "Check Result: 1" in out | ||||||||||||||||||||||||
| assert err == "" | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| @pytest.mark.parametrize( | ||||||||||||||||||||||||
| "error, expected_prefix", | ||||||||||||||||||||||||
| [ | ||||||||||||||||||||||||
| ( | ||||||||||||||||||||||||
| exceptions.NotFound("db missing"), | ||||||||||||||||||||||||
| "error: database 'example-db' on instance 'example-instance'", | ||||||||||||||||||||||||
| ), | ||||||||||||||||||||||||
| ( | ||||||||||||||||||||||||
| exceptions.PermissionDenied("denied"), | ||||||||||||||||||||||||
| "error: Cloud Trace query failed", | ||||||||||||||||||||||||
| ), | ||||||||||||||||||||||||
| ], | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
| @mock.patch(CT_EXPORTER) | ||||||||||||||||||||||||
| @mock.patch(SPANNER_CLIENT) | ||||||||||||||||||||||||
| def test_configure_cloud_trace_tracing_errors( | ||||||||||||||||||||||||
| mock_client_class: mock.MagicMock, | ||||||||||||||||||||||||
| mock_exporter_class: mock.MagicMock, | ||||||||||||||||||||||||
| capsys: pytest.CaptureFixture[str], | ||||||||||||||||||||||||
| error: Exception, | ||||||||||||||||||||||||
| expected_prefix: str, | ||||||||||||||||||||||||
| ) -> None: | ||||||||||||||||||||||||
| mock_exporter_class.return_value.export.return_value = SpanExportResult.SUCCESS | ||||||||||||||||||||||||
| database = ( | ||||||||||||||||||||||||
| mock_client_class.return_value.instance.return_value.database.return_value | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
|
Comment on lines
+86
to
+89
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Set the
Suggested change
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks! Because we intentionally omit project identifiers ( |
||||||||||||||||||||||||
| snapshot = database.snapshot.return_value.__enter__.return_value | ||||||||||||||||||||||||
| snapshot.execute_sql.side_effect = error | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| opentelemetry_traces_cloudtrace.configure_cloud_trace_tracing( | ||||||||||||||||||||||||
| PROJECT_ID, INSTANCE_ID, DATABASE_ID | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| out, err = capsys.readouterr() | ||||||||||||||||||||||||
| assert out == "" | ||||||||||||||||||||||||
| assert err.startswith(expected_prefix) | ||||||||||||||||||||||||
| assert PROJECT_ID not in err | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| @mock.patch(CT_EXPORTER_SRC) | ||||||||||||||||||||||||
| @mock.patch(SPANNER_CLIENT) | ||||||||||||||||||||||||
| def test_configure_cloud_trace_tracing_cli_entrypoint( | ||||||||||||||||||||||||
| mock_client_class: mock.MagicMock, | ||||||||||||||||||||||||
| mock_exporter_class: mock.MagicMock, | ||||||||||||||||||||||||
| monkeypatch: pytest.MonkeyPatch, | ||||||||||||||||||||||||
| capsys: pytest.CaptureFixture[str], | ||||||||||||||||||||||||
| ) -> None: | ||||||||||||||||||||||||
| mock_exporter_class.return_value.export.return_value = SpanExportResult.SUCCESS | ||||||||||||||||||||||||
| database = ( | ||||||||||||||||||||||||
| mock_client_class.return_value.instance.return_value.database.return_value | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
| database.name = DATABASE_NAME | ||||||||||||||||||||||||
|
Comment on lines
+111
to
+115
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Set the
Suggested change
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks! Because we intentionally omit project identifiers ( |
||||||||||||||||||||||||
| snapshot = database.snapshot.return_value.__enter__.return_value | ||||||||||||||||||||||||
| snapshot.execute_sql.return_value = [(1,)] | ||||||||||||||||||||||||
| monkeypatch.setattr( | ||||||||||||||||||||||||
| "sys.argv", | ||||||||||||||||||||||||
| [ | ||||||||||||||||||||||||
| "opentelemetry_traces_cloudtrace.py", | ||||||||||||||||||||||||
| "--project-id", | ||||||||||||||||||||||||
| PROJECT_ID, | ||||||||||||||||||||||||
| "--instance-id", | ||||||||||||||||||||||||
| INSTANCE_ID, | ||||||||||||||||||||||||
| "--database-id", | ||||||||||||||||||||||||
| DATABASE_ID, | ||||||||||||||||||||||||
| ], | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| runpy.run_module( | ||||||||||||||||||||||||
| "spanner_observability.opentelemetry_traces_cloudtrace", run_name="__main__" | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| assert "Check Result: 1" in capsys.readouterr().out | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| @conftest.live_only | ||||||||||||||||||||||||
| def test_configure_cloud_trace_tracing_live( | ||||||||||||||||||||||||
| capsys: pytest.CaptureFixture[str], | ||||||||||||||||||||||||
| ) -> None: | ||||||||||||||||||||||||
| with mock.patch.object(spanner, "Client", wraps=spanner.Client) as spy_client: | ||||||||||||||||||||||||
| opentelemetry_traces_cloudtrace.configure_cloud_trace_tracing( | ||||||||||||||||||||||||
| conftest.LIVE_PROJECT_ID, | ||||||||||||||||||||||||
| conftest.LIVE_INSTANCE_ID, | ||||||||||||||||||||||||
| conftest.LIVE_DATABASE_ID, | ||||||||||||||||||||||||
| ) | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| obs = spy_client.call_args.kwargs["observability_options"] | ||||||||||||||||||||||||
| assert obs["enable_end_to_end_tracing"] is True | ||||||||||||||||||||||||
| assert obs["enable_extended_tracing"] is True | ||||||||||||||||||||||||
| out, err = capsys.readouterr() | ||||||||||||||||||||||||
| assert err == "" | ||||||||||||||||||||||||
| assert conftest.LIVE_PROJECT_ID not in out | ||||||||||||||||||||||||
| assert "Check Result: 1" in out | ||||||||||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Update the
configure_cloud_trace_tracingfunction signature to acceptproject_idas an optional string (str | None). This allows the project ID to be inferred from the environment or Application Default Credentials (ADC) when not explicitly provided.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thanks for the suggestion! We are intentionally keeping
project_id: strexplicit in the sample signature so callers pass configuration directly rather than relying on implicit ADC resolution, and we intentionally omit project identifiers (project_id/client.project) fromstdoutandstderroutput so project metadata is not echoed in logs.