Skip to content

Commit

Permalink
update schema and syntax
Browse files Browse the repository at this point in the history
  • Loading branch information
@lmolkova
lmolkova committed Aug 8, 2024
1 parent 7776f2e commit 636a64a
Show file tree
Hide file tree
Showing 2 changed files with 105 additions and 66 deletions.
136 changes: 94 additions & 42 deletions semantic-conventions/semconv.schema.json
View file
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
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

0 comments on commit 636a64a

Please sign in to comment.