CPython runtime garbage collections metrics

.chloggen/cpython-runtime-gc.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: new_component
+
+# The name of the area of concern in the attributes-registry, (e.g. http, cloud, db)
+component: cpython
+
+# A brief description of the change. Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add CPython runtime garbage collector metrics
+
+# 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: [1930]
+
+# (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:

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -37,6 +37,7 @@ body:
         - area:code
         - area:container
         - area:cpu
+        - area:cpython
         - area:db
         - area:deployment
         - area:destination

.github/ISSUE_TEMPLATE/change_proposal.yaml

@@ -29,6 +29,7 @@ body:
         - area:code
         - area:container
         - area:cpu
+        - area:cpython
         - area:db
         - area:deployment
         - area:destination

docs/attributes-registry/README.md

@@ -48,6 +48,7 @@ Currently, the following namespaces exist:
 - [Code](code.md)
 - [Container](container.md)
 - [CPU](cpu.md)
+- [CPython](cpython.md)
 - [DB](db.md)
 - [Deployment](deployment.md)
 - [Destination](destination.md)

docs/attributes-registry/cpython.md

@@ -0,0 +1,22 @@
+<!-- NOTE: THIS FILE IS AUTOGENERATED. DO NOT EDIT BY HAND. -->
+<!-- see templates/registry/markdown/attribute_namespace.md.j2 -->
+
+# CPython
+
+## CPython attributes
+
+This document defines CPython related attributes.
+
+| Attribute | Type | Description | Examples | Stability |
+|---|---|---|---|---|
+| <a id="cpython-gc-generation" href="#cpython-gc-generation">`cpython.gc.generation`</a> | string | Name of the garbage collector collection generation. | `gen0`; `gen1`; `gen2` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+---
+
+`cpython.gc.generation` 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 |
+|---|---|---|
+| `gen0` | Generation 0 | ![Development](https://img.shields.io/badge/-development-blue) |
+| `gen1` | Generation 1 | ![Development](https://img.shields.io/badge/-development-blue) |
+| `gen2` | Generation 2 | ![Development](https://img.shields.io/badge/-development-blue) |

docs/runtime/README.md

@@ -45,6 +45,7 @@ Also consider the
 [OS process metrics](/docs/system/process-metrics.md)
 semantic conventions when instrumenting runtime environments.
 
+- [CPython](cpython-metrics.md)
 - [Go](go-metrics.md)
 - [JVM](jvm-metrics.md)
 - [Node.js](nodejs-metrics.md)

docs/runtime/cpython-metrics.md

@@ -0,0 +1,135 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: CPython
+--->
+
+# Semantic conventions for CPython runtime metrics
+
+**Status**: [Development][DocumentStatus]
+
+This document describes semantic conventions for CPython Runtime metrics in OpenTelemetry.
+
+<!-- toc -->
+
+- [CPython Garbage Collection](#cpython-garbage-collection)
+  - [Metric: `cpython.gc.collections`](#metric-cpythongccollections)
+  - [Metric: `cpython.gc.collected`](#metric-cpythongccollected)
+  - [Metric: `cpython.gc.uncollectable`](#metric-cpythongcuncollectable)
+
+<!-- tocstop -->
+
+## CPython Garbage Collection
+
+**Status**: [development][DocumentStatus]
+
+**Description:** CPython metrics related to garbage collection, captured under the namespace `cpython.gc.*`.
+
+### Metric: `cpython.gc.collections`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.cpython.gc.collections -->
+<!-- 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 |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `cpython.gc.collections` | Counter | `{collection}` | The number of times a generation was collected since interpreter start. [1] | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1]:** This metric reports data from [`gc.stats()`](https://docs.python.org/3/library/gc.html#gc.get_stats)
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`cpython.gc.generation`](/docs/attributes-registry/cpython.md) | string | Name of the garbage collector collection generation. | `gen0`; `gen1`; `gen2` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+---
+
+`cpython.gc.generation` 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 |
+|---|---|---|
+| `gen0` | Generation 0 | ![Development](https://img.shields.io/badge/-development-blue) |
+| `gen1` | Generation 1 | ![Development](https://img.shields.io/badge/-development-blue) |
+| `gen2` | Generation 2 | ![Development](https://img.shields.io/badge/-development-blue) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Metric: `cpython.gc.collected`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.cpython.gc.collected -->
+<!-- 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 |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `cpython.gc.collected.objects` | Counter | `{object}` | The total number of objects collected inside a generation that have occurred since interpreter start. [1] | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1]:** This metric reports data from [`gc.stats()`](https://docs.python.org/3/library/gc.html#gc.get_stats)
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`cpython.gc.generation`](/docs/attributes-registry/cpython.md) | string | Name of the garbage collector collection generation. | `gen0`; `gen1`; `gen2` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+---
+
+`cpython.gc.generation` 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 |
+|---|---|---|
+| `gen0` | Generation 0 | ![Development](https://img.shields.io/badge/-development-blue) |
+| `gen1` | Generation 1 | ![Development](https://img.shields.io/badge/-development-blue) |
+| `gen2` | Generation 2 | ![Development](https://img.shields.io/badge/-development-blue) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+### Metric: `cpython.gc.uncollectable`
+
+This metric is [recommended][MetricRecommended].
+
+<!-- semconv metric.cpython.gc.uncollectable -->
+<!-- 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 |
+| -------- | --------------- | ----------- | -------------- | --------- |
+| `cpython.gc.uncollectable.objects` | Counter | `{object}` | The total number of uncollectable objects inside a generation that have occurred since interpreter start. [1] | ![Development](https://img.shields.io/badge/-development-blue) |
+
+**[1]:** This metric reports data from [`gc.stats()`](https://docs.python.org/3/library/gc.html#gc.get_stats)
+
+| Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
+|---|---|---|---|---|---|
+| [`cpython.gc.generation`](/docs/attributes-registry/cpython.md) | string | Name of the garbage collector collection generation. | `gen0`; `gen1`; `gen2` | `Required` | ![Development](https://img.shields.io/badge/-development-blue) |
+
+---
+
+`cpython.gc.generation` 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 |
+|---|---|---|
+| `gen0` | Generation 0 | ![Development](https://img.shields.io/badge/-development-blue) |
+| `gen1` | Generation 1 | ![Development](https://img.shields.io/badge/-development-blue) |
+| `gen2` | Generation 2 | ![Development](https://img.shields.io/badge/-development-blue) |
+
+<!-- markdownlint-restore -->
+<!-- prettier-ignore-end -->
+<!-- END AUTOGENERATED TEXT -->
+<!-- endsemconv -->
+
+[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.42.0/specification/document-status.md
+[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended

docs/runtime/v8js-metrics.md

@@ -39,7 +39,7 @@ of `[ 0.01, 0.1, 1, 10 ]`.
 | -------- | --------------- | ----------- | -------------- | --------- |
 | `v8js.gc.duration` | Histogram | `s` | Garbage collection duration. [1] | ![Development](https://img.shields.io/badge/-development-blue) |
 
-**[1]:** The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions)
+**[1]:** The values can be retrieved from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions)
 
 | Attribute  | Type | Description  | Examples  | [Requirement Level](https://opentelemetry.io/docs/specs/semconv/general/attribute-requirement-level/) | Stability |
 |---|---|---|---|---|---|

model/cpython/metrics.yaml

@@ -0,0 +1,39 @@
+groups:
+  - id: metric.cpython.gc.collections
+    type: metric
+    metric_name: cpython.gc.collections
+    brief: "The number of times a generation was collected since interpreter start."
+    note: >
+      This metric reports data from [`gc.stats()`](https://docs.python.org/3/library/gc.html#gc.get_stats)
+    instrument: counter
+    unit: "{collection}"
+    stability: development
+    attributes:
+      - ref: cpython.gc.generation
+        requirement_level: required
+
+  - id: metric.cpython.gc.collected
+    type: metric
+    metric_name: cpython.gc.collected.objects
+    brief: "The total number of objects collected inside a generation that have occurred since interpreter start."
+    note: >
+      This metric reports data from [`gc.stats()`](https://docs.python.org/3/library/gc.html#gc.get_stats)
+    instrument: counter
+    unit: "{object}"
+    stability: development
+    attributes:
+      - ref: cpython.gc.generation
+        requirement_level: required
+
+  - id: metric.cpython.gc.uncollectable
+    type: metric
+    metric_name: cpython.gc.uncollectable.objects
+    brief: "The total number of uncollectable objects inside a generation that have occurred since interpreter start."
+    note: >
+      This metric reports data from [`gc.stats()`](https://docs.python.org/3/library/gc.html#gc.get_stats)
+    instrument: counter
+    unit: "{object}"
+    stability: development
+    attributes:
+      - ref: cpython.gc.generation
+        requirement_level: required

model/cpython/registry.yaml

@@ -0,0 +1,25 @@
+groups:
+  - id: registry.cpython
+    type: attribute_group
+    display_name: CPython attributes
+    brief: >
+      This document defines CPython related attributes.
+    attributes:
+      - id: cpython.gc.generation
+        stability: development
+        type:
+          members:
+            - id: gen0
+              value: 'gen0'
+              brief: "Generation 0"
+              stability: development
+            - id: gen1
+              value: 'gen1'
+              brief: "Generation 1"
+              stability: development
+            - id: gen2
+              value: 'gen2'
+              brief: "Generation 2"
+              stability: development
+        brief: Name of the garbage collector collection generation.
+        examples: ["gen0", "gen1", "gen2"]

model/v8js/metrics.yaml

@@ -10,7 +10,7 @@ groups:
       - ref: v8js.gc.type
         requirement_level: required
     note: >
-      The values can be retrieve from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions)
+      The values can be retrieved from [`perf_hooks.PerformanceObserver(...).observe({ entryTypes: ['gc'] })`](https://nodejs.org/api/perf_hooks.html#performanceobserverobserveoptions)
 
   - id: metric.v8js.memory.heap.limit
     type: metric

templates/registry/markdown/weaver.yaml

@@ -12,6 +12,7 @@ acronyms:
   - CloudEvents
   - CloudFoundry
   - CLR
+  - CPython
   - CPU
   - CSI
   - DB