diff --git a/.chloggen/abbr.yaml b/.chloggen/abbr.yaml new file mode 100755 index 000000000..31b3df5e4 --- /dev/null +++ b/.chloggen/abbr.yaml @@ -0,0 +1,22 @@ +# Use this changelog template to create an entry for release notes. +# +# If your change doesn't affect end users you should instead start +# your pull request title with [chore] or use the "Skip Changelog" label. + +# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix' +change_type: enhancement + +# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db) +component: all + +# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`). +note: Define name abbreviations guidelines in attribute and metric names. + +# Mandatory: One or more tracking issues related to the change. You can use the PR number here if no issue exists. +# The values here must be integers. +issues: [1121] + +# (Optional) One or more lines of additional information to render under the primary note. +# These lines will be padded with 2 spaces and then inserted directly into the document. +# Use pipe (|) for multiline entries. +subtext: diff --git a/docs/general/attribute-naming.md b/docs/general/attribute-naming.md index c45a92e1b..3b3445cb4 100644 --- a/docs/general/attribute-naming.md +++ b/docs/general/attribute-naming.md @@ -7,7 +7,8 @@ -- [Name Pluralization guidelines](#name-pluralization-guidelines) +- [Name Pluralization Guidelines](#name-pluralization-guidelines) +- [Name Abbreviation Guidelines](#name-abbreviation-guidelines) - [Name Reuse Prohibition](#name-reuse-prohibition) - [Recommendations for OpenTelemetry Authors](#recommendations-for-opentelemetry-authors) - [Recommendations for Application Developers](#recommendations-for-application-developers) @@ -57,7 +58,7 @@ Names SHOULD follow these rules: versa: any existing namespace prohibits existence of an equally named attribute key in the future. -## Name Pluralization guidelines +## Name Pluralization Guidelines - When an attribute represents a single entity, the attribute name SHOULD be singular. Examples: `host.name`, `container.id`. @@ -70,6 +71,16 @@ Names SHOULD follow these rules: [Metric Name Pluralization Guidelines](./metrics.md#pluralization) SHOULD be followed for the attribute name. +## Name Abbreviation Guidelines + +Abbreviations MAY be used when they are widely recognized and commonly used. + +Examples include common technical abbreviations such as `IP`, `DB`, `CPU`, +`HTTP`, `URL`, or product names like `AWS`, `GCP`, `K8s`. + +Abbreviations SHOULD be avoided if they are ambiguous, for example, when they apply +to multiple products or concepts. + ## Name Reuse Prohibition A new attribute MUST NOT be added with the same name as an attribute that diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 6dffdaa3d..09892e5fc 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -82,6 +82,9 @@ and confusion for end users. (For example, prefer `process.runtime.java.gc*` ove `process.runtime.gc.*`.) Measures of many operating system metrics are similarly ambiguous. +Metric names and attributes SHOULD follow the general +[name abbreviation guidelines](attribute-naming.md#name-abbreviation-guidelines). + ### Name Reuse Prohibition A new metric MUST NOT be added with the same name as a metric that existed in