Skip to content

feat(spanner): Add OpenTelemetry Cloud Trace exporter sample - #14871

Open
iennae wants to merge 4 commits into
feat/spanner-disable-builtin-metricsfrom
feat/spanner-opentelemetry-traces-cloudtrace
Open

iennae wants to merge 4 commits into
feat/spanner-disable-builtin-metricsfrom
feat/spanner-opentelemetry-traces-cloudtrace

Conversation

@iennae

@iennae iennae commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Description

Demonstrates exporting client-side and end-to-end Cloud Spanner traces directly to Google Cloud Trace via CloudTraceSpanExporter and W3C TraceContextTextMapPropagator.

Adds spanner_opentelemetry_traces_cloudtrace_usage.

Note: Stacked on #14857 (feat/spanner-disable-builtin-metrics) so this PR shows only this sample's diff. It will merge into main after #14857.

Checklist

Testing

  • I have tested this change on a live environment and verified it works as intended. Unit and live integration tests pass on Python 3.13.

Compliance & Style


Post-Approval Actions

  • Please merge this PR for me once it is approved

Exporting client-side and server-side Spanner traces directly to Google Cloud Trace lacked a standalone tested sample in python-docs-samples.
@iennae
iennae requested review from a team as code owners November 17, 2026 23:48
@product-auto-label product-auto-label Bot added api: spanner Issues related to the Spanner API. samples Issues that are directly related to samples. labels Nov 17, 2026
@snippet-bot

snippet-bot Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Here is the summary of changes.

You are about to add 1 region tag.

This comment is generated by snippet-bot.
If you find problems with this result, please file an issue at:
https://github.com/googleapis/repo-automation-bots/issues.
To update this comment, add snippet-bot:force-run label or use the checkbox below:

  • Refresh this comment

@gemini-code-assist gemini-code-assist Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a new module and tests for exporting Google Cloud Spanner OpenTelemetry traces to Cloud Trace. The feedback suggests improving flexibility by making the project_id parameter optional in both the configuration function and the CLI, allowing it to be automatically resolved from the environment or Application Default Credentials. To support this, the reviewer recommends using client.project in error messages to print the resolved project ID, and updating the mock tests to set the project attribute on the mocked Spanner client.

Comment on lines +28 to +30
def configure_cloud_trace_tracing(
project_id: str, instance_id: str, database_id: str
) -> None:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Update the configure_cloud_trace_tracing function signature to accept project_id as 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.

Suggested change
def configure_cloud_trace_tracing(
project_id: str, instance_id: str, database_id: str
) -> None:
def configure_cloud_trace_tracing(
project_id: str | None, instance_id: str, database_id: str
) -> None:

Copy link
Copy Markdown
Contributor Author

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: str explicit 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) from stdout and stderr output so project metadata is not echoed in logs.

Comment on lines +60 to +64
print(
f"error: database '{database_id}' on instance '{instance_id}' "
f"in project '{project_id}' was not found: {err.message}",
file=sys.stderr,
)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Use client.project instead of project_id in the error message. When project_id is not provided (i.e., None), the Spanner client automatically resolves the project ID from the environment. Using client.project ensures the actual resolved project ID is printed.

Suggested change
print(
f"error: database '{database_id}' on instance '{instance_id}' "
f"in project '{project_id}' was not found: {err.message}",
file=sys.stderr,
)
print(
f"error: database '{database_id}' on instance '{instance_id}' "
f"in project '{client.project}' was not found: {err.message}",
file=sys.stderr,
)

Copy link
Copy Markdown
Contributor Author

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: str explicit 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) from stdout and stderr output so project metadata is not echoed in logs.

Comment on lines +65 to +70
except exceptions.GoogleAPICallError as err:
print(
f"error: Cloud Trace query failed on database '{database_id}' "
f"in instance '{instance_id}' for project '{project_id}': {err.message}",
file=sys.stderr,
)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Use client.project instead of project_id in the error message to ensure the actual resolved project ID is printed when project_id is inferred from the environment.

Suggested change
except exceptions.GoogleAPICallError as err:
print(
f"error: Cloud Trace query failed on database '{database_id}' "
f"in instance '{instance_id}' for project '{project_id}': {err.message}",
file=sys.stderr,
)
except exceptions.GoogleAPICallError as err:
print(
f"error: Cloud Trace query failed on database '{database_id}' "
f"in instance '{instance_id}' for project '{client.project}': {err.message}",
file=sys.stderr,
)

Copy link
Copy Markdown
Contributor Author

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: str explicit 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) from stdout and stderr output so project metadata is not echoed in logs.

Comment on lines +91 to +95
"--project-id",
default=os.environ.get("GOOGLE_CLOUD_PROJECT", "example-project-id"),
help="Google Cloud project ID (default: $GOOGLE_CLOUD_PROJECT)",
)
parser.add_argument(

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Make the --project-id argument optional by defaulting to os.environ.get("GOOGLE_CLOUD_PROJECT") (which is None if not set) instead of a hardcoded string like "example-project-id". This allows the project ID to be automatically inferred from Application Default Credentials (ADC) or the environment when not provided.

    parser.add_argument(
        "--project-id",
        default=os.environ.get("GOOGLE_CLOUD_PROJECT"),
        help="Google Cloud project ID (default: $GOOGLE_CLOUD_PROJECT)",
    )
References
  1. When using argparse for a command-line script, the --project_id argument can be optional, as the project can be inferred from Application Default Credentials (ADC) if not provided.

Copy link
Copy Markdown
Contributor Author

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: str explicit 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) from stdout and stderr output so project metadata is not echoed in logs.

Comment on lines +43 to +47
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Set the project attribute on the mocked client to PROJECT_ID to ensure the mock behaves realistically and matches the actual client behavior.

Suggested change
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
mock_exporter_class.return_value.export.return_value = SpanExportResult.SUCCESS
mock_client_class.return_value.project = PROJECT_ID
database = (
mock_client_class.return_value.instance.return_value.database.return_value
)
database.name = DATABASE_NAME

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Because we intentionally omit project identifiers (project_id / client.project) from stdout and stderr output, the sample does not read client.project, so this mock attribute isn't needed.

Comment on lines +86 to +89
mock_exporter_class.return_value.export.return_value = SpanExportResult.SUCCESS
database = (
mock_client_class.return_value.instance.return_value.database.return_value
)

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Set the project attribute on the mocked client to PROJECT_ID to ensure the mock behaves realistically and matches the actual client behavior.

Suggested change
mock_exporter_class.return_value.export.return_value = SpanExportResult.SUCCESS
database = (
mock_client_class.return_value.instance.return_value.database.return_value
)
mock_exporter_class.return_value.export.return_value = SpanExportResult.SUCCESS
mock_client_class.return_value.project = PROJECT_ID
database = (
mock_client_class.return_value.instance.return_value.database.return_value
)

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Because we intentionally omit project identifiers (project_id / client.project) from stdout and stderr output, the sample does not read client.project, so this mock attribute isn't needed.

Comment on lines +110 to +114
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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Set the project attribute on the mocked client to PROJECT_ID to ensure the mock behaves realistically and matches the actual client behavior.

Suggested change
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
mock_exporter_class.return_value.export.return_value = SpanExportResult.SUCCESS
mock_client_class.return_value.project = PROJECT_ID
database = (
mock_client_class.return_value.instance.return_value.database.return_value
)
database.name = DATABASE_NAME

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Because we intentionally omit project identifiers (project_id / client.project) from stdout and stderr output, the sample does not read client.project, so this mock attribute isn't needed.

Avoids printing project identifiers in stdout resource lines or stderr error diagnostics.
Prints short resource identifiers instead of full project-prefixed resource paths and omits project_id from diagnostic messages.
…tions

Prints only runtime query results and verifies real spanner.Client options via wraps in live integration tests.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

api: spanner Issues related to the Spanner API. samples Issues that are directly related to samples.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants