feat(core): add request hook to enrich T4 network spans with GCP resource attributes (E)

[chalmerlowe]

Problem

Low-level gRPC transport spans generated by opentelemetry-instrumentation-grpc capture standard RPC metadata but lack Google Cloud semantic context. Without request- and response-level enrichment, spans cannot identify configured endpoint attributes (server.address, server.port, url.domain), resend count, or the Cloud Observability success status (rpc.response.status_code = "OK").

Solution

This PR enriches wire-level gRPC client spans in google-api-core by attaching lightweight request and response hooks to both synchronous and asynchronous OpenTelemetry gRPC interceptors:

1. Request Hook (_make_grpc_client_request_hook):

   • Sets rpc.system.name: "grpc" per OpenTelemetry semantic conventions.
   • Updates the span name (strips slash /, if present)
   • Updates the rpc.method

2. Response Hook (_grpc_client_response_hook):

   • Detects unsuccessful RPC completions on async calls and short circuits to avoid overwriting them. Sync calls do not return these values at all.
   • Records rpc.response.status_code = "OK" on successful sync or asycn RPC completions.

3. Transport Integration:

   • Registers both hooks in get_otel_interceptor (sync) and get_otel_async_interceptor (async) within google.api_core._observability.

4. Extracts Endpoint Attributes:

   • Extracts server.address, server.port (omitted for standard 443/80 ports), and url.domain from client_options.

Notes for Reviewers

• Hooks safely short-circuit when the active span is not recording, avoiding overhead when tracing is disabled or unsampled.
• Does not perform error translation (error names and gcp.errors.* attributes are handled at the client method span level). Those are covered in a previous PR #18274

[gemini-code-assist]

Code Review

This pull request introduces OpenTelemetry request hooks to extract and inject Google Cloud semantic and resource attributes (such as resource name, parent, and project ID) from gRPC request objects into OpenTelemetry spans. Specifically, it adds _extract_t4_attributes and _client_request_hook helper functions in _observability.py, registers the hook in the gRPC client interceptors, and includes comprehensive unit tests to verify this behavior. There are no review comments, so I have no feedback to provide.

[chalmerlowe]

Replaced the manual approach with urllib.parse. Great catch. Thnaks!

[daniel-sanche]

When would you expect this to be non-string? Are you sure we should fall back to the parent in that case?

[chalmerlowe]

This is OBE.

[daniel-sanche]

nit: we could reduce some duplication here:

resource_id = getattr(request, "name", None) or getattr(request, "parent", None)
if isinstance(resource_id, str) and resource_id:
    attrs["gcp.resource.destination.id"] = resource_id

[chalmerlowe]

This is OBE. We no longer process "gcp.resource.destination.id"

[daniel-sanche]

nit: can't this just be _make_grpc_client_request_hook(endpoint_attrs)? It seems like the implementation already handles empty endpoint_attrs, so I'm not sure we need to handle both cases here

[chalmerlowe]

Simplified. Good catch. Appreciate it.

[daniel-sanche]

In the PR description, you say " Without request- and response-level enrichment, spans cannot identify ... normalized string status codes".

Can you expand on that? Does the default instrumenter add code numbers, but not strings? It feels strange that we would have to add the cost of an extra callback layer to do that kind of transformation

Could we add this somewhere else in the stack? Or just stick with error numbers instead of names?

[chalmerlowe]

the PR description was outdated and described an earlier prototype where the response hook was trying to do too much.
To answer your questions directly:

1. Does the default instrumenter add code numbers, but not strings?
   Yes. Upstream opentelemetry-instrumentation-grpc sets rpc.grpc.status_code as an integer (0, 5, etc.) per OTel gRPC conventions. It does not set rpc.response.status_code at all.

2. Can we do this elsewhere / avoid callback translation overhead?
   Yes, we moved error resolution out of this hook. All error status mapping ("NOT_FOUND", "RESOURCE_EXHAUSTED", etc.) and gcp.errors.* attributes are handled directly on the client method span in google.api_core.gapic_v1.method (PR feat(gapic): add OpenTelemetry T3 client method span wrapping in gapic_v1.method (D) #18274) where exceptions are caught naturally.

3. What _grpc_client_response_hook actually does in this PR:
   The response hook here does zero error parsing, zero translation, and zero dictionary lookups. It only stamps rpc.response.status_code = "OK" on successful wire spans (checking span.status first to bail out if an error occurred).
   I've updated the PR description to reflect the current, simplified implementation.

[daniel-sanche]

My main comment is around the response callback. Are you sure it can do what we need? And do we really need a callback for status names?

[daniel-sanche]

My understanding is that request will be a protobuf message, which wouldn't have this field. What do you expect it to be? Can we have any clearer typing here?

[chalmerlowe]

DONE:
processing of the resend_count attribute has been removed.
it is in the deferred category so not required for the MVP.

Handling of:

attrs: dict[str, Any] = {
    "rpc.system.name": "grpc",
}

is now moved to client_request_hook() within _make_grpc_client_request_hook()

[daniel-sanche]

LGTM