syntax.md

Semantic Convention YAML Language

First, the syntax with a pseudo EBNF grammar is presented. Then, the semantic of each field is described.

• Semantic Convention YAML Language
  • JSON Schema
  • Syntax
  • Semantics
    • Groups
    • Semantic Convention
      • Span semantic convention
      • Event semantic convention
      • Metric Group semantic convention
      • Metric semantic convention
      • Attribute group semantic convention
    • Attributes
      • Examples (for examples)
      • Ref
      • Type
    • Constraints
      • Any Of
      • Include

JSON Schema

A JSON schema description of the syntax is available as semconv.schema.json, see README.md for how to use it with an editor. The documentation here in syntax.md should be considered more authoritative though. Please keep semconv.schema.json in synch when changing the "grammar" in this file!

Syntax

All attributes are lower case.

groups ::= semconv
       | semconv groups

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

id    ::= string

convtype ::= "span" # Default if not specified
         |   "resource" # see spanspecificfields
         |   "event"    # see eventspecificfields
         |   "metric"   # see metricfields
         |   "metric_group"
         |   "scope"
         |   "attribute_group" # no specific fields defined

brief ::= string
note  ::= string

prefix ::= string

extends ::= string

stability ::= "deprecated"
          |   "experimental"
          |   "stable"

deprecated ::= <description>

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

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]

requirement_level ::= "required"
         |   "conditionally_required" <condition>
         |   "recommended" [condition] # Default if not specified
         |   "opt_in"

# EXPERIMENTAL: Using this is NOT ALLOWED in the specification currently.
sampling_relevant ::= boolean

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

constraints ::= constraint {constraint}

constraint ::= any_of
           |   include

any_of ::= id {id}

include ::= id

specificfields ::= spanfields
               |   eventfields
               |   metricfields

spanfields ::= [events] [span_kind]
eventfields ::= [name]

span_kind ::= "client"
          |   "server"
          |   "producer"
          |   "consumer"
          |   "internal"

events ::= id {id} # MUST point to an existing event group

name ::= string

metricfields ::= metric_name instrument unit

metric_name ::= string
instrument ::=  "counter" 
            | "histogram" 
            | "gauge" 
            | "updowncounter" 
unit ::= string

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.

• type, optional enum, defaults to span (with a warning if not present).

• 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.

• stability, optional enum, specifies the stability of the semantic convention.

  Note that, if stability is missing but deprecated is present, it will automatically set the stability to deprecated. If deprecated is present and stability differs from deprecated, this will result in an error.

• deprecated, optional, specifies if the semantic convention is deprecated. The string provided as <description> MUST specify why it's deprecated and/or what to use instead. See also stability.

• attributes, list of attributes that belong to the semantic convention.

• constraints, optional list, additional constraints (See later). It defaults to an empty list.

Span semantic convention

The following is only valid if type is span (the default):

• span_kind, optional enum, specifies the kind of the span.
• events, optional list of strings that specify the ids of event semantic conventions associated with this span semantic convention.

Event semantic convention

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.

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 can be defined and then referenced from other metric groups using ref.

Metric semantic convention

The following is only valid if type is metric:

• metric_name, required, the metric name as described by the OpenTelemetry Specification.
• instrument, required, the instrument type that should be used to record the metric. Note that the semantic conventions must be written using the names of the synchronous instrument types (counter, gauge, updowncounter and histogram). For more details: Metrics semantic conventions - Instrument types.
• unit, required, the unit in which the metric is measured, which should adhere to the guidelines.

Attribute group semantic convention

Attribute group (attribute_group type) defines a set of attributes that can be declared once and referenced by semantic conventions for different signals, for example spans and logs. Attribute groups don't have any specific fields and follow the general semconv semantics.

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 for the definition of the value types.

• ref, optional string, reference an existing attribute, see below.

• 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 in the markdown generator.

• requirement_level, optional, specifies if the attribute is mandatory. Can be "required", "conditionally_required", "recommended" or "opt_in". When omitted, the attribute is "recommended". When set to "conditionally_required", the string provided as <condition> MUST specify the conditions under which the attribute is required.

• sampling_relevant, optional EXPERIMENTAL boolean, specifies if the attribute is (especially) relevant for sampling and thus should be set at span start. It defaults to false.

• brief, note, stability, deprecated, same meaning as for the whole semantic convention, but per attribute.

• examples, sequence of example values for the attribute or single example value. They are required only for string and string array 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. See below.

Examples (for examples)

Examples for setting the examples field:

A single example value for a string attribute. All the following three representations are equivalent:

examples: 'this is a single string'

or

examples: ['this is a single string']

or

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:

examples:
   - ['this is an error']

examples: [['this is an error']]

Multiple example values for a string attribute:

examples: ['this is a single string', 'this is another one']

or

examples:
   - 'this is a single string'
   - 'this is another one'

A single example value for an array of strings attribute:

examples: ['first element of first array', 'second element of first array']

or

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:

examples: 'this is an error'

Multiple example values for an array of string attribute:

examples: [ ['first element of first array', 'second element of first array'], ['first element of second array', 'second element of second array'] ]

or

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.