Question: naming conventions, prefer . (dot) or _ (underscore)?

[jviau]

I have a question regarding naming conventions. When looking at FaaS metrics sematic conventions here, I see the names uses a mix of . and _. So my question is:

Why was a name like faas.invoke_duration chosen over faas.invoke.duration?

As I add my own metrics, I want to make sure I understand this rationale and know when to use . vs _ for names.

[jviau]

I also just noticed it is not consistent: RPC spec follows rpc.server.duration here.

So I am guessing this is just in progress?

[reyang]

The minimum bar is captured by the API spec https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-naming-rule.

My general observation is that folks intend to use . to group things in hierarchical way, and _ is used to improve readability if a particular term has multiple words.

Some additional things to consider while exporting the data to specific backends, e.g. https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/data-model.md#otlp-metric-points-to-prometheus

[reyang]

I also just noticed it is not consistent: RPC spec follows rpc.server.duration here.

So I am guessing this is just in progress?

Yes, if you scroll to the very top of this spec, you can see it marked as Experimental instead of Stable, which means it could have breaking changes or even get removed or redesigned in the near future.

[Oberon00]

Probably it makes sense to apply the same logic as with attribute naming: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/attribute-naming.md

[jviau]

Thank you for the links and explanation.

@reyang - regarding rpc.server.duration vs faas.invoke_duration. Both are marked as "Experimental". Would you know, or be able to guess, which direction OTel will settle on? (I personally am more of a fan of rpc.server.duration).

[joaopgrassi]

My interpretation is also as @reyang mentioned. A dot . is for grouping or "namespacing" things together. Your example of rpc.server., it has a dot after server, because server is the grouping of multiple metrics like duration and requests_per_rpc.

For the faas.invoke_duration I'd imagine that it was chosen like that because invoke alone is not a "grouping". If there was more sub-metrics under invoke then it would make sense to use what you propose, faas.invoke.duration. But since it's just a concept on itself then it's under the top-level faas. An underscore then is how one can combine multiple words.

[jviau]

faas invoked does have a grouping concept, at least in the attributes: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/semantic_conventions/faas-metrics.md#attributes faas.invoked_name, faas.invoked_provider, and faas.invoked_region. I could also see more metrics based on invoked, just like rpc.server.* - could have faas.invoked.request.size and faas.invoked.response.size

But this issue isn't to argue/discuss the choice of FaaS naming. I have my answer: . when it is a grouping, _ when it is multi-word separation. What is a grouping vs multi-word is always going to be subjective. Thank you for the answers.

[Oberon00]

For FaaS, "invoked" is not really suitable as a namespace IMHO. "faas.invoked.request.size" = the size of the invoked request? That does not make sense. Maybe it would be better to rename this to faas.invocation.request.size, faas.invocation.peer.provider, etc.