Move syntax.md to build-tools, improve semconv README. (#1825)
This commit is contained in:
Christian Neumüller
GitHub
parent
91392de830
commit
00e41f5884
|
|
@ -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
|
||||
}
|
||||
|
|
|
|||
|
|
@ -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 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/main/semantic-conventions/README.md) for what extension you need.
|
||||
|
||||
## Generation
|
||||
|
||||
|
|
@ -26,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).
|
||||
|
|
|
|||
|
|
@ -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" <condition>
|
||||
|
||||
examples ::= <example_value> {<example_value>}
|
||||
|
||||
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 `<condition>` 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.
|
||||
Loading…
Reference in New Issue