### Install Playwright Browsers

Source: https://github.com/open-telemetry/weaver/blob/main/ui/README.md

Installs the necessary browser binaries for Playwright end-to-end tests. This is a one-time setup step.

```sh
pnpm exec playwright install chromium
```

--------------------------------

### Single String Example (Multiple Formats)

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md

Demonstrates three equivalent ways to specify a single string example for an attribute.

```yaml
examples: "this is a single string"
```

```yaml
examples: ["this is a single string"]
```

```yaml
examples:
  - "this is a single string"
```

--------------------------------

### Multiple String Examples (Multiple Formats)

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md

Shows two equivalent ways to specify multiple string examples for an attribute.

```yaml
examples: ["this is a single string", "this is another one"]
```

```yaml
examples:
  - "this is a single string"
  - "this is another one"
```

--------------------------------

### Install Dependencies

Source: https://github.com/open-telemetry/weaver/blob/main/ui/README.md

Installs project dependencies using pnpm. Ensure Node.js and pnpm are set up according to the prerequisites.

```sh
pnpm install
```

--------------------------------

### Weaver Configuration Example

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md

Shows a sample weaver.yaml configuration snippet defining templates, JQ filters, and application modes. This file guides Weaver's generation process.

```yaml
templates:
  - template: "attributes.j2"
    filter: semconv_grouped_attributes
    application_mode: each
  - ...
```

--------------------------------

### Multiple Array of Strings Examples (Multiple Formats)

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md

Presents two equivalent ways to specify multiple examples for an array of strings attribute.

```yaml
examples:
  [
    ["first element of first array", "second element of first array"],
    ["first element of second array", "second element of second array"],
  ]
```

```yaml
examples:
  - ["first element of first array", "second element of first array"]
  - ["first element of second array", "second element of second array"]
```

--------------------------------

### Install cargo-nextest

Source: https://github.com/open-telemetry/weaver/blob/main/CONTRIBUTING.md

Installs cargo-nextest for faster and better-formatted test output. Use this for improved testing experience.

```bash
cargo install cargo-nextest --locked
```

--------------------------------

### Single Array of Strings Example (Multiple Formats)

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md

Provides two equivalent ways to specify a single example for an array of strings attribute.

```yaml
examples: [["first element of first array", "second element of first array"]]
```

```yaml
examples:
  - ["first element of first array", "second element of first array"]
```

--------------------------------

### Invalid String Example Format

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md

Illustrates incorrect formats for providing a string example, which would lead to type mismatch errors.

```yaml
examples:
   - ['this is an error']

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

--------------------------------

### Install and Use cargo-expand

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_macros/README.md

Use `cargo-expand` to inspect the code generated by Weaver macros. This requires a one-time setup and the nightly toolchain.

```bash
cargo install cargo-expand  # one-time setup; also requires `rustup toolchain install nightly`

cargo expand registry::emit  # expand a module; search the output for the struct/impl you want
```

--------------------------------

### PolicyFinding Example

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_live_check/README.md

Illustrates a PolicyFinding from a builtin advisor for a missing attribute. The 'live_check_result' object augments the sample entity with compliance details.

```json
{
  "live_check_result": {
    "all_advice": [
      {
        "level": "violation",
        "id": "missing_attribute",
        "message": "Attribute `hello` does not exist in the registry.",
        "context": { "attribute_key": "hello" },
        "signal_name": "http.client.request.duration",
        "signal_type": "metric"
      }
    ],
    "highest_advice_level": "violation"
  },
  "name": "hello",
  "type": "string",
  "value": "world"
}
```

--------------------------------

### Definition Manifest Example

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-schemas.md

Example of a definition manifest for a registry that extends OTel semantic conventions. Specifies schema URL, stability, description, and dependencies.

```yaml
schema_url: https://acme.com/schemas/my-registry/1.0.0
stability: development
description: My custom registry.
dependencies:
- schema_url: https://opentelemetry.io/schemas/1.{future}.0
```

--------------------------------

### Example manifest.yaml with OTEL Dependency

Source: https://github.com/open-telemetry/weaver/blob/main/docs/define-your-own-telemetry-schema.md

An example of a manifest.yaml file that defines a custom registry named 'acme' and includes a dependency on OpenTelemetry semantic conventions version 1.40.0.

```yaml
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]
```

--------------------------------

### Example Schema Diff in YAML

Source: https://github.com/open-telemetry/weaver/blob/main/docs/schema-changes.md

An example of a schema diff report in YAML format, showing changes in registry attributes, events, and metrics between two versions.

```yaml
head:
  semconv_version: v1.27.0
baseline:
  semconv_version: v1.26.0
changes:
  registry_attributes:
    - name: http.server_name      # attribute name
      type: obsoleted             # change type
      note: This attribute is deprecated.
    - name: user.email            # attribute name
      type: added                 # change type
    - name: http_target
      type: renamed
      new_name: http.target
      note: Renamed to http.target
    - ...
  events:
    - name: exception
      type: added
    - ...
  metrics:
    - name: go.goroutine.count
      type: added
    - name: db.client.connections.max
      type: obsoleted
      note: Deprecated
    - ...

```

--------------------------------

### Java Comment Format Example

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md

An example configuration for generating Java comments using HTML format, specifying Javadoc and general Java comment styles.

```yaml
# Example of configuration for Java
comment_formats:
  javadoc:
    format: html
    header: "/**"
    prefix: " * "
    footer: " */"
    old_style_paragraph: true
    omit_closing_li: false
    inline_code_snippet: "{@code {{code}}}"
    block_code_snippet: "<pre>{@code {{code}}}</pre>"
    trim: true
    remove_trailing_dots: true
  java:
    format: html
    prefix: "// "
    old_style_paragraph: true
    omit_closing_li: false
    inline_code_snippet: "{@code {{code}}}"
    block_code_snippet: "<pre>{@code {{code}}}</pre>"
    trim: true
    remove_trailing_dots: true
default_comment_format: javadoc

```

--------------------------------

### Released Version Policy Example

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_checker/README.md

Shows the structure of a released version of a network attribute policy.

```yaml
groups:
  - id: registry.network1
    prefix: network
    type: attribute_group
    brief: >
      These attributes may be used for any network related operation.
    attributes:
      - id: protocol.name
        stability: stable
        type: string
        brief: '[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.'
        note: The value SHOULD be normalized to lowercase.
        examples: ['amqp', 'http', 'mqtt']
        deprecated: true
      - id: protocol.name.3
        stability: stable
        type: string
        brief: '[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.'
        note: The value SHOULD be normalized to lowercase.
        examples: ['amqp', 'http', 'mqtt']

```

--------------------------------

### Unreleased Version Policy Example

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_checker/README.md

Shows the structure of an unreleased version of a network attribute policy, including a reference to another attribute.

```yaml
groups:
  - id: registry.network
    prefix: network
    type: attribute_group
    brief: >
      These attributes may be used for any network related operation.
    attributes:
      - id: protocol.name.1
        stability: stable
        type: string
        brief: '[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.'
        note: The value SHOULD be normalized to lowercase.
        examples: ['amqp', 'http', 'mqtt']
        deprecated: true
      - id: protocol.name.2
        stability: stable
        type: string
        brief: '[OSI application layer](https://osi-model.com/application-layer/) or non-OSI equivalent.'
        note: The value SHOULD be normalized to lowercase.
        examples: ['amqp', 'http', 'mqtt']
      - ref: protocol.port
        deprecated: true

```

--------------------------------

### Metric Definition Example

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.v2.md

Illustrates the structure of a metric definition, including name, description, unit, instrument type, stability, attributes, and entity associations.

```yaml
metrics:
  - name: http.server.request.duration
    brief: Duration of HTTP server requests.
    unit: s
    instrument: histogram
    stability: stable
    attributes:
      - ref: http.request.method
        requirement_level: required
      - ref: http.response.status_code
        requirement_level: required
      # ...
    entity_associations:
      - service.instance
```

--------------------------------

### Configure JQ Filters in weaver.yaml

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md

Example configuration showing how to associate JQ filters with templates in the weaver.yaml file. This setup allows for data manipulation before templates are rendered.

```yaml
templates:
  - template: "attributes.j2"
    filter: semconv_grouped_attributes
    application_mode: each
  - template: "metrics.j2"
    filter: semconv_grouped_metrics
    application_mode: each
  # ...
```

--------------------------------

### Preview Production Build

Source: https://github.com/open-telemetry/weaver/blob/main/ui/README.md

Serves the production build locally for sanity checking before deployment.

```sh
pnpm preview
```

--------------------------------

### Round-trip Test with Emit

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_live_check/README.md

Perform a round-trip test using `weaver registry emit`. This example starts live-check, emits telemetry data, and then signals live-check to stop. This is useful for verifying that telemetry is correctly processed and emitted.

```sh
weaver registry live-check --output ./outdir &
LIVE_CHECK_PID=$!
sleep 3
weaver registry emit --skip-policies
kill -HUP $LIVE_CHECK_PID
wait $LIVE_CHECK_PID
```

--------------------------------

### CI/CD JSON Report Generation

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_live_check/README.md

Generate a JSON report for CI/CD pipelines. This example starts live-check in the background, waits for a few seconds, runs the code under test, and then signals live-check to stop. The exit code and the JSON report in the output directory can then be checked.

```sh
weaver registry live-check --format json --output ./outdir &
LIVE_CHECK_PID=$!
sleep 3
# Run the code under test here.
kill -HUP $LIVE_CHECK_PID
wait $LIVE_CHECK_PID
# Check the exit code and/or parse the JSON in outdir
```

--------------------------------

### Jinja Template - Basic File Naming

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_forge/README.md

A basic Jinja template example. The first two lines can optionally specify the output file name and inputs.

```jinja
...
a valid jinja template
...
```

--------------------------------

### Generate Documentation (Markdown)

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_live_check/docs/dog-fooding.md

Use the `otel/weaver` Docker image to generate markdown documentation files. Ensure you have the necessary model and template paths correctly specified.

```sh
docker run --rm \
  -u "$(id -u):$(id -g)" \
  -e HOME=/tmp \
  -v "$(pwd)":/home/weaver/source \
  otel/weaver:v0.24.2 \
  registry generate \
  --registry /home/weaver/source/crates/weaver_live_check/model/ \
  --templates /home/weaver/source/crates/weaver_live_check/templates/ \
  --v2 \
  markdown \
  /home/weaver/source/crates/weaver_live_check/docs/
```

--------------------------------

### Example .weaver.toml Configuration

Source: https://github.com/open-telemetry/weaver/blob/main/docs/specs/package-vs-project-config/config-proposal.md

This TOML file demonstrates various settings that can be configured at the project level in Weaver, including live-check filters, template defaults, and CLI-equivalent options. Settings are grouped by functionality.

```toml
# === Phase 1: Live-check finding filters ===

[[live_check.finding_filters]]
exclude = ["deprecated"]
min_level = "improvement"
exclude_samples = ["trace.parent_id", "trace.span_id"]

# === Template defaults ===
# Shared settings applied on top of all template packages.
# These override the package's own weaver_template.yaml.
#
# [template_defaults]
# acronyms = ["API", "HTTP", "SDK", "CLI", "URL", "JSON"]
#
# [template_defaults.template_syntax]
# block_start = "{%"
# block_end = "%}"
# variable_start = "{{"
# variable_end = "}}"
# comment_start = "{#"
# comment_end = "#}"
#
# [template_defaults.whitespace_control]
# trim_blocks = true
# lstrip_blocks = true
# keep_trailing_newline = false
#
# [template_defaults.params]
# copyright_owner = "Acme"
# year = 2026

# === CLI-equivalent settings ===

# Shared options (apply to all subcommands that accept them)
# [registry]
# path = "https://github.com/open-telemetry/semantic-conventions.git"
# follow_symlinks = false
# include_unreferenced = false
# v2 = true
#
# [policy]
# paths = ["./policies"]
# skip = false
#
# [diagnostics]
# format = "ansi"          # ansi | json | gh_workflow_command
# template = "diagnostic_templates"
# stdout = false
#
# [live_check]
# input_source = "otlp"
# input_format = "json"
# format = "ansi"
# templates = "live_check_templates"
# no_stream = false
# no_stats = false
#
# [live_check.otlp]
# grpc_address = "0.0.0.0"
# grpc_port = 4317
# admin_port = 4320
# inactivity_timeout = 10
#
# [live_check.emit]
# otlp_logs = false
# otlp_logs_endpoint = "http://localhost:4317"
# otlp_logs_stdout = false
#
# [generate]
# templates = "templates"
# target = ""
#
# [emit]
# endpoint = "http://localhost:4317"

```

--------------------------------

### Build Weaver from Source

Source: https://github.com/open-telemetry/weaver/blob/main/README.md

Clone the Weaver repository and build the release binary from source using Cargo.

```bash
git clone https://github.com/open-telemetry/weaver.git
cd weaver
cargo build --release
```

--------------------------------

### Example Weaver Configuration for Java Code Generation

Source: https://github.com/open-telemetry/weaver/blob/main/docs/weaver-config.md

An incomplete example of a weaver.yaml file used for generating Java code from a semconv specification.

```yaml
# Below a concrete example of a `weaver.yaml` file that could be used to generate Java code
# from a semconv specification (incomplete):

```

--------------------------------

### Invalid Array of Strings Example Format

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md

Demonstrates an incorrect format for providing examples for an array of strings attribute, which would result in a type mismatch.

```yaml
examples: "this is an error"
```

--------------------------------

### Run All Code Generation

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_live_check/docs/dog-fooding.md

Execute all code generation steps and format the output. This is the simplest way to regenerate code from the repository root.

```sh
just generate
```

--------------------------------

### Definition Schema Example

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-schemas.md

Example structure of a definition schema used for writing conventions. It includes attributes, metrics, and their properties like key, type, stability, and references.

```yaml
file_format: "definition/2"
attributes:
- key: my.operation.name
  type: string
  stability: development
  brief: My service operation name as defined in this Open API spec
  examples: ["get_object", "create_collection"]
...
metrics:
- name: my.client.operation.duration
  stability: stable
  instrument: histogram
  unit: s
  attributes:
    - ref: my.operation.name
    - ref_group: my.operation.server.attributes
    - ref: error.type
```

--------------------------------

### Live-check General and OTLP Configuration

Source: https://github.com/open-telemetry/weaver/blob/main/crates/weaver_live_check/README.md

Configures general live-check settings such as input source, format, and output directory, along with OTLP-specific parameters like GRPC addresses and ports.

```toml
[live_check]
input_source = "otlp"
input_format = "json"
format = "ansi"
templates = "live_check_templates"
no_stream = false
no_stats = false
output = "reports"
advice_policies = "policies"
advice_preprocessor = "preprocessor.jq"

[live_check.otlp]
grpc_address = "0.0.0.0"
grpc_port = 4317
admin_port = 4320
inactivity_timeout = 10

[live_check.emit]
otlp_logs = false
otlp_logs_endpoint = "http://localhost:4317"
otlp_logs_stdout = false
```

--------------------------------

### Checkout New Branch for Release Preparation

Source: https://github.com/open-telemetry/weaver/blob/main/CONTRIBUTING.md

Use this command to create a new branch for preparing a release. Replace X.Y.Z with the target version number.

```bash
git checkout -b prepare-release-vX.Y.Z
```

--------------------------------

### Event Semantic Convention Example

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-syntax.md

Provides a comprehensive example of an event semantic convention, including its ID, name, type, stability, attributes, and a detailed 'body' definition with nested fields and an enum.

```yaml
- id: event.some_event
  name: the.event.name
  type: event
  brief: "Describes the event."
  stability: development
  attributes: # Optional
    - ref: registry.attribute.id
    - ref: registry.some_other.attribute.id # Reference to an existing global attribute
  body: # Optional, follows the any_value conventions
    id: event_body.some_event.fields
    type: map
    requirement_level: required
    fields: # Unique to this event definition only
      - id: method
        type: string
        stability: development
        brief: "The HTTP method used in the request."
        examples: ["GET", "POST"]
        requirement_level: required
      - id: url
        type: string
        stability: development
        brief: "The URL of the request."
        examples: ["http://example.com"]
        requirement_level: required
      - id: status_code
        type: int
        stability: development
        brief: "The status code of the response."
        examples: [200, 404]
        requirement_level: required
      - id: nested_map
        type: map
        stability: development
        requirement_level: required
        fields:
          - id: nested_field
            type: string # May be any supported any_value type
            stability: development
            requirement_level: required
            brief: "A nested field."
            examples: ["nested_value"]
      - id: nested_enum_state
        type: enum
        stability: development
        requirement_level: required
        members:
          - id: active
            value: "active"
            brief: The state became active.
          - id: inactive
            value: "inactive"
            brief: The state became inactive.
          - id: background
            value: "background"
            brief: The state is now in the background.
```

--------------------------------

### Registry Directory Structure

Source: https://github.com/open-telemetry/weaver/blob/main/docs/specs/multi-registry/multi_registry.md

Illustrates the file and directory layout for a semantic convention registry, including the new `manifest.yaml` file.

```text
registry_root/
  domain_1/
  domain_2/
  ...
  resources/
  manifest.yaml
```

--------------------------------

### Build for Production

Source: https://github.com/open-telemetry/weaver/blob/main/ui/README.md

Creates a production build of the UI, outputting assets to the `ui/dist` directory, which is then embedded into the `weaver` binary.

```sh
pnpm build
```

--------------------------------

### Resolved Schema Example

Source: https://github.com/open-telemetry/weaver/blob/main/schemas/semconv-schemas.md

An example of a resolved schema, which is a single file containing all registry signals and refinements, optimized for distribution. It includes an attribute catalog and registry details for metrics, referencing attributes by index.

```yaml
# returned from https://acme.com/schemas/my-registry/1.0.0/resolved.yaml
file_format: "resolved/2.0"
schema_url: https://opentelemetry.io/schemas/semconv/1.{future}.0
attribute_catalog:
...
- key: my.operation.name
  type: string
  stability: development
  brief: My service operation name as defined in this Open API spec
  examples: ["get_object", "create_collection"]
...
registry:
  attributes:
  - 888   # index of `server.address` in attribute_catalog
  - 1042  # index of `my.operation.name` in attribute_catalog
  ...
  metrics:
  - name: my.client.operation.duration
    instrument: histogram
    unit: s
    attributes:
      - base: 1042  # index of `my.operation.name`
        requirement_level: required
      - base: 888   # index of `server.address`
        requirement_level: recommended
      ...
refinements:
  metrics:
  - name: my.client.operation.duration
    instrument: histogram
    unit: s
    attributes:
      - base: 1042
        requirement_level: required
        ...

```