diff --git a/.chloggen/cpython-runtime-gc.yaml b/.chloggen/cpython-runtime-gc.yaml new file mode 100644 index 0000000000..d418d8dcc0 --- /dev/null +++ b/.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: diff --git a/.github/ISSUE_TEMPLATE/bug_report.yaml b/.github/ISSUE_TEMPLATE/bug_report.yaml index 4edc8d9694..1cb895abdb 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yaml +++ b/.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 diff --git a/.github/ISSUE_TEMPLATE/change_proposal.yaml b/.github/ISSUE_TEMPLATE/change_proposal.yaml index b9e963a44b..a472a40433 100644 --- a/.github/ISSUE_TEMPLATE/change_proposal.yaml +++ b/.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 diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 629a46c242..da8bcd7a3d 100644 --- a/docs/attributes-registry/README.md +++ b/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) diff --git a/docs/attributes-registry/cpython.md b/docs/attributes-registry/cpython.md new file mode 100644 index 0000000000..45a307c474 --- /dev/null +++ b/docs/attributes-registry/cpython.md @@ -0,0 +1,22 @@ + + + +# CPython + +## CPython attributes + +This document defines CPython related attributes. + +| Attribute | Type | Description | Examples | Stability | +|---|---|---|---|---| +| `cpython.gc.generation` | 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) | diff --git a/docs/runtime/README.md b/docs/runtime/README.md index d4632bb4d8..b68c014536 100644 --- a/docs/runtime/README.md +++ b/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) diff --git a/docs/runtime/cpython-metrics.md b/docs/runtime/cpython-metrics.md new file mode 100644 index 0000000000..572b7ad3c7 --- /dev/null +++ b/docs/runtime/cpython-metrics.md @@ -0,0 +1,135 @@ + + +# Semantic conventions for CPython runtime metrics + +**Status**: [Development][DocumentStatus] + +This document describes semantic conventions for CPython Runtime metrics in OpenTelemetry. + + + +- [CPython Garbage Collection](#cpython-garbage-collection) + - [Metric: `cpython.gc.collections`](#metric-cpythongccollections) + - [Metric: `cpython.gc.collected.objects`](#metric-cpythongccollectedobjects) + - [Metric: `cpython.gc.uncollectable.objects`](#metric-cpythongcuncollectableobjects) + + + +## 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]. + + + + + + + + +| 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) | + + + + + + +### Metric: `cpython.gc.collected.objects` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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) | + + + + + + +### Metric: `cpython.gc.uncollectable.objects` + +This metric is [recommended][MetricRecommended]. + + + + + + + + +| 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) | + + + + + + +[DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.42.0/specification/document-status.md +[MetricRecommended]: /docs/general/metric-requirement-level.md#recommended diff --git a/docs/runtime/v8js-metrics.md b/docs/runtime/v8js-metrics.md index efb690232f..da4ae25141 100644 --- a/docs/runtime/v8js-metrics.md +++ b/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 | |---|---|---|---|---|---| diff --git a/model/cpython/metrics.yaml b/model/cpython/metrics.yaml new file mode 100644 index 0000000000..543c7aa91f --- /dev/null +++ b/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.objects + 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.objects + 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 diff --git a/model/cpython/registry.yaml b/model/cpython/registry.yaml new file mode 100644 index 0000000000..94569fd0c3 --- /dev/null +++ b/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"] diff --git a/model/v8js/metrics.yaml b/model/v8js/metrics.yaml index 30925ce0ce..0ca777563f 100644 --- a/model/v8js/metrics.yaml +++ b/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 diff --git a/templates/registry/markdown/weaver.yaml b/templates/registry/markdown/weaver.yaml index cbe61f30e3..c5440dcf00 100644 --- a/templates/registry/markdown/weaver.yaml +++ b/templates/registry/markdown/weaver.yaml @@ -12,6 +12,7 @@ acronyms: - CloudEvents - CloudFoundry - CLR + - CPython - CPU - CSI - DB