Skip to content

feat(spanner): Add OpenTelemetry query stats latency metric sample - #14872

Open
iennae wants to merge 4 commits into
feat/spanner-disable-builtin-metricsfrom
feat/spanner-opentelemetry-query-stats-metric
Open

iennae wants to merge 4 commits into
feat/spanner-disable-builtin-metricsfrom
feat/spanner-opentelemetry-query-stats-metric

Conversation

@iennae

@iennae iennae commented Nov 17, 2026

Copy link
Copy Markdown
Contributor

Description

Records server-side SQL execution latency (query_stats['elapsed_time'] via QueryMode.PROFILE) into a spanner/query_stats_elapsed OpenTelemetry histogram.

Adds spanner_opentelemetry_capture_query_stats_metric.

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

Recording server-side SQL execution elapsed_time from profiled queries into an OpenTelemetry histogram lacked a Python counterpart to Go and Java.
@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 script to capture Spanner query execution latency using OpenTelemetry, along with its corresponding unit tests. The review feedback suggests implementing defensive checks when accessing query statistics to prevent potential AttributeErrors, ensuring the project ID is correctly resolved from Application Default Credentials, and updating the argparse configuration to allow the project ID to be optional.

Comment on lines +46 to +71
client = spanner.Client(project=project_id)
database = client.instance(instance_id).database(database_id)
elapsed_ms = 0.0

try:
with database.snapshot() as snapshot:
results = snapshot.execute_sql(
"SELECT SingerId, FirstName FROM Singers LIMIT 5",
query_mode=spanner_v1.ExecuteSqlRequest.QueryMode.PROFILE,
)
rows = list(results)
raw_elapsed = str(results.stats.query_stats.get("elapsed_time", "0 msecs"))
elapsed_ms = float(raw_elapsed.split()[0])
query_latency.record(elapsed_ms, {"database": database_id})
except exceptions.NotFound as err:
print(
f"error: database '{database_id}' on instance '{instance_id}' "
f"in project '{project_id}' was not found: {err.message}",
file=sys.stderr,
)
except exceptions.GoogleAPICallError as err:
print(
f"error: profiled 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

To ensure robust execution and accurate error reporting, we should implement two improvements:

  1. Defensively check if results.stats and results.stats.query_stats are populated before accessing them to avoid a potential AttributeError.
  2. Resolve the actual project ID using client.project so that if the project ID is inferred from Application Default Credentials (ADC), the correct ID is displayed in error messages instead of None.
    client = spanner.Client(project=project_id)
    resolved_project_id = project_id or client.project
    database = client.instance(instance_id).database(database_id)
    elapsed_ms = 0.0

    try:
        with database.snapshot() as snapshot:
            results = snapshot.execute_sql(
                "SELECT SingerId, FirstName FROM Singers LIMIT 5",
                query_mode=spanner_v1.ExecuteSqlRequest.QueryMode.PROFILE,
            )
            rows = list(results)
            stats = results.stats
            if stats and stats.query_stats:
                raw_elapsed = str(stats.query_stats.get("elapsed_time", "0 msecs"))
                elapsed_ms = float(raw_elapsed.split()[0])
                query_latency.record(elapsed_ms, {"database": database_id})
    except exceptions.NotFound as err:
        print(
            f"error: database '{database_id}' on instance '{instance_id}' "
            f"in project '{resolved_project_id}' was not found: {err.message}",
            file=sys.stderr,
        )
    except exceptions.GoogleAPICallError as err:
        print(
            f"error: profiled query failed on database '{database_id}' "
            f"in instance '{instance_id}' for project '{resolved_project_id}': {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! results.stats is already guarded (results.stats.query_stats if results.stats else {}), 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
parser.add_argument(
"--project-id",
default=os.environ.get("GOOGLE_CLOUD_PROJECT", "example-project-id"),
help="Google Cloud project ID (default: $GOOGLE_CLOUD_PROJECT)",
)

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

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. We should default to os.environ.get("GOOGLE_CLOUD_PROJECT") (which evaluates to None if unset) instead of a hardcoded fallback like "example-project-id", allowing spanner.Client to automatically perform ADC project resolution.

Suggested change
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(
"--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.

Avoids printing project identifiers in stdout or stderr and guards against unset query_stats metadata.
Prints short resource identifiers instead of full project-prefixed resource paths and omits project_id from diagnostic messages.
Prints only runtime resource and query results instead of hardcoded string literals.
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