Please guide how to properly extend attributes for not-yet-documented protocols

[Rast1234]

What are you trying to achieve?

I am implementing tracing library for Json Rpc 2.0. It would be convenient to have some additional attributes as GRPC does: rpc.grpc.status_code. However, it is not clear to me how to extend attributes properly. I can think of two approaches:

1. Use existing attrs and extend them:

• rpc.system = jsonrpc. Question: is this attribute intended to be used for any sort of RPC? Since i can't find closed list of allowed values...
• rpc.jsonrpc.something_protocol_related = "blah" because GRPC does the same

2. Make completely separate attrs like com.my_organization.jsonrpc.something_protocol_related since Json Rpc is not standartized here (yet) to avoid collisions in future

I followed docs about semantic conventions and naming and i see the pattern how attributes extend for specific protocols. However i'm not sure if extensibility by nesting is intended for developers outside of opentelemetry project. Question here is: should we treat attributes mentioned in these docs as read-only allowed things or can we extend them?

[Oberon00]

rpc.system = jsonrpc. Question: is this attribute intended to be used for any sort of RPC? Since i can't find closed list of allowed values...

Good point, that should probably be formatted as an (open) enum. It would be intended to be used for such a case.

should we treat attributes mentioned in these docs as read-only allowed things or can we extend them?

Most "enum"-like attributes explicitly allow using "a custom value", and rpc.system is IMHO supposed to be one of them.

[Oberon00]

For adding new attributes, I would use a custom prefix. E.g. for your example I would use my_organization.rpc.jsonrpc.something_protocol_related if you do not intend to contribute semantic conventions for Json Rpc to OpenTelemetry. However if we are talking about that JSON RPC https://en.wikipedia.org/wiki/JSON-RPC, then I think it would be best to create a PR with your suggested semantic conventions. In the meantime, if you already need them, use the version with the prefix internally or be prepared for them to change during PR review.

[Rast1234]

Thanks!

Most "enum"-like attributes explicitly allow using "a custom value"

Can you please point where it is in the specification? I've seen only explicitly closed "enums" like messaging.destination_kind: only queue or topic are allowed.

Next thing i was going to ask: is a PR welcome. I am going to contribute JSON RPC then :)

[reyang]

Discussed during the issue triage, the namespace approach (use company/product/project/etc. names) seems to be the safe way to go.
It would be helpful if @Rast1234 you could send a PR to capture this in the semantic convention doc?

[Rast1234]

I'll think how to put this into docs. However,currently i'm waiting (indefinetly) for my company to allow signing CLA for another PR...

[Oberon00]

Can you please point where it is in the specification?

For example db.system: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/semantic_conventions/database.md#connection-level-attributes. The spec there is: "db.system MUST be one of the following or, if none of the listed values apply, a custom value"