From 21163cf5a8692f4f08ae66a7f6abbfc8b0082c74 Mon Sep 17 00:00:00 2001 From: Alex Boten <223565+codeboten@users.noreply.github.com> Date: Thu, 22 Aug 2024 14:38:28 -0700 Subject: [PATCH 1/8] Collector telemetry lifecycle This is an initial attempt at documenting the lifecycle of telemetry emitted by the Collector. Fixes https://github.com/open-telemetry/opentelemetry-collector/issues/10003 Signed-off-by: Alex Boten <223565+codeboten@users.noreply.github.com> --- .../en/docs/collector/internal-telemetry.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/content/en/docs/collector/internal-telemetry.md b/content/en/docs/collector/internal-telemetry.md index eb6807e1bbcb..b1ac672f868c 100644 --- a/content/en/docs/collector/internal-telemetry.md +++ b/content/en/docs/collector/internal-telemetry.md @@ -260,6 +260,53 @@ categorized by instrumentation type. | `rpc_server_response_size` | Measures the size of RPC response messages (uncompressed). | Histogram | | `rpc_server_responses_per_rpc` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. | Histogram | +### Telemetry lifecycle + +#### Tracing + +Tracing instrumentation is still under active development, and may change in a variety of ways. This includes span names, attached attributes, instrumented endpoints, etc. Until this feature graduates to stable, there are no guarantees of backwards compatibility for tracing instrumentation. + +#### Metrics + +The lifecycle of metrics in the Collector follows the following cycle, each stage is documented below: + +> Alpha metric → Stable metric → Deprecated metric → Deleted metric + +##### Alpha + +Alpha metrics have no stability guarantees. These metrics can be modified or deleted at any time. + +##### Stable + +Stable metrics are guaranteed to not change. This means: + +* A stable metric without a deprecated signature will not be deleted or renamed +* A stable metric's type and attributes will not be modified + +##### Deprecated + +Deprecated metrics are slated for deletion, but are still available for use. These metrics include an annotation about the version in which they became deprecated. For example: + + Before deprecation + + # HELP some_counter this counts things + # TYPE some_counter counter + otelcol_exporter_queue_size 0 + + After deprecation + + # HELP some_counter (Deprecated since 1.15.0) this counts things + # TYPE some_counter counter + some_counter 0 + +##### Deleted + +Deleted metrics are no longer published and cannot be used. + +#### Logs + +Individual log entries and their formatting may change from one release to the next, there are no stability guarantees at this time. + ### Events observable with internal logs The Collector logs the following internal events: From 29aa93cac57578595f7d117cc5a893c13079a1dd Mon Sep 17 00:00:00 2001 From: Alex Boten <223565+codeboten@users.noreply.github.com> Date: Thu, 22 Aug 2024 15:55:57 -0700 Subject: [PATCH 2/8] Apply suggestions from code review Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com> --- content/en/docs/collector/internal-telemetry.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/content/en/docs/collector/internal-telemetry.md b/content/en/docs/collector/internal-telemetry.md index b1ac672f868c..6c5b8f703200 100644 --- a/content/en/docs/collector/internal-telemetry.md +++ b/content/en/docs/collector/internal-telemetry.md @@ -264,11 +264,11 @@ categorized by instrumentation type. #### Tracing -Tracing instrumentation is still under active development, and may change in a variety of ways. This includes span names, attached attributes, instrumented endpoints, etc. Until this feature graduates to stable, there are no guarantees of backwards compatibility for tracing instrumentation. +Tracing instrumentation is still under active development, and changes might be made to span names, attached attributes, instrumented endpoints, or other aspects of the telemetry. Until this feature graduates to stable, there are no guarantees of backwards compatibility for tracing instrumentation. #### Metrics -The lifecycle of metrics in the Collector follows the following cycle, each stage is documented below: +The Collector's metrics follow a four-stage lifecycle: > Alpha metric → Stable metric → Deprecated metric → Deleted metric @@ -280,12 +280,12 @@ Alpha metrics have no stability guarantees. These metrics can be modified or del Stable metrics are guaranteed to not change. This means: -* A stable metric without a deprecated signature will not be deleted or renamed -* A stable metric's type and attributes will not be modified +- A stable metric without a deprecated signature will not be deleted or renamed. +- A stable metric's type and attributes will not be modified. ##### Deprecated -Deprecated metrics are slated for deletion, but are still available for use. These metrics include an annotation about the version in which they became deprecated. For example: +Deprecated metrics are slated for deletion but are still available for use. These metrics include an annotation about the version in which they became deprecated. For example: Before deprecation @@ -305,7 +305,7 @@ Deleted metrics are no longer published and cannot be used. #### Logs -Individual log entries and their formatting may change from one release to the next, there are no stability guarantees at this time. +Individual log entries and their formatting might change from one release to the next. There are no stability guarantees at this time. ### Events observable with internal logs From 66da88a7d520dfa8d640178fb324776e669cedfb Mon Sep 17 00:00:00 2001 From: Alex Boten <223565+codeboten@users.noreply.github.com> Date: Mon, 9 Sep 2024 08:57:39 -0700 Subject: [PATCH 3/8] Update content/en/docs/collector/internal-telemetry.md Co-authored-by: Patrice Chalin --- content/en/docs/collector/internal-telemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/collector/internal-telemetry.md b/content/en/docs/collector/internal-telemetry.md index 6c5b8f703200..47b146893786 100644 --- a/content/en/docs/collector/internal-telemetry.md +++ b/content/en/docs/collector/internal-telemetry.md @@ -260,7 +260,7 @@ categorized by instrumentation type. | `rpc_server_response_size` | Measures the size of RPC response messages (uncompressed). | Histogram | | `rpc_server_responses_per_rpc` | Measures the number of messages sent per RPC. Should be 1 for all non-streaming RPCs. | Histogram | -### Telemetry lifecycle +### Telemetry maturity levels #### Tracing From 351c83f0c8999d4bc89233e9bdb278f60cd244ab Mon Sep 17 00:00:00 2001 From: Alex Boten <223565+codeboten@users.noreply.github.com> Date: Mon, 9 Sep 2024 08:58:43 -0700 Subject: [PATCH 4/8] Update content/en/docs/collector/internal-telemetry.md Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com> --- content/en/docs/collector/internal-telemetry.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/content/en/docs/collector/internal-telemetry.md b/content/en/docs/collector/internal-telemetry.md index 47b146893786..2ca85732689f 100644 --- a/content/en/docs/collector/internal-telemetry.md +++ b/content/en/docs/collector/internal-telemetry.md @@ -287,17 +287,12 @@ Stable metrics are guaranteed to not change. This means: Deprecated metrics are slated for deletion but are still available for use. These metrics include an annotation about the version in which they became deprecated. For example: - Before deprecation +Before deprecation: - # HELP some_counter this counts things - # TYPE some_counter counter - otelcol_exporter_queue_size 0 - - After deprecation - - # HELP some_counter (Deprecated since 1.15.0) this counts things - # TYPE some_counter counter - some_counter 0 +```sh +# HELP some_counter this counts things +# TYPE some_counter counter +otelcol_exporter_queue_size 0 ##### Deleted From 0938d3391c4eb8a8ec2d37bb899922f436e404b6 Mon Sep 17 00:00:00 2001 From: Alex Boten <223565+codeboten@users.noreply.github.com> Date: Mon, 9 Sep 2024 09:01:07 -0700 Subject: [PATCH 5/8] Update internal-telemetry.md --- content/en/docs/collector/internal-telemetry.md | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/content/en/docs/collector/internal-telemetry.md b/content/en/docs/collector/internal-telemetry.md index 2ca85732689f..4a2a3534f7a4 100644 --- a/content/en/docs/collector/internal-telemetry.md +++ b/content/en/docs/collector/internal-telemetry.md @@ -290,9 +290,18 @@ Deprecated metrics are slated for deletion but are still available for use. Thes Before deprecation: ```sh -# HELP some_counter this counts things -# TYPE some_counter counter +# HELP otelcol_exporter_queue_size this counts things +# TYPE otelcol_exporter_queue_size counter otelcol_exporter_queue_size 0 +``` + +After deprecation: + +```sh +# HELP otelcol_exporter_queue_size (Deprecated since 1.15.0) this counts things +# TYPE otelcol_exporter_queue_size counter +otelcol_exporter_queue_size 0 +``` ##### Deleted From f8a645d0f47432b79519b0c0c34de42a68dfa042 Mon Sep 17 00:00:00 2001 From: Alex Boten <223565+codeboten@users.noreply.github.com> Date: Tue, 10 Sep 2024 13:55:45 -0700 Subject: [PATCH 6/8] Update content/en/docs/collector/internal-telemetry.md Co-authored-by: Tiffany Hrabusa <30397949+tiffany76@users.noreply.github.com> --- content/en/docs/collector/internal-telemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/collector/internal-telemetry.md b/content/en/docs/collector/internal-telemetry.md index 4a2a3534f7a4..d2a1fd942503 100644 --- a/content/en/docs/collector/internal-telemetry.md +++ b/content/en/docs/collector/internal-telemetry.md @@ -262,7 +262,7 @@ categorized by instrumentation type. ### Telemetry maturity levels -#### Tracing +#### Traces Tracing instrumentation is still under active development, and changes might be made to span names, attached attributes, instrumented endpoints, or other aspects of the telemetry. Until this feature graduates to stable, there are no guarantees of backwards compatibility for tracing instrumentation. From d0bcda0b45c72a977ba190ae99dc502f3f96b628 Mon Sep 17 00:00:00 2001 From: Alex Boten <223565+codeboten@users.noreply.github.com> Date: Wed, 11 Sep 2024 11:32:47 -0700 Subject: [PATCH 7/8] Update content/en/docs/collector/internal-telemetry.md --- content/en/docs/collector/internal-telemetry.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/docs/collector/internal-telemetry.md b/content/en/docs/collector/internal-telemetry.md index d2a1fd942503..5ddfe0d9bc94 100644 --- a/content/en/docs/collector/internal-telemetry.md +++ b/content/en/docs/collector/internal-telemetry.md @@ -285,7 +285,7 @@ Stable metrics are guaranteed to not change. This means: ##### Deprecated -Deprecated metrics are slated for deletion but are still available for use. These metrics include an annotation about the version in which they became deprecated. For example: +Deprecated metrics are slated for deletion but are still available for use. The description of these metrics include an annotation about the version in which they became deprecated. For example: Before deprecation: From 89829840ef3d5e9d48459a9896293c7d279a58c7 Mon Sep 17 00:00:00 2001 From: opentelemetrybot <107717825+opentelemetrybot@users.noreply.github.com> Date: Tue, 17 Sep 2024 23:14:32 +0000 Subject: [PATCH 8/8] Results from /fix:format --- content/en/docs/collector/internal-telemetry.md | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/content/en/docs/collector/internal-telemetry.md b/content/en/docs/collector/internal-telemetry.md index 01998f9e6218..6a352e8c5299 100644 --- a/content/en/docs/collector/internal-telemetry.md +++ b/content/en/docs/collector/internal-telemetry.md @@ -276,7 +276,10 @@ libraries. {{% /alert %}} #### Traces -Tracing instrumentation is still under active development, and changes might be made to span names, attached attributes, instrumented endpoints, or other aspects of the telemetry. Until this feature graduates to stable, there are no guarantees of backwards compatibility for tracing instrumentation. +Tracing instrumentation is still under active development, and changes might be +made to span names, attached attributes, instrumented endpoints, or other +aspects of the telemetry. Until this feature graduates to stable, there are no +guarantees of backwards compatibility for tracing instrumentation. #### Metrics @@ -286,7 +289,8 @@ The Collector's metrics follow a four-stage lifecycle: ##### Alpha -Alpha metrics have no stability guarantees. These metrics can be modified or deleted at any time. +Alpha metrics have no stability guarantees. These metrics can be modified or +deleted at any time. ##### Stable @@ -297,7 +301,9 @@ Stable metrics are guaranteed to not change. This means: ##### Deprecated -Deprecated metrics are slated for deletion but are still available for use. The description of these metrics include an annotation about the version in which they became deprecated. For example: +Deprecated metrics are slated for deletion but are still available for use. The +description of these metrics include an annotation about the version in which +they became deprecated. For example: Before deprecation: @@ -321,7 +327,8 @@ Deleted metrics are no longer published and cannot be used. #### Logs -Individual log entries and their formatting might change from one release to the next. There are no stability guarantees at this time. +Individual log entries and their formatting might change from one release to the +next. There are no stability guarantees at this time. ### Events observable with internal logs