Merge branch 'main' into session_start_and_end_events

breedx-splk · Jul 29, 2024 · 46f22a0 · 46f22a0
2 parents 929d3c3 + a44ff76
commit 46f22a0
Show file tree

Hide file tree

Showing 27 changed files with 222 additions and 19 deletions.
diff --git a/.chloggen/add_linux_memory_slab.yaml b/.chloggen/add_linux_memory_slab.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: linux
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add the `system.linux.memory.slab.usage` metric and the `linux.memory.slab.state` attributes.
+
+# 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: [531]
+
+# (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/.chloggen/jvm_memory-buffer_metric_renaming.yaml b/.chloggen/jvm_memory-buffer_metric_renaming.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: breaking
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: jvm
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: "Rename JVM metric `jvm.buffer.memory.usage` to `jvm.buffer.memory.used`"
+
+# 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: [288]
+
+# (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/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml
@@ -52,6 +52,7 @@ body:
         - area:http
         - area:jvm
         - area:k8s
+        - area:linux
         - area:log
         - area:messaging
         - area:network

diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml
@@ -45,6 +45,7 @@ body:
         - area:http
         - area:jvm
         - area:k8s
+        - area:linux
         - area:log
         - area:messaging
         - area:network

diff --git a/.github/ISSUE_TEMPLATE/new-conventions.yaml b/.github/ISSUE_TEMPLATE/new-conventions.yaml
@@ -54,6 +54,7 @@ body:
         - area:http
         - area:jvm
         - area:k8s
+        - area:linux
         - area:log
         - area:messaging
         - area:network

diff --git a/docs/README.md b/docs/README.md
@@ -42,3 +42,5 @@ Semantic Conventions by signals:
 * [Metrics](general/metrics.md): Semantic Conventions for metrics.
 * [Resource](resource/README.md): Semantic Conventions for resources.
 * [Trace](general/trace.md): Semantic Conventions for traces and spans.
+
+Also see, [Non-normative supplementary information](non-normative/README.md).
diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md
@@ -66,6 +66,7 @@ Currently, the following namespaces exist:
 - [iOS](ios.md)
 - [JVM](jvm.md)
 - [K8s](k8s.md)
+- [Linux](linux.md)
 - [Log](log.md)
 - [Messaging](messaging.md)
 - [Network](network.md)

diff --git a/docs/attributes-registry/linux.md b/docs/attributes-registry/linux.md
@@ -0,0 +1,22 @@
+<!--- Hugo front matter used to generate the website version of this page:
+--->
+
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# Linux
+
+## Linux Memory Attributes
+
+Describes Linux Memory attributes
+
+| Attribute                 | Type   | Description                 | Examples                       | Stability                                                        |
+| ------------------------- | ------ | --------------------------- | ------------------------------ | ---------------------------------------------------------------- |
+| `linux.memory.slab.state` | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`linux.memory.slab.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value           | Description   | Stability                                                        |
+| --------------- | ------------- | ---------------------------------------------------------------- |
+| `reclaimable`   | reclaimable   | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `unreclaimable` | unreclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
diff --git a/docs/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md
@@ -15,7 +15,7 @@ Some descriptions are also provided for populating general OpenTelemetry semanti
 
 ## Context Propagation
 
-See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation).
+See [compatibility](../non-normative/compatibility/aws.md#context-propagation).
 
 ## Common Attributes
 

diff --git a/docs/faas/aws-lambda.md b/docs/faas/aws-lambda.md
@@ -168,7 +168,7 @@ For every message in the event, the [message system attributes][] (not message a
 the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be
 parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/context/api-propagators.md) and
 added as a link to the span. This means the span may have as many links as messages in the batch.
-See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info.
+See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info.
 
 - [`faas.trigger`][faas] MUST be set to `pubsub`.
 - [`messaging.operation.type`](/docs/messaging/messaging-spans.md) MUST be set to `process`.
@@ -181,7 +181,7 @@ corresponding to the SQS event. The [message system attributes][] (not message a
 the user) SHOULD be checked for the key `AWSTraceHeader`. If it is present, an OpenTelemetry `Context` SHOULD be
 parsed from the value of the attribute using the [AWS X-Ray Propagator](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.33.0/specification/context/api-propagators.md) and
 added as a link to the span.
-See [compatibility](../../supplementary-guidelines/compatibility/aws.md#context-propagation) for more info.
+See [compatibility](../non-normative/compatibility/aws.md#context-propagation) for more info.
 
 - [`faas.trigger`][faas] MUST be set to `pubsub`.
 - [`messaging.operation.type`](/docs/messaging/messaging-spans.md#messaging-attributes) MUST be set to `process`.

diff --git a/docs/general/attributes.md b/docs/general/attributes.md
@@ -1,6 +1,6 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Attributes
-aliases: [docs/specs/semconv/general/general-attributes]
+aliases: [general-attributes]
 --->
 
 # General Attributes

diff --git a/docs/general/events.md b/docs/general/events.md
@@ -1,6 +1,6 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Events
-aliases: [docs/specs/semconv/general/events-general]
+aliases: [events-general]
 --->
 
 # Semantic Conventions for Events

diff --git a/docs/general/logs.md b/docs/general/logs.md
@@ -1,6 +1,6 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Logs
-aliases: [docs/specs/semconv/general/logs-general]
+aliases: [logs-general]
 --->
 
 # General Logs Attributes

diff --git a/docs/general/metrics.md b/docs/general/metrics.md
@@ -1,6 +1,6 @@
 <!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Metrics
-aliases: [docs/specs/semconv/general/metrics-general]
+aliases: [metrics-general]
 --->
 
 # Metrics Semantic Conventions

diff --git a/docs/non-normative/README.md b/docs/non-normative/README.md
@@ -0,0 +1,11 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Non-normative
+path_base_for_github_subdir:
+  from: tmp/semconv/docs/non-normative/_index.md
+  to: non-normative/README.md
+--->
+
+# Non-normative supplementary information
+
+The pages in this section are **non-normative**, most are supplementary
+guidelines.
diff --git a/docs/non-normative/compatibility/README.md b/docs/non-normative/compatibility/README.md
@@ -0,0 +1,7 @@
+<!--- Hugo front matter used to generate the website version of this page:
+path_base_for_github_subdir:
+  from: tmp/semconv/docs/non-normative/compatibility/_index.md
+  to: non-normative/compatibility/README.md
+--->
+
+# Compatibility
diff --git a/...lementary-guidelines/compatibility/aws.md → docs/non-normative/compatibility/aws.md b/...lementary-guidelines/compatibility/aws.md → docs/non-normative/compatibility/aws.md
@@ -1,6 +1,10 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: AWS
+--->
+
 # Compatibility Considerations for AWS
 
-This document highlights compatibility considerations for OpenTelemetry
+This page highlights compatibility considerations for OpenTelemetry
 instrumentations when interacting with AWS managed services using an aws-sdk,
 a third-party library, or a direct HTTP request.
 

diff --git a/docs/http/migration-guide.md → docs/non-normative/http-migration.md b/docs/http/migration-guide.md → docs/non-normative/http-migration.md
@@ -1,4 +1,9 @@
-# HTTP semantic convention stability migration guide
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: HTTP migration
+aliases: [../http/migration-guide]
+--->
+
+# HTTP semantic convention stability migration
 
 Due to the significant number of modifications and the extensive user base
 affected by them, existing HTTP instrumentations published by
@@ -207,7 +212,7 @@ which case `{summary}` is `HTTP`.
 
 ### Migrating from `<= v1.16.0`
 
-This document does not cover these versions.
+This page does not cover these versions.
 
 [Host header]: https://tools.ietf.org/html/rfc7230#section-5.4
 [HTTP/2 authority]: https://tools.ietf.org/html/rfc9113#section-8.3.1

diff --git a/...s/semantic_conventions_code_generation.md → docs/non-normative/libraries.md b/...s/semantic_conventions_code_generation.md → docs/non-normative/libraries.md
@@ -1,3 +1,8 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Libraries
+# Renamed from: semantic_conventions_code_generation
+--->
+
 # Semantic convention libraries
 
 <!-- toc -->
@@ -115,4 +120,4 @@ Code-generation usually involves several steps which could be semi-automated:
 5. Fix lint violations in the auto-generated code (if any)
 6. Send the PR with new code to the corresponding repository
 
-Here're the examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh).
+Here are examples of how steps 2-5 are implemented for [Java](https://github.com/open-telemetry/semantic-conventions-java/blob/7da24068eea69dff11a78d59750b115dc4c5854d/build.gradle.kts#L55-L137) and [Python](https://github.com/open-telemetry/opentelemetry-python/blob/397e357dfad3e6ff42c09c74d5945dfdcad24bdd/scripts/semconv/generate.sh).
diff --git a/docs/runtime/jvm-metrics.md b/docs/runtime/jvm-metrics.md
@@ -33,7 +33,7 @@ This document describes semantic conventions for JVM metrics in OpenTelemetry.
   - [Metric: `jvm.memory.init`](#metric-jvmmemoryinit)
   - [Metric: `jvm.system.cpu.utilization`](#metric-jvmsystemcpuutilization)
   - [Metric: `jvm.system.cpu.load_1m`](#metric-jvmsystemcpuload_1m)
-  - [Metric: `jvm.buffer.memory.usage`](#metric-jvmbuffermemoryusage)
+  - [Metric: `jvm.buffer.memory.used`](#metric-jvmbuffermemoryused)
   - [Metric: `jvm.buffer.memory.limit`](#metric-jvmbuffermemorylimit)
   - [Metric: `jvm.buffer.count`](#metric-jvmbuffercount)
 
@@ -743,12 +743,12 @@ This metric is obtained from [`OperatingSystemMXBean#getSystemLoadAverage()`](ht
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-### Metric: `jvm.buffer.memory.usage`
+### Metric: `jvm.buffer.memory.used`
 
 This metric is [recommended][MetricRecommended].
 This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/BufferPoolMXBean.html#getMemoryUsed--).
 
-<!-- semconv metric.jvm.buffer.memory.usage(metric_table) -->
+<!-- semconv metric.jvm.buffer.memory.used(metric_table) -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->
@@ -757,15 +757,15 @@ This metric is obtained from [`BufferPoolMXBean#getMemoryUsed()`](https://docs.o
 
 | Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
 | -------- | --------------- | ----------- | -------------- | --------- |
-| `jvm.buffer.memory.usage` | UpDownCounter | `By` | Measure of memory used by buffers. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `jvm.buffer.memory.used` | UpDownCounter | `By` | Measure of memory used by buffers. | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
 
 
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->
 <!-- endsemconv -->
 
-<!-- semconv metric.jvm.buffer.memory.usage(full) -->
+<!-- semconv metric.jvm.buffer.memory.used(full) -->
 <!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
 <!-- see templates/registry/markdown/snippet.md.j2 -->
 <!-- prettier-ignore-start -->

diff --git a/docs/system/system-metrics.md b/docs/system/system-metrics.md
@@ -57,6 +57,7 @@ Resource attributes related to a host, SHOULD be reported under the `host.*` nam
   - [Metric: `system.process.created`](#metric-systemprocesscreated)
 - [`system.{os}.` - OS Specific System Metrics](#systemos---os-specific-system-metrics)
   - [Metric: `system.linux.memory.available`](#metric-systemlinuxmemoryavailable)
+  - [Metric: `system.linux.memory.slab.usage`](#metric-systemlinuxmemoryslabusage)
 
 <!-- tocstop -->
 
@@ -1475,6 +1476,58 @@ See also `MemAvailable` in [/proc/meminfo](https://man7.org/linux/man-pages/man5
 
 
 
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Metric: `system.linux.memory.slab.usage`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.system.linux.memory.slab.usage(metric_table) -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Name     | Instrument Type | Unit (UCUM) | Description    | Stability |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `system.linux.memory.slab.usage` | UpDownCounter | `By` | Reports the memory used by the Linux kernel for managing caches of frequently used objects. [1] | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+**[1]:** The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system.
+Note that the total slab memory is not constant and may vary over time.
+See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
+
+
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+<!-- semconv metric.system.linux.memory.slab.usage(full) -->
+<!-- NOTE: THIS TEXT IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/snippet.md.j2 -->
+<!-- prettier-ignore-start -->
+<!-- markdownlint-capture -->
+<!-- markdownlint-disable -->
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`linux.memory.slab.state`](/docs/attributes-registry/linux.md) | string | The Linux Slab memory state | `reclaimable`; `unreclaimable` | `Recommended` | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+`linux.memory.slab.state` has the following list of well-known values. If one of them applies, then the respective value MUST be used; otherwise, a custom value MAY be used.
+
+| Value  | Description | Stability |
+|---|---|---|
+| `reclaimable` | reclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+| `unreclaimable` | unreclaimable | ![Experimental](https://img.shields.io/badge/-experimental-blue) |
+
+
+
 <!-- markdownlint-restore -->
 <!-- prettier-ignore-end -->
 <!-- END AUTOGENERATED TEXT -->

diff --git a/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh
@@ -27,7 +27,7 @@ fix_file() {
    "$1"
 }
 
-important_files=("docs" "model" "README.md" "supplementary-guidelines")
+important_files=("docs" "model" "README.md")
 
 # TODO - limit to markdown/yaml files?
 find "${important_files[@]}" -type f -not -path '*/.*' -print0 | while read -d $'\0' file; do

diff --git a/model/metrics/deprecated/jvm-metrics.yaml b/model/metrics/deprecated/jvm-metrics.yaml
@@ -0,0 +1,10 @@
+groups:
+  - id: metric.jvm.buffer.memory.usage.deprecated
+    type: metric
+    metric_name: jvm.buffer.memory.usage
+    stability: experimental
+    deprecated: "Replaced by `jvm.buffer.memory.used`."
+    brief: "Deprecated, use `jvm.buffer.memory.used` instead."
+    extends: attributes.jvm.buffer
+    instrument: updowncounter
+    unit: "By"
diff --git a/model/metrics/jvm-metrics-experimental.yaml b/model/metrics/jvm-metrics-experimental.yaml
@@ -42,9 +42,9 @@ groups:
       - ref: jvm.buffer.pool.name
         requirement_level: recommended
 
-  - id: metric.jvm.buffer.memory.usage
+  - id: metric.jvm.buffer.memory.used
     type: metric
-    metric_name: jvm.buffer.memory.usage
+    metric_name: jvm.buffer.memory.used
     stability: experimental
     extends: attributes.jvm.buffer
     brief: "Measure of memory used by buffers."

diff --git a/model/metrics/system-metrics.yaml b/model/metrics/system-metrics.yaml
@@ -342,3 +342,17 @@ groups:
     instrument: updowncounter
     unit: "By"
     attributes: []
+
+  - id: metric.system.linux.memory.slab.usage
+    type: metric
+    metric_name: system.linux.memory.slab.usage
+    stability: experimental
+    brief: "Reports the memory used by the Linux kernel for managing caches of frequently used objects."
+    note: |
+      The sum over the `reclaimable` and `unreclaimable` state values in `linux.memory.slab.usage` SHOULD be equal to the total slab memory available on the system.
+      Note that the total slab memory is not constant and may vary over time.
+      See also the [Slab allocator](https://blogs.oracle.com/linux/post/understanding-linux-kernel-memory-statistics) and `Slab` in [/proc/meminfo](https://man7.org/linux/man-pages/man5/proc.5.html).
+    instrument: updowncounter
+    unit: "By"
+    attributes:
+      - ref: linux.memory.slab.state