Skip to content

Latest commit

 

History

History
125 lines (91 loc) · 5.46 KB

README.md

File metadata and controls

125 lines (91 loc) · 5.46 KB
Raw

Semantic Convention generator + Docker

A docker image to process Semantic Convention YAML models.

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.

Code Generator

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

For example, opentelemetry-java generates typed constants for semantic conventions using this template.

The commands used to generate that are here in the opentelemetry-java repo. Note especially the docker run commands. For example to generate the aforementioned SemanticAttributes.java, the following command is used:

docker run --rm \
  -v ${SCRIPT_DIR}/opentelemetry-specification/semantic_conventions/trace:/source \
  -v ${SCRIPT_DIR}/templates:/templates \
  -v ${ROOT_DIR}/semconv/src/main/java/io/opentelemetry/semconv/trace/attributes/:/output \
  otel/semconvgen:$GENERATOR_VERSION \
  --yaml-root /source \
  code \
  --template /templates/SemanticAttributes.java.j2 \
  --output /output/SemanticAttributes.java \
  -Dclass=SemanticAttributes \
  -DschemaUrl=$SCHEMA_URL \
  -Dpkg=io.opentelemetry.semconv.trace.attributes

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.