From de25ecbbffdcd01f44692a9209beb953eda7b7f2 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Mon, 29 Jul 2024 04:06:52 -0400 Subject: [PATCH] [editorial] Move supplementary-guidelines into docs (#1284) Signed-off-by: Patrice Chalin --- docs/README.md | 2 ++ docs/cloud-providers/aws-sdk.md | 2 +- docs/faas/aws-lambda.md | 4 ++-- docs/general/attributes.md | 2 +- docs/general/events.md | 2 +- docs/general/logs.md | 2 +- docs/general/metrics.md | 2 +- docs/non-normative/README.md | 11 +++++++++++ docs/non-normative/compatibility/README.md | 7 +++++++ .../non-normative}/compatibility/aws.md | 6 +++++- .../http-migration.md} | 9 +++++++-- .../non-normative/libraries.md | 7 ++++++- internal/tools/update_specification_version.sh | 2 +- 13 files changed, 46 insertions(+), 12 deletions(-) create mode 100644 docs/non-normative/README.md create mode 100644 docs/non-normative/compatibility/README.md rename {supplementary-guidelines => docs/non-normative}/compatibility/aws.md (93%) rename docs/{http/migration-guide.md => non-normative/http-migration.md} (98%) rename supplementary-guidelines/semantic_conventions_code_generation.md => docs/non-normative/libraries.md (93%) diff --git a/docs/README.md b/docs/README.md index 27c2c200a0..f31cc91fa5 100644 --- 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/cloud-providers/aws-sdk.md b/docs/cloud-providers/aws-sdk.md index 84e003d360..c9857d47fb 100644 --- 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 index 4ed35e73f9..b36fde656a 100644 --- 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 index 895fbe8e4e..cb3f3360ca 100644 --- a/docs/general/attributes.md +++ b/docs/general/attributes.md @@ -1,6 +1,6 @@ # General Attributes diff --git a/docs/general/events.md b/docs/general/events.md index f86dda708f..87460baae5 100644 --- a/docs/general/events.md +++ b/docs/general/events.md @@ -1,6 +1,6 @@ # Semantic Conventions for Events diff --git a/docs/general/logs.md b/docs/general/logs.md index b48b379edd..24ead6f931 100644 --- a/docs/general/logs.md +++ b/docs/general/logs.md @@ -1,6 +1,6 @@ # General Logs Attributes diff --git a/docs/general/metrics.md b/docs/general/metrics.md index 09892e5fc0..3c9740a478 100644 --- a/docs/general/metrics.md +++ b/docs/general/metrics.md @@ -1,6 +1,6 @@ # Metrics Semantic Conventions diff --git a/docs/non-normative/README.md b/docs/non-normative/README.md new file mode 100644 index 0000000000..c51419111d --- /dev/null +++ b/docs/non-normative/README.md @@ -0,0 +1,11 @@ + + +# 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 new file mode 100644 index 0000000000..fa1af86c8e --- /dev/null +++ b/docs/non-normative/compatibility/README.md @@ -0,0 +1,7 @@ + + +# Compatibility diff --git a/supplementary-guidelines/compatibility/aws.md b/docs/non-normative/compatibility/aws.md similarity index 93% rename from supplementary-guidelines/compatibility/aws.md rename to docs/non-normative/compatibility/aws.md index 3777cb22a9..e40a7cc1aa 100644 --- a/supplementary-guidelines/compatibility/aws.md +++ b/docs/non-normative/compatibility/aws.md @@ -1,6 +1,10 @@ + + # 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 b/docs/non-normative/http-migration.md similarity index 98% rename from docs/http/migration-guide.md rename to docs/non-normative/http-migration.md index 65fea1a3fe..d0c70fe68f 100644 --- a/docs/http/migration-guide.md +++ b/docs/non-normative/http-migration.md @@ -1,4 +1,9 @@ -# HTTP semantic convention stability 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/supplementary-guidelines/semantic_conventions_code_generation.md b/docs/non-normative/libraries.md similarity index 93% rename from supplementary-guidelines/semantic_conventions_code_generation.md rename to docs/non-normative/libraries.md index 76436fed77..320627ed3e 100644 --- a/supplementary-guidelines/semantic_conventions_code_generation.md +++ b/docs/non-normative/libraries.md @@ -1,3 +1,8 @@ + + # Semantic convention libraries @@ -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/internal/tools/update_specification_version.sh b/internal/tools/update_specification_version.sh index 34af42f446..c5a8387f1a 100755 --- 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