From 549eefb8ca14934eea98a7cbf43f2df23a7696c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 22 Jul 2021 17:43:14 +0200 Subject: [PATCH 1/3] Move syntax.md to build-tools, improve semconv README. --- .vscode/settings.json | 6 + semantic_conventions/README.md | 15 ++- semantic_conventions/syntax.md | 235 --------------------------------- 3 files changed, 20 insertions(+), 236 deletions(-) delete mode 100644 semantic_conventions/syntax.md diff --git a/.vscode/settings.json b/.vscode/settings.json index d1289e8e72e..77fab00c653 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -9,4 +9,10 @@ "MD033": false, "MD040": false, }, + "yaml.schemas": { + "https://raw.githubusercontent.com/open-telemetry/build-tools/main/semantic-conventions/semconv.schema.json": [ + "semantic_conventions/**/*.yaml" + ] + }, + "json.schemaDownload.enable": true } diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index cd4523ff8ee..75f0c9348c3 100644 --- a/semantic_conventions/README.md +++ b/semantic_conventions/README.md @@ -4,9 +4,22 @@ 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 under `/specification/*/semantic_conventions/`, +i.e.: + +* [Trace semantic conventions](../specification/trace/semantic_conventions/README.md) +* [Metric semantic conventions](../specification/metrics/semantic_conventions/README.md) +* [Resource semantic conventions](../specification/resource/semantic_conventions/README.md) + ## Writing semantic conventions -Refer to the [syntax](./syntax.md) for how to write the YAML files for semantic conventions. +Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions/syntax.md) +for how to write the YAML files for semantic conventions. + +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/main/semantic-conventions/README.md) for what extension you need. ## Generation diff --git a/semantic_conventions/syntax.md b/semantic_conventions/syntax.md deleted file mode 100644 index 49bad47e535..00000000000 --- a/semantic_conventions/syntax.md +++ /dev/null @@ -1,235 +0,0 @@ -# Semantic Convention YAML Language - -First, the syntax with a pseudo [EBNF](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form) grammar is presented. -Then, the semantic of each field is described. - -## Syntax - -All attributes are lower case. - -```bnf -groups ::= semconv - | semconv groups - -semconv ::= id brief [note] [prefix] [extends] [span_kind] attributes [constraints] - -id ::= string -brief ::= string -note ::= string - -prefix ::= string - -# extends MUST point to an existing semconv id -extends ::= string - -span_kind ::= "client" - | "server" - | "producer" - | "consumer" - | "internal" - -attributes ::= (id type brief examples | ref [brief] [examples]) [required] [note] - -# ref MUST point to an existing attribute id -ref ::= id - -type ::= "string" - | "int" - | "double" - | "boolean" - | "string[]" - | "int[]" - | "double[]" - | "boolean[]" - | enum - -enum ::= [allow_custom_values] members - -allow_custom_values := boolean - -members ::= member {member} - -member ::= id value [brief] [note] - -required ::= "always" - | "conditional" - -examples ::= {} - -constraints ::= constraint {constraint} - -constraint ::= any_of - | include - -any_of ::= id {id} - -include ::= id - -``` - -## Semantics - -### Groups - -Groups contain the list of semantic conventions and it is the root node of each yaml file. - -### Semantic Convention - -The field `semconv` represents a semantic convention and it is made by: - -- `id`, string that uniquely identifies the semantic convention. -- `brief`, string, a brief description of the semantic convention. -- `note`, optional string, a more elaborate description of the semantic convention. - It defaults to an empty string. -- `prefix`, optional string, prefix for the attributes for this semantic convention. - It defaults to an empty string. -- `extends`, optional string, reference another semantic convention `id`. - It inherits the prefix, constraints, and all attributes defined in the specified semantic convention. -- `span_kind`, optional enum, specifies the kind of the span. -- `attributes`, list of attributes that belong to the semantic convention. -- `constraints`, optional list, additional constraints (See later). It defaults to an empty list. - -### Attributes - -An attribute is defined by: - -- `id`, string that uniquely identifies the attribute. -- `type`, either a string literal denoting the type or an enum definition (See later). - The accepted string literals are: - - * "string": String attributes. - * "int": Integer attributes. - * "double": Double attributes. - * "boolean": Boolean attributes. - * "string[]": Array of strings attributes. - * "int[]": Array of integer attributes. - * "double[]": Array of double attributes. - * "boolean[]": Array of booleans attributes. - - See the [specification of Attributes](../specification/common/common.md#attributes) for the definition of the value types. -- `ref`, optional string, reference an existing attribute, see later. -- `required`, optional, specifies if the attribute is mandatory. - Can be "always", or "conditional". When omitted, the attribute is not required. - When set to "conditional",the string provided as `` MUST specify - the conditions under which the attribute is required. -- `brief`, string, brief description of the attribute. -- `note`, optional string, additional notes to the attribute. It defaults to an empty string. -- `examples`, sequence/dictionary of example values for the attribute. - They are optional for boolean and enum attributes. - Example values must be of the same type of the attribute. - If only a single example is provided, it can directly be reported without encapsulating it into a sequence/dictionary. - -Examples for setting the `examples` field: - -A single example value for a string attribute. All the following three representations are equivalent: - -```yaml -examples: 'this is a single string' -``` - -or - -```yaml -examples: ['this is a single string'] -``` - -or - -```yaml -examples: - - 'this is a single string' -``` - -Attention, the following will throw a type mismatch error because a string type as example value is expected and not an array of string: - -```yaml -examples: - - ['this is an error'] - -examples: [['this is an error']] -``` - -Multiple example values for a string attribute: - -```yaml -examples: ['this is a single string', 'this is another one'] -``` - -or - -```yaml -examples: - - 'this is a single string' - - 'this is another one' -``` - -A single example value for an array of strings attribute: - -```yaml -examples: ['first element of first array', 'second element of first array'] -``` - -or - -```yaml -examples: - - ['first element of first array', 'second element of first array'] -``` - -Attention, the following will throw a type mismatch error because an array of strings as type for the example values is expected and not a string: - -```yaml -examples: 'this is an error' -``` - -Multiple example values for an array of string attribute: - -```yaml -examples: [ ['first element of first array', 'second element of first array'], ['first element of second array', 'second element of second array'] ] -``` - -or - -```yaml -examples: - - ['first element of first array', 'second element of first array'] - - ['first element of second array', 'second element of second array'] -``` - -### Ref - -`ref` MUST have an id of an existing attribute. When it is set, `id` and `type` MUST NOT be present. -`ref` is useful for specifying that an existing attribute of another semantic convention is part of -the current semantic convention and inherit its `brief`, `note`, and `example` values. However, if these -fields are present in the current attribute definition, they override the inherited values. - -### Type - -An attribute type can either be a string, int, double, boolean, array of strings, array of int, array of double, -array of booleans, or an enumeration. If it is an enumeration, additional fields are required: - -- `allow_custom_values`, optional boolean, set to false to not accept values - other than the specified members. It defaults to `true`. -- `members`, list of enum entries. - -An enum entry has the following fields: - -- `id`, string that uniquely identifies the enum entry. -- `value`, string, int, or boolean; value of the enum entry. -- `brief`, optional string, brief description of the enum entry value. It defaults to the value of `id`. -- `note`, optional string, longer description. It defaults to an empty string. - -### Constraints - -Allow to define additional requirements on the semantic convention. -Currently, it supports `any_of` and `include`. - -#### Any Of - -`any_of` accepts a list of sequences. Each sequence contains a list of attribute ids that are required. -`any_of` enforces that all attributes of at least one of the sequences are set. - -#### Include - -`include` accepts a semantic conventions `id`. It includes as part of this semantic convention all constraints -and required attributes that are not already defined in the current semantic convention. From 6de7432799810af2ceec99e7d458b0f09a8056c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 22 Jul 2021 17:51:27 +0200 Subject: [PATCH 2/3] Fix leftover link to syntax.md, removing section. --- semantic_conventions/README.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/semantic_conventions/README.md b/semantic_conventions/README.md index 75f0c9348c3..db57d1a3c49 100644 --- a/semantic_conventions/README.md +++ b/semantic_conventions/README.md @@ -15,7 +15,7 @@ i.e.: ## Writing semantic conventions Refer to the [syntax](https://github.com/open-telemetry/build-tools/tree/main/semantic-conventions/syntax.md) -for how to write the YAML files for semantic conventions. +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 @@ -39,7 +39,3 @@ 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) - -## Description of the model - -The fields and their expected values are presented in [syntax.md](./syntax.md). From e46bd177589974cf001c962a03ff52e2af8c9de2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20Neum=C3=BCller?= Date: Thu, 22 Jul 2021 17:56:12 +0200 Subject: [PATCH 3/3] Fix one more link to syntax.md. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index aa9194fefc3..a700df41b7e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -61,7 +61,7 @@ See: ### Semantic Conventions update Semantic convention is declared in YAML files and markdown tables are -generated from these files. Read about semantic convention updates [here](./semantic_conventions/syntax.md). +generated from these files. Read about semantic convention updates [here](./semantic_conventions/README.md). ### Autoformatting