From 4676115f6ab1f964f7008f602ae6ea5ac55ef1d2 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 19 Dec 2024 17:44:45 -0800 Subject: [PATCH] random doc fixes --- CONTRIBUTING.md | 36 +++++++++++-------- Makefile | 2 +- docs/attributes-registry/README.md | 5 +-- docs/gen-ai/gen-ai-events.md | 5 --- ...ility.md => semantic-convention-groups.md} | 0 model/README.md | 28 ++++++++++++--- templates/registry/markdown/readme.md.j2 | 5 +-- 7 files changed, 53 insertions(+), 28 deletions(-) rename docs/general/{group-stability.md => semantic-convention-groups.md} (100%) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4cfc04991c..a387fb97ac 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -106,6 +106,8 @@ The YAML (model definition) and Markdown (documentation) files are organized in │ │ ├── ....md ├── model │ ├── {root-namespace} +│ │ ├── deprecated +│ │ | ├── registry-deprecated.yaml │ │ ├── events.yaml │ │ ├── metrics.yaml │ │ ├── registry.yaml @@ -126,6 +128,9 @@ HTTP spans are defined in `model/http/spans.yaml`. YAML definitions could be broken down into multiple files. For example, AWS spans are defined in `/model/aws/lambda-spans.yaml` and `/model/aws/sdk-spans.yaml` files. +Deprecated conventions should be placed under `/model/{root-namespace}/deprecated` +folder. + #### Schema files When making changes to existing semantic conventions (attributes, metrics, etc) @@ -137,6 +142,7 @@ For details, please read You can also take examples from past changes inside the `schemas` folder. > [!WARNING] +> > DO NOT add your changes to files inside the `schemas` folder. Always add your > changes to the `schema-next.yaml` file. @@ -167,7 +173,21 @@ When creating new markdown files, you should provide the `linkTitle` attribute. This is used to generate the navigation bar on the website, and will be listed relative to the "parent" document. -### 3. Verify the changes before committing +### 4. Check new convention + +Semantic conventions are validated for name formatting and backward compatibility with last released versions. +Here's [the full list of compatibility checks](./policies/compatibility.rego). + +Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead. +It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes. + +You can run backward compatibility check (along with other policies) in all yaml files with the following command: + +```bash +make check-policies +``` + +### 5. Verify the changes before committing Before sending a PR with your changes, make sure to run the automated checks: @@ -178,7 +198,7 @@ make check Alternatively, you can run each check individually. Refer to the [Automation](#automation) section for more details. -### 4. Changelog +### 6. Changelog #### When to add a Changelog Entry @@ -341,18 +361,6 @@ To check the validity of links in all markdown files, run the following command: make markdown-link-check ``` -### Version compatibility check - -Semantic conventions are validated for backward compatibility with last released versions. Here's [the full list of compatibility checks](./policies/compatibility.rego). -Removing attributes, metrics, or enum members is not allowed, they should be deprecated instead. -It applies to stable and experimental conventions and prevents semantic conventions auto-generated libraries from introducing breaking changes. - -You can run backward compatibility check (along with other policies) in all yaml files with the following command: - -```bash -make check-policies -``` - ## Updating the referenced specification version 1. Open the `./internal/tools/update_specification_version.sh` script. diff --git a/Makefile b/Makefile index 6f2cf5c809..e4ed069ccc 100644 --- a/Makefile +++ b/Makefile @@ -183,7 +183,7 @@ fix-format: # Run all checks in order of speed / likely failure. # As a last thing, run attribute registry generation and git-diff for differences. .PHONY: check -check: misspell markdownlint check-format markdown-toc compatibility-check markdown-link-check check-policies attribute-registry-generation +check: misspell markdownlint check-format markdown-toc markdown-link-check check-policies attribute-registry-generation git diff --exit-code ':*.md' || (echo 'Generated markdown Table of Contents is out of date, please run "make markdown-toc" and commit the changes in this PR.' && exit 1) @echo "All checks complete" diff --git a/docs/attributes-registry/README.md b/docs/attributes-registry/README.md index 4bfe974911..f8be3b149a 100644 --- a/docs/attributes-registry/README.md +++ b/docs/attributes-registry/README.md @@ -16,7 +16,7 @@ The attributes registry is the place where attributes are defined. An attribute - a `brief` description of the attribute and optionally a longer `note` - example values -Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. +Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id`, `type`, and `stability` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions. @@ -24,7 +24,8 @@ If applicable, application developers are encouraged to use existing attributes All registered attributes are listed by namespace in this registry. -> **Warning** +> [!WARNING] +> > The following registry overview is a work in progress. > > Further attribute namespaces are currently being migrated and will appear in this registry soon. diff --git a/docs/gen-ai/gen-ai-events.md b/docs/gen-ai/gen-ai-events.md index cc77890c73..e7fa7c0beb 100644 --- a/docs/gen-ai/gen-ai-events.md +++ b/docs/gen-ai/gen-ai-events.md @@ -25,13 +25,8 @@ linkTitle: Generative AI events GenAI instrumentations MAY capture user inputs sent to the model and responses received from it as [events](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/specification/logs/api.md#emit-an-event). -<<<<<<< HEAD -> [!NOTE] -> Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix.md#events) to see the implementation status in corresponding language. -======= > Note: > Event API is experimental and not yet available in some languages. Check [spec-compliance matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.40.0/spec-compliance-matrix.md#logs) to see the implementation status in corresponding language. ->>>>>>> 75746bc9 (reword) Instrumentations MAY capture inputs and outputs if and only if application has enabled the collection of this data. This is for three primary reasons: diff --git a/docs/general/group-stability.md b/docs/general/semantic-convention-groups.md similarity index 100% rename from docs/general/group-stability.md rename to docs/general/semantic-convention-groups.md diff --git a/model/README.md b/model/README.md index 821423416e..fd1b22e4ea 100644 --- a/model/README.md +++ b/model/README.md @@ -4,8 +4,10 @@ The YAML descriptions of semantic convention contained in this directory are int be used by the various OpenTelemetry language implementations to aid in automatic generation of semantics-related code. -⚠ If you want to read the semantic conventions and not edit them, please see -the generated markdown output in the [docs](../docs/README.md) folder. +> [!NOTE] +> +> If you want to read the semantic conventions and not edit them, please see +> the generated markdown output in the [docs](../docs/README.md) folder. ## Writing semantic conventions @@ -21,18 +23,36 @@ A schema file for VS code is configured in the `/.vscode/settings.json` of this repository, enabling auto-completion and additional checks. Refer to [the generator README](https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md) for what extension you need. +When defining semantic conventions, follow [contributing guide](/CONTRIBUTING.md#1-modify-the-yaml-model): + +- If new attributes are necessary, define them in the [attribute registry](/docs/attributes-registry/README.md). + Attributes can only be defined inside groups with `attribute_group` type and with `id` starting with `registry.` prefix. +- Define new spans, metrics, events, resources, and other conventions using appropriate group type. See + [semantic convention groups](/docs/general/semantic-convention-groups.md) for more details. + ## Generating markdown -These YAML files are used by the make target `table-generation` to generate consistently +These YAML files are used by the make targets `attribute-registry-generation` and `table-generation` to generate consistently formatted Markdown tables for all semantic conventions in the specification. Run it from the root of this repository using the command ``` -make table-generation +make attribute-registry-generation table-generation ``` For more information, see the [Weaver](https://github.com/open-telemetry/weaver) as our code generations tool. +## Validating semantic conventions + +Semantic conventions YAML files are validated by `check-policies` make target for backward compatibility, +name formatting, and other policies. + +You can run it with the following command: + +``` +make check-policies +``` + See also: * [Markdown Templates](../templates/registry/markdown) diff --git a/templates/registry/markdown/readme.md.j2 b/templates/registry/markdown/readme.md.j2 index 1767f38b2e..ab36d57be8 100644 --- a/templates/registry/markdown/readme.md.j2 +++ b/templates/registry/markdown/readme.md.j2 @@ -17,7 +17,7 @@ The attributes registry is the place where attributes are defined. An attribute - a `brief` description of the attribute and optionally a longer `note` - example values -Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id` and `type` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. +Attributes defined in the registry can be used in different semantic conventions. Attributes should be included in this registry before they are used in semantic conventions. Semantic conventions may override all the properties of an attribute except for the `id`, `type` and `stability` in case it's required for a particular context. In addition, semantic conventions specify the requirement level of an attribute in the corresponding context. A definition of an attribute in the registry doesn't necessarily imply that the attribute is used in any of the semantic conventions. @@ -25,7 +25,8 @@ If applicable, application developers are encouraged to use existing attributes All registered attributes are listed by namespace in this registry. -> **Warning** +> [!WARNING] +> > The following registry overview is a work in progress. > > Further attribute namespaces are currently being migrated and will appear in this registry soon.