Skip to content

define-your-own-telemetry-schema.md

Latest commit

 

History

History
111 lines (87 loc) · 4.15 KB

define-your-own-telemetry-schema.md

File metadata and controls

111 lines (87 loc) · 4.15 KB

Define your own telemetry schema

Weaver allows you to specify your application's signals using a telemetry schema based on the concept of semantic conventions. These telemetry schemas are also called custom registries. You can define your own signals or reuse the signals and attributes defined by the OTEL semantic conventions (url).

To define your schema, you must:

  • create a directory that will contain your semantic conventions
  • add a manifest.yaml file (see structure below)
  • add semantic convention files describing the signals that your application may produce

From there, you can use Weaver commands to check, resolve, generate code and documentation, or even control your instrumentation with the live-check command.

manifest.yaml file

This manifest file is used to define the metadata of your custom registry and the dependencies it has on other registries. The manifest file is required for the weaver tool to recognize your custom registry and to resolve it correctly.

name: <custom registry name>
description: <an optional description of the custom registry>
schema_url: <base URL where the registry's schema files are hosted>/<version of this custom registry>
dependencies:
  - name: <an alias for the dependency>
    registry_path: <the location of the dependency>

Current limitations:

  • Weaver supports a maximum of 10 registry levels without circular dependencies. In practice, this is not a limitation, even for complex enterprise environments.

Below is an example of a valid manifest.yaml file:

name: acme
description: This registry contains the semantic conventions for the Acme vendor.
schema_url: https://acme.com/schemas/0.1.0
dependencies:
  - name: otel
    registry_path: https://github.com/open-telemetry/semantic-conventions@v1.40.0[model]

Semantic conventions files

Semantic conventions are defined in YAML files. OpenTelemetry maintains a registry of general attributes and signals across many domains, from databases and messaging to generative AI (see the official OTEL semantic conventions).

You can define your own semantic conventions or reuse those defined by OTEL. The example below shows how to define a simple span semantic convention representing a message sent by a client application.

You can also import existing semantic conventions from other registries, such as the OTEL semantic conventions, to extend your custom registry.

groups:
  - id: span.example_message
    type: span
    stability: development
    brief: This span represents a simple message.
    span_kind: client
    attributes:
      - ref: host.name                 # imported from OTEL semantic conventions
        requirement_level: required    # requirement level redefined locally
      - ref: host.arch                 # imported from OTEL semantic conventions
        requirement_level: required    # requirement level redefined locally

imports:
  metrics:
    - db.*                # import all metrics in the `db` namespace
  entities:
    - gcp.*               # import all entities in the `gcp` namespace
  events:
    - session.start       # import the `session.start` event

In the imports section, you can specify which metric, event, and entity groups to import from other registries. You can use a wildcard expression to import all groups in a namespace or specify individual groups by name.

Run weaver commands on your schema

To check the validity of your custom registry

weaver registry check -r <path-to-your-registry>

To control the compliance of your instrumentation with your custom registry

weaver registry live-check --registry <path-to-your-registry>

All commands accepting the -r or --registry parameter can be applied to your custom registry. It is important to note that some templates are specific to the OTEL registry. We are working to remove this type of limitation.

The <path-to-your-registry> parameter can be a local directory, a local or remote archive or a Git URL. It is also possible to use specific Git references, such as a tag, a branch or even a specific commit with the <path-to-your-registry>@<refspec> syntax.