From 5adf5a46b5118403ec8703ef5b6743214fb2c5a3 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Fri, 6 Oct 2023 14:56:04 +0200 Subject: [PATCH 1/3] Add folder for runtime environment semconv --- .../README.md} | 46 +++++++++---------- docs/{jvm => runtime}/jvm-metrics.md | 0 2 files changed, 23 insertions(+), 23 deletions(-) rename docs/{system/runtime-environment-metrics.md => runtime/README.md} (50%) rename docs/{jvm => runtime}/jvm-metrics.md (100%) diff --git a/docs/system/runtime-environment-metrics.md b/docs/runtime/README.md similarity index 50% rename from docs/system/runtime-environment-metrics.md rename to docs/runtime/README.md index c77222063a..a60539ebaa 100644 --- a/docs/system/runtime-environment-metrics.md +++ b/docs/runtime/README.md @@ -1,28 +1,24 @@ -# Semantic Conventions for Runtime Environment Metrics +# Semantic Conventions for Runtime Environment **Status**: [Experimental][DocumentStatus] -This document includes semantic conventions for runtime environment level -metrics in OpenTelemetry. Also consider the [general -metric](/docs/general/metrics.md#general-metric-semantic-conventions), [system -metrics](system-metrics.md) and [OS Process metrics](process-metrics.md) -semantic conventions when instrumenting runtime environments. +This document defines semantic conventions for +runtime environment spans, metrics and logs. -- [Metric Instruments](#metric-instruments) - * [Runtime Environment Specific Metrics - `process.runtime.{environment}.`](#runtime-environment-specific-metrics---processruntimeenvironment) -- [Attributes](#attributes) +- [Metrics](#metrics) + * [Attributes](#attributes) -## Metric Instruments +## Metrics Runtime environments vary widely in their terminology, implementation, and relative values for a given metric. For example, Go and Python are both @@ -32,26 +28,30 @@ does not propose any standard top-level runtime metric instruments. See [OTEP 108](https://github.com/open-telemetry/oteps/pull/108/files) for additional discussion. -### Runtime Environment Specific Metrics - `process.runtime.{environment}.` - Metrics specific to a certain runtime environment should be prefixed with -`process.runtime.{environment}.` and follow the semantic conventions outlined in -[general metric semantic -conventions](/docs/general/metrics.md#general-metric-semantic-conventions). Authors of -runtime instrumentations are responsible for the choice of `{environment}` to -avoid ambiguity when interpreting a metric's name or values. +the runtime's top-level namespace `{environment}.*`, e.g., `jvm.*` and follow the +[general metric semantic convention guidelines](/docs/general/metrics.md#general-metric-semantic-conventions). + +Authors of runtime instrumentations are responsible for the choice of +`{environment}` to avoid ambiguity when interpreting a metric's name or values. For example, some programming languages have multiple runtime environments that vary significantly in their implementation, like [Python which has many implementations](https://wiki.python.org/moin/PythonImplementations). For such languages, consider using specific `{environment}` prefixes to avoid -ambiguity, like `process.runtime.cpython.` and `process.runtime.pypy.`. +ambiguity, like `cpython.*` and `pypy.*`. + +Also consider the +[general metrics](/docs/general/metrics.md#general-metric-semantic-conventions), +[system metrics](/docs/system/system-metrics.md) and +[OS process metrics](/docs/system/process-metrics.md) +semantic conventions when instrumenting runtime environments. -There are other dimensions even within a given runtime environment to -consider, for example pthreads vs green thread implementations. +- [JVM](jvm-metrics.md) -## Attributes +### Attributes -[`process.runtime`](/docs/resource/process.md#process-runtimes) resource attributes SHOULD be included on runtime metric events as appropriate. +[`process.runtime`](/docs/resource/process.md#process-runtimes) +resource attributes SHOULD be included on runtime metric events as appropriate. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/jvm/jvm-metrics.md b/docs/runtime/jvm-metrics.md similarity index 100% rename from docs/jvm/jvm-metrics.md rename to docs/runtime/jvm-metrics.md From de616f89d416b4b48448a8509833d109f995a078 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Fri, 6 Oct 2023 15:20:52 +0200 Subject: [PATCH 2/3] fix dead links --- docs/general/metrics.md | 2 +- docs/system/README.md | 2 +- docs/system/process-metrics.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index c4c6398fbf..2601373185 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -35,7 +35,7 @@ The following semantic conventions surrounding metrics are defined: * [System](/docs/system/system-metrics.md): For standard system metrics. * [Hardware](/docs/system/hardware-metrics.md): For hardware-related metrics. * [Process](/docs/system/process-metrics.md): For standard process metrics. - * [Runtime Environment](/docs/system/runtime-environment-metrics.md): For runtime environment metrics. + * [Runtime Environment](/docs/runtime/readme.md#metrics): For runtime environment metrics. Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with diff --git a/docs/system/README.md b/docs/system/README.md index 7e6be0f0e4..0df014ead6 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -16,6 +16,6 @@ System semantic conventions are defined for the following metrics: * [System](system-metrics.md): For standard system metrics. * [Hardware](hardware-metrics.md): For hardware-related metrics. * [Process](process-metrics.md): For standard process metrics. -* [Runtime Environment](runtime-environment-metrics.md): For runtime environment metrics. +* [Runtime Environment](/docs/runtime/readme.md#metrics): For runtime environment metrics. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index d287b94a7d..35ce1d79ae 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -13,7 +13,7 @@ instruments not explicitly defined in this document. OS process metrics are not related to the runtime environment of the program, and should take measurements from the operating system. For runtime environment metrics see [semantic conventions for runtime environment -metrics](runtime-environment-metrics.md). +metrics](/docs/runtime/readme.md#metrics). From 317c6fa308845718a2fbdfd946fb9ba728cfc397 Mon Sep 17 00:00:00 2001 From: Joao Grassi Date: Fri, 6 Oct 2023 15:22:47 +0200 Subject: [PATCH 3/3] fix dead links --- docs/general/metrics.md | 2 +- docs/system/README.md | 2 +- docs/system/process-metrics.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 2601373185..564d929a6a 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -35,7 +35,7 @@ The following semantic conventions surrounding metrics are defined: * [System](/docs/system/system-metrics.md): For standard system metrics. * [Hardware](/docs/system/hardware-metrics.md): For hardware-related metrics. * [Process](/docs/system/process-metrics.md): For standard process metrics. - * [Runtime Environment](/docs/runtime/readme.md#metrics): For runtime environment metrics. + * [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. Apart from semantic conventions for metrics, [traces](trace.md), [logs](logs.md), and [events](events.md), OpenTelemetry also defines the concept of overarching [Resources](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/resource/sdk.md) with diff --git a/docs/system/README.md b/docs/system/README.md index 0df014ead6..8d47ef9fcc 100644 --- a/docs/system/README.md +++ b/docs/system/README.md @@ -16,6 +16,6 @@ System semantic conventions are defined for the following metrics: * [System](system-metrics.md): For standard system metrics. * [Hardware](hardware-metrics.md): For hardware-related metrics. * [Process](process-metrics.md): For standard process metrics. -* [Runtime Environment](/docs/runtime/readme.md#metrics): For runtime environment metrics. +* [Runtime Environment](/docs/runtime/README.md#metrics): For runtime environment metrics. [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/tree/v1.22.0/specification/document-status.md diff --git a/docs/system/process-metrics.md b/docs/system/process-metrics.md index 35ce1d79ae..25a6eb8bc4 100644 --- a/docs/system/process-metrics.md +++ b/docs/system/process-metrics.md @@ -13,7 +13,7 @@ instruments not explicitly defined in this document. OS process metrics are not related to the runtime environment of the program, and should take measurements from the operating system. For runtime environment metrics see [semantic conventions for runtime environment -metrics](/docs/runtime/readme.md#metrics). +metrics](/docs/runtime/README.md#metrics).