Skip to content

Latest commit

 

History

History
147 lines (101 loc) · 6.34 KB

README.md

File metadata and controls

147 lines (101 loc) · 6.34 KB
Raw

Semantic Convention generator + Docker

A docker image to process Semantic Convention YAML models.

See CONTRIBUTING.md for information on making changes to this repository.

Usage

The image can be used to generate Markdown tables or code.

docker run --rm -v<yaml-path>:<some-path> -v<output-path>:<some-path> otel/semconvgen [OPTION]

For help try:

docker run --rm otel/semconvgen -h

Model definition language (YAML input)

The expected YAML input file format is documented in syntax.md.

There is also a JSON schema definition available for the YAML files, which can be used e.g. in VS code to get validation and auto-completion: semconv.schema.json. For example, with the redhat.vscode-yaml plugin, use the following snippet in your VS Code settings.json to apply it to the test YAML files:

{
    "yaml.schemas": {
        "./semantic-conventions/semconv.schema.json": [
            "semantic-conventions/src/tests/**/*.yaml"
        ]
    }
}

Markdown Tables

Tables can be generated using the command:

docker run --rm otel/semconvgen --yaml-root {yaml_folder} markdown --markdown-root {markdown_folder}

Where {yaml_folder} is the absolute path to the directory containing the yaml files and {markdown_folder} the absolute path to the directory containing the markdown definitions (specification for opentelemetry-specification).

The tool will automatically replace the tables with the up to date definition of the semantic conventions. To do so, the tool looks for special tags in the markdown.

<!-- semconv {semantic_convention_id} -->
<!-- endsemconv -->

Everything between these two tags will be replaced with the table definition. The {semantic_convention_id} MUST be the id field in the yaml files of the semantic convention for which we want to generate the table. After {semantic_convention_id}, optional parameters enclosed in parentheses can be added to customize the output:

  • tag={tag}: prints only the attributes that have {tag} as a tag;
  • full: prints attributes and constraints inherited from the parent semantic conventions or from included ones;
  • ref: prints attributes that are referenced from another semantic convention;
  • remove_constraint: does not print additional constraints of the semantic convention.

Examples

These examples assume that a semantic convention with the id http.server extends another semantic convention with the id http.

<!-- semconv http.server --> will print only the attributes and constraints of the http.server semantic convention.

<!-- semconv http.server(full) --> will print the attributes and constraints of the http semantic convention and also the attributes and constraints of the http.server semantic convention.

<!-- semconv http.server() --> is equivalent to <!-- semconv http.server -->.

<!-- semconv http.server(tag=network) --> will print the constraints and attributes of the http.server semantic convention that have the tag network.

<!-- semconv http.server(tag=network, full) --> will print the constraints and attributes of both http and http.server semantic conventions that have the tag network.

<!-- semconv metric.http.server.active_requests(metric_table) --> will print a table describing a single metric http.server.active_requests.

Code Generator

The image supports Jinja templates to generate code from the models.

For example, opentelemetry-java generates typed constants for semantic conventions. Refer to https://github.com/open-telemetry/semantic-conventions-java for all semantic conventions.

The commands used to generate that are here in the semantic-conventions-java repo

By default, all models are fed into the specified template at once, i.e. only a single file is generated. This is helpful to generate constants for the semantic attributes, example from opentelemetry-java.

If the parameter --file-per-group {pattern} is set, a single yaml model is fed into the template and the value of pattern is resolved from the model and attached as prefix to the output argument. This way, multiple files are generated. The value of pattern can be one of the following:

  • semconv_id: The id of the semantic convention.
  • prefix: The prefix with which all attributes starts with.
  • extends: The id of the parent semantic convention.

Finally, additional value can be passed to the template in form of key=value pairs separated by comma using the --parameters [{key=value},]+ or -D flag.

Customizing Jinja's Whitespace Control

The image also supports customising Whitespace Control in Jinja templates via the additional flag --trim-whitespace. Providing the flag will enable both lstrip_blocks and trim_blocks.

Version compatibility check

You can check compatibility between the local one specified with --yaml-root and sepcific OpenTelemetry semantic convention version using the following command:

docker run --rm otel/semconvgen --yaml-root {yaml_folder} compatibility --previous-version {semconv version}

The {semconv version} (e.g. 1.24.0) is the previously released version of semantic conventions.

Following checks are performed

  • On all attributes and metrics (experimental and stable):

    • attributes and metrics must not be removed.

  • On stable attributes and attribute templates:

    • stability must not be changed
    • the type of attribute must not be changed
    • enum attribute: type of value must not be changed
    • enum attribute: members must not be removed (changing id field is allowed, as long as value does not change)

  • On stable metrics:

    • stability must not be changed
    • instrument and unit must not be changed
    • new attributes should not be added. This check does not take into account opt-in attributes. Adding new attributes to metric is not always breaking, so it's considered non-critical and it's possible to suppress it with --ignore-warnings