Skip to content

Template types: define type-safe examples #1740

Open
@jerbly

Description

@jerbly

There are real-world examples of template types in use that already create non-compliant output. For example http.request.header.KEY is defined with type: template[string[]]. However, it is common to see a single string rather than an array of strings in the data sent out. There are also examples already defined that suggest a mixed-type for the dictionary values would be preferable.

Secondly, the definition of template type examples (with or without a mixed-type) is not strongly-typed. This makes it hard/impossible to check with weaver and therefore ensure correctness.

Here are some examples from the current semconv definitions:

Mismatch key:

      - id: rpc.connect_rpc.request.metadata
        type: template[string[]]
        examples: ['rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]']

Missing keys:

      - id: db.operation.parameter
        type: template[string]
        examples: ["someval", "55"]

Mixed types:

      - id: db.elasticsearch.path_parts
        type: template[string]
        examples:
          [
            "db.elasticsearch.path_parts.index=test-index",
            "db.elasticsearch.path_parts.doc_id=123",
          ]

Suggestions:

Allow mixed type values within template types. Either remove the strict typing:

    template[string]
    template[int]
    template[boolean]
    template[double]
    template[string[]]
    template[int[]]
    template[boolean[]]
    template[double[]]

Replaced with just template.

Or, add a mixed-type definition: template[any]

Make examples type and correctness checkable:

groups:
  - id: rpc.connect_rpc.request.metadata
    type: template[string[]]
    # examples: ['rpc.request.metadata.my-custom-metadata-attribute=["1.2.3.4", "1.2.3.5"]']
    examples:
      - key: "my-custom-metadata-attribute"
        value: ["1.2.3.4", "1.2.3.5"]
  - id: db.elasticsearch.path_parts
    #type: template[string]
    type: template[any]
    # examples:
    #   [
    #     "db.elasticsearch.path_parts.index=test-index",
    #     "db.elasticsearch.path_parts.doc_id=123",
    #   ]
    examples:
      - key: "index"
        value: "test-index"
      - key: "doc_id"
        value: 123

Note: I've included a mixed type case here
The generated documentation can combine the key with the id preventing mistakes as seen in the rpc example above.

Metadata

Metadata

Assignees

Labels

schemaSemantic Conventions schema definitiontoolingRegarding build, workflows, build-tools, ...

Type

No type

Projects

  • Status

    Clean up YAML schema

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions