Deprecate per-rpc status code attributes in favor of rpc.status_code

[lmolkova]

Fixes #1504

Some of the RPC frameworks generate status code on client side when response cannot be received. This includes :

• gRPC:
  https://grpc.io/docs/what-is-grpc/core-concepts/#rpc-termination

  In gRPC, both the client and server make independent and local determinations of the success of the call, and their conclusions may not match. This means that, for example, you could have an RPC that finishes successfully on the server side (“I have sent all my responses!”) but fails on the client side (“The responses arrived after my deadline!”)

  https://grpc.io/docs/guides/status-codes/

  When an error situation occurs, the gRPC library may produce a corresponding status. The library may do this either on the client- or the server-side.

• Connect RPC. Similar to gRPC - client returns error/throws exception when any error happens and may generate deadline_exceeded / cancelled / unknown / unavailable errors

  https://github.com/connectrpc/connect-go/blob/5398e9930ae8e7c06b500f4a0b8ed46c82192d5e/error.go#L274-L278

  Even invalid URL is reported with code unavailable - https://github.com/connectrpc/connect-go/blob/5398e9930ae8e7c06b500f4a0b8ed46c82192d5e/client.go#L391

• Apache Dubbo. Similar - pretty much everything (network, timeouts, serialization errors) is wrapped into RpcException with code defaulting to unknown https://github.com/apache/dubbo/blob/0d8c15adea9061aac1296ce5077384ad8e7b947b/dubbo-rpc/dubbo-rpc-api/src/main/java/org/apache/dubbo/rpc/protocol/AbstractInvoker.java#L280-L335

Since status code may be generated by the client, we're not including response in the status_code.

This PR

• introduces common rpc.status_code attribute
• deprecates rpc.connect_rpc.error_code, rpc.grpc.status_code, rpc.jsonrpc.error_code
• adds recommendation on reporting span status based on rpc.status_code value

[trask]

Some of the RPC frameworks generate status code on client side when response cannot be received. This includes gRPC, Connect RPC and Apache Dubbo. So not including response in the status_code

Can you include a couple examples of this in the PR description? Thanks

[lmolkova]

Can you include a couple examples of this in the PR description? Thanks

@trask sure, updated description with links

[trask]

(related open-telemetry/opentelemetry-specification#3496)

[lmolkova]

I removed the part about error message and created #2967 which is a blocker for RPC stability

[thompson-tomo]

For me I see grpc as warranting it's own attribute to increase interoperability with the grpc metrics & also allow the rpc.status_code to be set by the framework ie Dubbo. Deprecating the other 2 makes sense.

[github-actions]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• otel

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

[lmolkova]

For me I see grpc as warranting it's own attribute to increase interoperability with the grpc metrics

could you elaborate? How would having rpc.status_code and grpc.status_code would help with grpc metrics interoperability?

also allow the rpc.status_code to be set by the framework ie Dubbo. Deprecating the other 2 makes sense.

Looking into Dubbo, it juggles with 3 different sets of error codes (Dubbo, Triple, and HTTP). If it makes sense to report both protocol (grpc / HTTP) and framework (dubbo), I'd assume we'd have dubbo-specific attribute for it instead of making it gRPC responsibility.

[github-actions]

This PR contains changes to area(s) that do not have an active SIG/project and will be auto-closed:

• otel

Such changes may be rejected or put on hold until a new SIG/project is established.

Please refer to the Semantic Convention Areas
document to see the current active SIGs and also to learn how to kick start a new one.

[thompson-tomo]

The grpc.status attribute is an established attribute used by the grpc metrics hence it would decrease the gap between the specs.

Having network request status seperate provides clear indication that the network has been used and it would enable the framework to have a different status to the network. That is important when the framework supports/uses client side caching.

In relation to the examples in the description should we not be using error/exception to capture the details of the status and only setting the rpc.status_code when it is being returned from the server.

Also note grpc doesn't define cancelled as an error but the note on the new attribute indicates everything but ok is an error.

[lmolkova]

The grpc.status attribute is an established attribute used by the grpc metrics hence it would decrease the gap between the specs.

Targeting compatibility with current gRPC metrics would involve way more than grpc.status attribute. Having one attribute with the same name would not help with compatibility if metric names and everything else is different.

Having network request status seperate provides clear indication that the network has been used and it would enable the framework to have a different status to the network. That is important when the framework supports/uses client side caching.

Framework (when there is a framework and it needs separate status code) should then provide that extra status code attribute. Why have discrepancy on the protocol level?

In relation to the examples in the description should we not be using error/exception to capture the details of the status and only setting the rpc.status_code when it is being returned from the server.

could you please add a suggestions on the specific lines so we can have focused discussion and I can understand the context of your comments?

Also note grpc doesn't define cancelled as an error but the note on the new attribute indicates everything but ok is an error.

Same here, in the future, please leave comment on specific lines so it's easier to understand what you mean.
Substantially: I broke down the table we already have here https://github.com/open-telemetry/semantic-conventions/blob/main/docs/rpc/grpc.md#grpc-status into notes on rpc.status_code without changing the behavior. I agree cancelled status being error is the issue and we're going to address it in #560 which is blocking for RPC stability.

[lmolkova]

SIG discussion:

• generic error.type mentions gRPC status code - let's generalize it
• let's refine error.type on RPC conventions to explain what to do wrt status code