Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update schema and syntax #344

Merged
merged 3 commits into from
Aug 8, 2024
Merged

Update schema and syntax #344

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
636a64a
update schema and syntax
lmolkova Aug 8, 2024
85e820d
changelog
lmolkova Aug 8, 2024
ffb95c4
fix array examples
lmolkova Aug 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 94 additions & 42 deletions semantic-conventions/semconv.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"description": "YAML schema for semantic convention generator, use for example with VS Code.",
"additionalProperties": false,
Expand All @@ -9,27 +9,44 @@
"items": {
"anyOf": [
{
"allOf": [{"$ref": "#/definitions/SemanticConvention"}]
"allOf": [
{
"$ref": "#/$defs/SemanticConvention"
}
]
},
{
"allOf": [{"$ref": "#/definitions/SpanSemanticConvention"}]
"allOf": [
{
"$ref": "#/$defs/SpanSemanticConvention"
}
]
},
{
"allOf": [{"$ref": "#/definitions/EventSemanticConvention"}]
"allOf": [
{
"$ref": "#/$defs/EventSemanticConvention"
}
]
},
{
"allOf": [{"$ref": "#/definitions/MetricSemanticConvention"}]
"allOf": [
{
"$ref": "#/$defs/MetricSemanticConvention"
}
]
}
]
}
}
},
"definitions": {
"$defs": {
"SemanticConventionBase": {
"type": "object",
"required": [
"id",
"brief"
"brief",
"stability"
],
"anyOf": [
{
Expand Down Expand Up @@ -67,29 +84,40 @@
"type": "string",
"description": "a more elaborate description of the semantic convention. It defaults to an empty string"
},
"prefix": {
"type": "string",
"description": "prefix of the attribute for this semconv. It defaults to an empty string."
},
"extends": {
"type": "string",
"description": "reference another semantic convention ID. It inherits all attributes from the specified semconv."
"description": "reference another semantic convention ID. It inherits all attributes from the specified semantic convention."
},
"attributes": {
"type": "array",
"items": {
"$ref": "#/definitions/Attribute"
"$ref": "#/$defs/Attribute"
},
"description": "list of attributes that belong to the semconv"
"description": "list of attributes that belong to the semantic convention"
},
"display_name": {
"type": "string",
"description": "the display name / title of the attribute group."
},
"deprecated": {
"type": "string",
"description": "specifies if the attribute is deprecated. The string provided as <description> MUST specify why it's deprecated and/or what to use instead."
},
"stability": {
"allOf": [
{
"$ref": "#/$defs/StabilityLevel"
}
]
}
}
},
"SpanSemanticConvention": {
"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
"allOf": [
{
"$ref": "#/$defs/SemanticConventionBase"
}
],
"properties": {
"type": {
"type": "string",
Expand All @@ -104,29 +132,40 @@
"consumer",
"internal"
],
"description": "specifies the kind of the span. Leaf semconv nodes (in the hierarchy tree) that do not have this field set will generate a warning."
"description": "specifies the kind of the span. Leaf semantic convention nodes (in the hierarchy tree) that do not have this field set will generate a warning."
}
}
},
"EventSemanticConvention": {
"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
"allOf": [
{
"$ref": "#/$defs/SemanticConventionBase"
}
],
"properties": {
"type": {
"type": "string",
"const": "event"
},
"name": {
"type": "string",
"description": "The name of the event. Required if no prefix is given."
"description": "The name of the event."
}
},
"anyOf": [
{"required": ["prefix"]},
{"required": ["name"]}
{
"required": [
"name"
]
}
]
},
"MetricSemanticConvention": {
"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
"allOf": [
{
"$ref": "#/$defs/SemanticConventionBase"
}
],
"required": [
"type",
"metric_name",
Expand Down Expand Up @@ -159,13 +198,22 @@
}
},
"SemanticConvention": {
"allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }],
"required": ["type"],
"allOf": [
{
"$ref": "#/$defs/SemanticConventionBase"
}
],
"required": [
"type"
],
"properties": {
"type": {
"type": "string",
"not": {
"enum": ["span", "event"]
"enum": [
"span",
"event"
]
}
}
}
Expand All @@ -174,17 +222,15 @@
"type": "object",
"additionalProperties": false,
"properties": {
"allow_custom_values": {
"type": "boolean"
},
"members": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"value"
"value",
"stability"
],
"properties": {
"id": {
Expand All @@ -206,8 +252,16 @@
"type": "string",
"description": "longer description. It defaults to an empty string."
},
"deprecated": {
"type": "string",
"description": "specifies if the attribute is deprecated. The string provided as <description> MUST specify why it's deprecated and/or what to use instead."
},
"stability": {
"allOf": [{ "$ref": "#/definitions/StabilityLevel" }]
"allOf": [
{
"$ref": "#/$defs/StabilityLevel"
}
]
}
}
}
Expand All @@ -217,7 +271,8 @@
"AttributeFullSpec": {
"required": [
"id",
"type"
"type",
"stability"
],
"properties": {
"id": {
Expand Down Expand Up @@ -249,7 +304,7 @@
"description": "literal denoting the type"
},
{
"$ref": "#/definitions/AttributeEnumType"
"$ref": "#/$defs/AttributeEnumType"
}
]
}
Expand Down Expand Up @@ -362,30 +417,27 @@
},
"examples": {
"anyOf": [
{ "$ref": "#/definitions/ValueType" },
{
"$ref": "#/$defs/ValueType"
},
{
"type": "array",
"items": { "$ref": "#/definitions/ValueType" }
"items": {
"$ref": "#/$defs/ValueType"
}
}
],
"description": "sequence/dictionary of example values for the attribute. They are optional for boolean, int, double, 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."
},
"deprecated": {
"type": "string",
"description": "specifies if the attribute is deprecated. The string provided as <description> MUST specify why it's deprecated and/or what to use instead."
},
"stability": {
"allOf": [{ "$ref": "#/definitions/StabilityLevel" }]
}
}
},
{
"oneOf": [
{
"$ref": "#/definitions/AttributeFullSpec"
"$ref": "#/$defs/AttributeFullSpec"
},
{
"$ref": "#/definitions/AttributeReference"
"$ref": "#/$defs/AttributeReference"
}
]
}
Expand Down
35 changes: 11 additions & 24 deletions semantic-conventions/syntax.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ All attributes are lower case.
groups ::= semconv
| semconv groups

semconv ::= id [convtype] brief [note] [prefix] [extends] [stability] [deprecated] attributes [specificfields]
semconv ::= id [convtype] brief [note] [extends] stability [deprecated] attributes [specificfields]

id ::= string

Expand All @@ -53,16 +53,14 @@ convtype ::= "span" # Default if not specified
brief ::= string
note ::= string

prefix ::= string

extends ::= string

stability ::= "experimental"
| "stable"

deprecated ::= <description>

attributes ::= (id type brief examples | ref [brief] [examples]) [tag] [stability] [deprecated] [required] [sampling_relevant] [note]
attributes ::= (id type brief examples | ref [brief] [examples]) [tag] stability [deprecated] [required] [sampling_relevant] [note]

# ref MUST point to an existing attribute id
ref ::= id
Expand All @@ -82,13 +80,11 @@ simple_type ::= "string"

template_type ::= "template[" simple_type "]" # As a single string

enum ::= [allow_custom_values] members

allow_custom_values := boolean
enum ::= members

members ::= member {member}

member ::= id value [brief] [note] [stability] [deprecated]
member ::= id value [brief] [note] stability [deprecated]

requirement_level ::= "required"
| "conditionally_required" <condition>
Expand All @@ -99,10 +95,6 @@ sampling_relevant ::= boolean

examples ::= <example_value> {<example_value>}

any_of ::= id {id}

include ::= id

specificfields ::= spanfields
| eventfields
| metricfields
Expand Down Expand Up @@ -143,12 +135,11 @@ The field `semconv` represents a semantic convention and it is made by:
- `id`, string that uniquely identifies the semantic convention.
- `type`, optional enum, defaults to `span` (with a warning if not present).
- `brief`, string, a brief description of the semantic convention.
- `stability`, required enum, either `stable` or `experimental`, specifies the stability of the attribute.
- `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, and all attributes defined in the specified semantic convention.
It inherits all attributes defined in the specified semantic convention.
- `deprecated`, optional, when present marks the semantic convention as deprecated.
The string provided as `<description>` MUST specify why it's deprecated and/or what to use instead.
- `attributes`, list of attributes that belong to the semantic convention.
Expand All @@ -165,16 +156,14 @@ The following is only valid if `type` is `span` (the default):

The following is only valid if `type` is `event`:

- `name`, conditionally required string. The name of the event.
If not specified, the `prefix` is used. If `prefix` is empty (or unspecified),
`name` is required.
- `name`, required, string. The name of the event.

#### Metric Group semantic convention

Metric group inherits all from the base semantic convention, and does not
add any additional fields.

The metric group semconv is a group where related metric attributes
The metric group semantic convention is a group where related metric attributes
can be defined and then referenced from other `metric` groups using `ref`.

#### Metric semantic convention
Expand Down Expand Up @@ -210,10 +199,10 @@ An attribute is defined by:
* `"string[]"`: Array of strings attributes.
* `"int[]"`: Array of integer attributes.
* `"double[]"`: Array of double attributes.
* `"boolean[]"`: Array of booleans attributes.
* `"boolean[]"`: Array of boolean attributes.
* _template type as string literal:_ `"template[<PRIMITIVE_OR_ARRAY_TYPE>]"` (See [below](#template-type))
See the [specification of Attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute) for the definition of the value types.
- `stability`, enum - either `stable` or `experimental`, specifies the stability of the attribute. Required.
- `stability`, required enum, either `stable` or `experimental`, specifies the stability of the attribute.
- `ref`, optional string, reference an existing attribute, see [below](#ref).
- `tag`, optional string, associates a tag ("sub-group") to the attribute.
It carries no particular semantic meaning but can be used e.g. for filtering
Expand Down Expand Up @@ -321,7 +310,7 @@ fields are present in the current attribute definition, they override the inheri
#### Type

An attribute type can either be a string, int, double, boolean, array of strings, array of int, array of double,
array of booleans, a template type or an enumeration.
array of boolean, a template type or an enumeration.

##### Template type

Expand Down Expand Up @@ -355,8 +344,6 @@ In this example the definition will be resolved into a dictionary of attributes

If the type 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:
Expand Down
Loading