The correct attribution of cloud region for multi-regional client calls

[SrdjanLL]

Hi team, it is my first issue here, so let me know in case there are any missing details/practices.

Use case

As part of open-telemetry/opentelemetry-python-contrib#3210 (Amazon Bedrock instrumentation), I'm hoping to introduce a proper semconv attribute for the cloud region. Looking at this made me wonder about the currently defined attributes for the cloud region and how they play with the scenarios of multi-regional calls from the client side.

When instrumenting client-side API calls to the cloud service running in different regions, it's valuable to capture the target region of the request. This may happen in the case of client's intended of balancing the load, regional failovers or sometimes the same service may offer additional features in different regions (for example Amazon Bedrock model availability differs per AWS region).

Problem

Currently, the standard semantic conventions include the incubating attribute CLOUD_REGION), defined as "The geographical region the resource is running in." This attribute correctly describes the location of the instrumented service (the resource emitting the telemetry).

However, there doesn't appear to be a standard semantic convention specifically designed to capture the cloud region of the remote peer or dependency service being called, particularly for inclusion on the client span representing that call.

Proposal / Request for Discussion

I was hoping to receive some guidance on this if possible and see whether I'm misinterpreting the existing attribute or this is a viable use case for introducing a new attribute.

Alternatives considered:

• Using CLOUD_REGION from incubating attributes here, but the description implied it being tied to a resource, not so much to the destination of an interaction represented by a span.

Next steps:

I would appreciate feedback on:

1. Is this a recognised need? Do others require capturing the target service's region on client spans? So far I've seen such use case in botocore instrumentation here.
2. Are the existing conventions already addressing this and I have missed their meaning?
   • In case this is a viable reason for a new attribute - ideally, this attribute would be associated with client spans and represent the cloud region of the target service being called. The exact mechanism for discovering this target region would be implementation-specific.

[lmolkova]

There is some prior art on this: azure.cosmosdb.operation.contacted_regions which is somewhat specific to that use-case - it's an array. It's also used on CosmosDB spans/metrics.

I agree that we should probably revise the description of cloud.region and make it less about the region app is running in and more generic. It should also be possible to reference this attribute from AWS client SDK spans here https://github.com/open-telemetry/semantic-conventions/blob/28c225759dfeb0a5b861898204bfdfbd441f0512/docs/cloud-providers/aws-sdk.md.

checking with @ppittle and @AsakerMohd in case they have any thoughts from the AWS perspective.

It'd also be useful to bring it up on the SemConv SIG call (8am PT on Monday) and see if people have any thoughts on this.

[xrmx]

It'd also be useful to bring it up on the SemConv SIG call (8am PT on Monday) and see if people have any thoughts on this.

Added to the next notes, thanks @lmolkova !

[ppittle]

I don't have a strong personal opinion on how to approach this, but I could see the value in users wanting the ability to follow the path of a span as it moves across regions.

I wont be able to make the SIG, but please post any decisions made back to this thread.

[xrmx]

Discussed this in May 5th Sem Conv SIG call, no objection in going forward using cloud.region after updating its brief. As suggested here #2142 (comment) we can also reference it in the aws docs.

[SrdjanLL]

Thanks everyone for your help with moving this forward! I created a PR to update the brief and make the mention in AWS docs.
Once this is completed, I will follow up with capturing the attribute in AWS botocore instrumentation.