Renamed specification and semantic_conventions directories for more clarity

.github/CODEOWNERS

@@ -20,19 +20,19 @@
 /internal/tools/schema_check.sh @open-telemetry/specs-semconv-approvers @tigrannajaryan
 
 # Logs semantic conventions
-/semantic_conventions/logs/                        @open-telemetry/specs-semconv-approvers @tigrannajaryan
-/specification/exceptions/exceptions-logs.md       @open-telemetry/specs-semconv-approvers @tigrannajaryan
-/specification/feature-flags/feature-flags-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan
-/specification/general/events-general.md           @open-telemetry/specs-semconv-approvers @tigrannajaryan
-/specification/general/logs-general.md             @open-telemetry/specs-semconv-approvers @tigrannajaryan
-/specification/logs/                               @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/model/logs/                        @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/semantic_conventions/exceptions/exceptions-logs.md       @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/semantic_conventions/feature-flags/feature-flags-logs.md @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/semantic_conventions/general/events-general.md           @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/semantic_conventions/general/logs-general.md             @open-telemetry/specs-semconv-approvers @tigrannajaryan
+/semantic_conventions/logs/                               @open-telemetry/specs-semconv-approvers @tigrannajaryan
 
 # JVM semantic conventions approvers
-/semantic_conventions/metrics/process-runtime-jvm-metrics.yaml              @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers
-/semantic_conventions/metrics/process-runtime-jvm-metrics-experimental.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers
+/model/metrics/process-runtime-jvm-metrics.yaml              @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers
+/model/metrics/process-runtime-jvm-metrics-experimental.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-jvm-approvers
 
 # HTTP semantic conventions approvers
-/semantic_conventions/metrics/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
-/semantic_conventions/trace/http.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
+/model/metrics/http.yaml @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
+/model/trace/http.yaml   @open-telemetry/specs-semconv-approvers @open-telemetry/semconv-http-approvers
 
 # TODO - Add semconv area experts

CONTRIBUTING.md

@@ -53,7 +53,7 @@ See:
 ### YAML to Markdown
 
 Semantic conventions are declared in YAML files and markdown tables are
-generated from these files. Read about semantic convention updates [here](./semantic_conventions/README.md).
+generated from these files. Read about semantic convention updates [here](./model/README.md).
 
 ### Autoformatting
 

Makefile

@@ -7,7 +7,7 @@ MISSPELL_BINARY=bin/misspell
 MISSPELL = $(TOOLS_DIR)/$(MISSPELL_BINARY)
 
 # see https://github.com/open-telemetry/build-tools/releases for semconvgen updates
-# Keep links in semantic_conventions/README.md and .vscode/settings.json in sync!
+# Keep links in model/README.md and .vscode/settings.json in sync!
 SEMCONVGEN_VERSION=0.18.0
 
 # TODO: add `yamllint` step to `all` after making sure it works on Mac.
@@ -74,13 +74,13 @@ yamllint:
 # Generate markdown tables from YAML definitions
 .PHONY: table-generation
 table-generation:
-	docker run --rm -v $(PWD)/semantic_conventions:/source -v $(PWD)/specification:/spec \
+	docker run --rm -v $(PWD)/model:/source -v $(PWD)/specification:/spec \
 		otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec
 
 # Check if current markdown tables differ from the ones that would be generated from YAML definitions
 .PHONY: table-check
 table-check:
-	docker run --rm -v $(PWD)/semantic_conventions:/source -v $(PWD)/specification:/spec \
+	docker run --rm -v $(PWD)/model:/source -v $(PWD)/specification:/spec \
 		otel/semconvgen:$(SEMCONVGEN_VERSION) -f /source markdown -md /spec --md-check
 
 .PHONY: schema-check

README.md

@@ -9,7 +9,7 @@ This repository is currently using [this specification version][SpecificationVer
 
 ## Read the docs
 
-The documentation currently resides in the [specification](specification/README.md) folder.
+The documentation currently resides in the [semantic_conventions](semantic_conventions/README.md) folder.
 
 ## TODOs
 

internal/tools/update_specification_version.sh

@@ -22,7 +22,7 @@ fix_file() {
    "$1"
 }
 
-important_files=("specification" "semantic_conventions" "README.md" "supplementary-guidelines")
+important_files=("specification" "model" "README.md" "supplementary-guidelines")
 
 # TODO - limit to markdown/yaml files?
 find "${important_files[@]}" -type f -not -path '*/.*' -print0 | while read -d $'\0' file; do

model/README.md

@@ -0,0 +1,41 @@
+# YAML Model for Semantic Conventions
+
+The YAML descriptions of semantic convention contained in this directory are intended to
+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 [semantic_conventions](../semantic_conventions/README.md) folder.
+
+## Writing semantic conventions
+
+Semantic conventions for the spec MUST adhere to the
+[attribute naming](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/common/attribute-naming.md),
+[attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/common/attribute-requirement-level.md),
+and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/metric-requirement-level.md) conventions.
+
+Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions/syntax.md)
+for how to write the YAML files for semantic conventions and what the YAML properties mean.
+
+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/build-tools/tree/v0.18.0/semantic-conventions/README.md) for what extension you need.
+
+## Generating markdown
+
+These YAML files are used by the make target `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
+```
+
+For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions)
+in the OpenTelemetry build tools repository.
+Using this build tool, it is also possible to generate code for use in OpenTelemetry
+language projects.
+
+See also:
+
+* [Markdown Tables](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions#markdown-tables)
+* [Code Generator](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions#code-generator)

semantic_conventions/http-common.yaml → model/http-common.yaml

@@ -111,14 +111,14 @@ groups:
         note: >
           MUST NOT be populated when this is not supported by the HTTP server framework as the route attribute should have low-cardinality and the URI path can NOT substitute it.
 
-          SHOULD include the [application root](/specification/http/http-spans.md#http-server-definitions) if there is one.
+          SHOULD include the [application root](/semantic_conventions/http/http-spans.md#http-server-definitions) if there is one.
       - ref: server.address
         brief: >
           Name of the local HTTP server that received the request.
         note: |
           Determined by using the first of the following that applies
 
-          - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
+          - The [primary server name](/semantic_conventions/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
             include host identifier.
           - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
@@ -132,7 +132,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host.
+          - Port identifier of the [primary server host](/semantic_conventions/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header

semantic_conventions/metrics/http.yaml → model/metrics/http.yaml

@@ -11,7 +11,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
+          - The [primary server name](/semantic_conventions/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
             include host identifier.
           - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
@@ -26,7 +26,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host.
+          - Port identifier of the [primary server host](/semantic_conventions/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header
@@ -74,7 +74,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
+          - The [primary server name](/semantic_conventions/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
             include host identifier.
           - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
@@ -89,7 +89,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host.
+          - Port identifier of the [primary server host](/semantic_conventions/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header

semantic_conventions/resource/faas.yaml → model/resource/faas.yaml

@@ -14,7 +14,7 @@ groups:
           This is the name of the function as configured/deployed on the FaaS
           platform and is usually different from the name of the callback
           function (which may be stored in the
-          [`code.namespace`/`code.function`](/specification/general/general-attributes.md#source-code-attributes)
+          [`code.namespace`/`code.function`](/semantic_conventions/general/general-attributes.md#source-code-attributes)
           span attributes).
 
           For some cloud providers, the above definition is ambiguous. The following

semantic_conventions/resource/os.yaml → model/resource/os.yaml

@@ -61,5 +61,5 @@ groups:
         type: string
         brief: >
           The version string of the operating system as defined in
-          [Version Attributes](/specification/resource/README.md#version-attributes).
+          [Version Attributes](/semantic_conventions/resource/README.md#version-attributes).
         examples: ['14.2.1', '18.04.1']

semantic_conventions/trace/general.yaml → model/trace/general.yaml

@@ -170,7 +170,7 @@ groups:
       - id: service
         type: string
         brief: >
-          The [`service.name`](/specification/resource/README.md#service)
+          The [`service.name`](/semantic_conventions/resource/README.md#service)
           of the remote service. SHOULD be equal to the actual `service.name`
           resource attribute of the remote service if any.
         examples: "AuthTokenCache"

semantic_conventions/trace/http.yaml → model/trace/http.yaml

@@ -100,7 +100,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - The [primary server name](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
+          - The [primary server name](/semantic_conventions/http/http-spans.md#http-server-definitions) of the matched virtual host. MUST only
             include host identifier.
           - Host identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
@@ -116,7 +116,7 @@ groups:
         note: |
           Determined by using the first of the following that applies
 
-          - Port identifier of the [primary server host](/specification/http/http-spans.md#http-server-definitions) of the matched virtual host.
+          - Port identifier of the [primary server host](/semantic_conventions/http/http-spans.md#http-server-definitions) of the matched virtual host.
           - Port identifier of the [request target](https://www.rfc-editor.org/rfc/rfc9110.html#target.resource)
             if it's sent in absolute-form.
           - Port identifier of the `Host` header

semantic_conventions/README.md

@@ -1,41 +1,28 @@
-# YAML Model for Semantic Conventions
-
-The YAML descriptions of semantic convention contained in this directory are intended to
-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 [specification](../specification/README.md) folder.
-
-## Writing semantic conventions
-
-Semantic conventions for the spec MUST adhere to the
-[attribute naming](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/common/attribute-naming.md),
-[attribute requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/common/attribute-requirement-level.md),
-and [metric requirement level](https://github.com/open-telemetry/opentelemetry-specification/tree/v1.21.0/specification/metrics/metric-requirement-level.md) conventions.
-
-Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions/syntax.md)
-for how to write the YAML files for semantic conventions and what the YAML properties mean.
-
-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/build-tools/tree/v0.18.0/semantic-conventions/README.md) for what extension you need.
-
-## Generating markdown
-
-These YAML files are used by the make target `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
-```
-
-For more information, see the [semantic convention generator](https://github.com/open-telemetry/build-tools/tree/v0.18.0/semantic-conventions)
-in the OpenTelemetry build tools repository.
-Using this build tool, it is also possible to generate code for use in OpenTelemetry
-language projects.
-
-See also:
-
-* [Markdown Tables](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions#markdown-tables)
-* [Code Generator](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions#code-generator)
+# OpenTelemetry Semantic Conventions
+
+The Semantic Conventions define a common set of (semantic) attributes which provide meaning to data when collecting, producing and consuming it.
+The Semantic Conventions specify among other things span names and kind, metric instruments and units as well as attribute names, types, meaning and valid values. For a detailed definition of the Semantic Conventions' scope see [Semantic Conventions Stability](https://opentelemetry.io/docs/specs/otel/versioning-and-stability/#semantic-conventions-stability).
+The benefit to using Semantic Conventions is in following a common naming scheme that can be standardized across a codebase, libraries, and platforms. This allows easier correlation and consumption of data.
+
+Semantic Conventions are defined for the following areas:
+
+* **[General](general/README.md): General Semantic Conventions**.
+* [CloudEvents](cloudevents/README.md): Semantic Conventions for the CloudEvents specification.
+* [Cloud Providers](cloud-providers/README.md): Semantic Conventions for cloud providers libraries.
+* [Database](database/README.md): Semantic Conventions for database operations.
+* [Exceptions](exceptions/README.md): Semantic Conventions for exceptions.
+* [FaaS](faas/README.md): Semantic Conventions for Function as a Service (FaaS) operations.
+* [Feature Flags](http/README.md): Semantic Conventions for feature flag evaluations.
+* [HTTP](feature-flags/README.md): Semantic Conventions for HTTP client and server operations.
+* [Messaging](messaging/README.md): Semantic Conventions for messaging operations and systems.
+* [Object Stores](object-stores/README.md): Semantic Conventions for object stores operations.
+* [RPC](rpc/README.md): Semantic Conventions for RPC client and server operations.
+* [System](system/README.md): System Semantic Conventions.
+
+Semantic Conventions by signals:
+
+* [Events](general/events-general.md): Semantic Conventions for event data.
+* [Logs](general/logs-general.md): Semantic Conventions for logs data.
+* [Metrics](general/metrics-general.md): Semantic Conventions for metrics.
+* [Resource](resource/README.md): Semantic Conventions for resources.
+* [Trace](general/trace-general.md): Semantic Conventions for traces and spans.

specification/cloud-providers/aws-sdk.md → semantic_conventions/cloud-providers/aws-sdk.md

@@ -36,7 +36,7 @@ with the naming guidelines for RPC client spans.
 
 The following Semantic Conventions extend the general AWS SDK attributes for specific AWS services:
 
-* [AWS DynamoDB](/specification/database/dynamodb.md): Semantic Conventions for *AWS DynamoDB*.
-* [AWS S3](/specification/object-stores/s3.md): Semantic Conventions for *AWS S3*.
+* [AWS DynamoDB](/semantic_conventions/database/dynamodb.md): Semantic Conventions for *AWS DynamoDB*.
+* [AWS S3](/semantic_conventions/object-stores/s3.md): Semantic Conventions for *AWS S3*.
 
 [DocumentStatus]: https://github.com/open-telemetry/opentelemetry-specification/blob/v1.21.0/specification/document-status.md