Skip to content

Make weaver.yaml more customizeable via toml and params - #1561

Merged
lmolkova merged 8 commits into
open-telemetry:mainfrom
lmolkova:add-acronyms-to-toml
Jul 5, 2026
Merged

lmolkova merged 8 commits into
open-telemetry:mainfrom
lmolkova:add-acronyms-to-toml

Conversation

@lmolkova

@lmolkova lmolkova commented Jul 3, 2026 •

Copy link
Copy Markdown
Member

To support reusable templates here open-telemetry/opentelemetry-weaver-packages#38, we need to make templates + weaver.yaml more customizable.

Several things that should be configurable by semconv repos:

  1. acronyms
  2. text maps
  3. set of sections to generate (e.g. metric / span /event registries are not rendered today in semconv or semconv-genai and I might even want to disable attribute registry in genai conventions)
  4. params (supported via CLI, not yet via toml), JQ helper options can all be configured through params, no change in this PR:
    • v2 - not configurable - templates are
    • exclude_deprecated
    • excluded_namespaces

This PR

  • adds acronyms and text maps to weaver.toml and merges them between toml and yaml giving toml priority (yaml is reusable, toml is project-specific)
  • adds when clause into weaver yaml template section that contains JQ expression that controls if this template is on.

E.g.

# weaver.yaml
  - template: span_namespace.md.j2
    when: $generate_span_registry
    filter: |-
      semconv_grouped_spans({v2: true, exclude_deprecated: $exclude_deprecated, stable_only: $stable_only, exclude_root_namespace: $exclude_root_namespace})
    application_mode: each
    file_name: "{{ ctx.root_namespace | kebab_case }}/spans.md"

Would only be triggered when $generate_span_registry is true

and

  - template: registry_readme.md.j2
    when: $generate_attribute_registry or $generate_entity_registry or $generate_span_registry or $generate_metric_registry or $generate_event_registry

would be triggered when any of generate_*_registry params is true.

Reusing JQ conditions in when to match filter.

open-telemetry/opentelemetry-weaver-packages#38 is demonstrating this version and open-telemetry/semantic-conventions-genai@main...lmolkova:semantic-conventions-genai:reusable-templates-demo shows e2e.

@lmolkova
lmolkova requested a review from a team as a code owner July 3, 2026 19:24
@lmolkova
lmolkova requested a review from Copilot July 3, 2026 19:24
@lmolkova lmolkova changed the title Add acronyms to toml Make weaver.yaml more customizeable via toml and params Jul 3, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR extends Weaver’s templating configuration model to support reusable template packages while allowing project-specific overrides via .weaver.toml, and adds conditional template execution via a new when (JQ) clause in weaver.yaml.

Changes:

  • Add project-level [template] config in .weaver.toml (acronyms + text maps) and merge it into each template package’s weaver.yaml config with TOML taking precedence.
  • Add optional when (JQ expression) on template entries to conditionally apply templates based on params/registry content.
  • Update schema/docs and add end-to-end tests covering acronym/text_map merging and when gating.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 4 comments.

Show a summary per file
File Description
tests/registry_generate.rs Adds integration tests for TOML template merges and when gating.
src/registry/update_markdown.rs Applies project-level template overrides when building template config for update-markdown.
src/registry/mod.rs Introduces apply_template_config helper to merge project template settings into forge config.
src/registry/json_schema.rs Exposes the new template section in the generated .weaver.toml schema.
src/registry/generate.rs Applies project-level template overrides when building template config for generate.
schemas/weaver-config.json Adds JSON schema for the new top-level template section.
docs/weaver-config.md Documents the new per-template when clause.
crates/weaver_forge/src/lib.rs Implements when evaluation and gating before filtering/rendering a template.
crates/weaver_forge/src/config.rs Adds when field to template config; adds merge helpers for acronyms/text maps.
crates/weaver_config/src/template.rs Defines TOML-deserializable project-level TemplateConfig.
crates/weaver_config/src/lib.rs Adds template to WeaverConfig and re-exports TemplateConfig.

πŸ’‘ Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread crates/weaver_forge/src/lib.rs Resolved
Comment thread tests/registry_generate.rs Resolved
Comment thread tests/registry_generate.rs Resolved
Comment thread tests/registry_generate.rs Resolved
@opentelemetry-pr-dashboard

Copy link
Copy Markdown

This PR has review comments. Review suggestions, whether from maintainers or automated reviewers, aren't always correct or required. Please evaluate each comment on its merits, then make sure each thread has a clear outcome.

For example, link to the commit if you applied a suggestion, explain why it wasn't applied, or ask a follow-up question.

Automation flags a PR for human review once every review thread has a reply or is marked as resolved.

Status across open PRs is visible on the pull request dashboard.

@codecov

codecov Bot commented Jul 3, 2026 •

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 96.77419% with 1 line in your changes missing coverage. Please review.
βœ… Project coverage is 82.0%. Comparing base (f0486b3) to head (eb4d43b).

Files with missing lines Patch % Lines
crates/weaver_forge/src/lib.rs 93.3% 1 Missing ⚠️
Additional details and impacted files
@@          Coverage Diff          @@
##            main   #1561   +/-   ##
=====================================
  Coverage   81.9%   82.0%           
=====================================
  Files        129     129           
  Lines      10917   10948   +31     
=====================================
+ Hits        8946    8978   +32     
+ Misses      1971    1970    -1     

β˜” View full report in Codecov by Harness.
πŸ“’ Have feedback on the report? Share it here.

πŸš€ New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • πŸ“¦ JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

@jerbly

jerbly commented Jul 3, 2026

Copy link
Copy Markdown
Member

I haven't had a detailed look at this yet but how does it fit in with the spec we agreed on here: https://github.com/open-telemetry/weaver/blob/main/docs/specs/package-vs-project-config/config-proposal.md ?

I partially completed phase 2 in the implementation plan. But did not tackle things to do with templates, this bullet in the doc for example:

  • Template defaults β€” shared settings like acronyms, template_syntax, whitespace_control, and params that apply across all template packages used by the project, overriding the package's own weaver_template.yaml defaults

Phase 3 renames the weaver.yaml to weaver_template.yaml to disambiguate too. Perhaps this PR covers the missing parts of Phase 2 and should include Phase 3?

Comment thread crates/weaver_forge/src/lib.rs Resolved
Comment thread crates/weaver_forge/src/config.rs Resolved
Comment thread crates/weaver_forge/src/config.rs Resolved
Comment thread crates/weaver_forge/src/config.rs Resolved
Comment thread crates/weaver_forge/src/lib.rs Resolved
@lmolkova

lmolkova commented Jul 4, 2026

Copy link
Copy Markdown
Member Author

I haven't had a detailed look at this yet but how does it fit in with the spec we agreed on here: https://github.com/open-telemetry/weaver/blob/main/docs/specs/package-vs-project-config/config-proposal.md ?

Phase 3 renames the weaver.yaml to weaver_template.yaml to disambiguate too. Perhaps this PR covers the missing parts of Phase 2 and should include Phase 3?

The acronyms and maps are based exactly on the proposal with a caveat that I used [templates] and not [template_defaults] because defaults is relative and confusing (weaver.yaml in reusable templates would have defaults, toml effectively overrides them).

It's part of the phase 2 and doesn't do anything from the phase 3

@jerbly jerbly left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nice! Probably just needs a changelog entry and maybe something in the docs to finish.

@lmolkova
lmolkova merged commit 0be347d into open-telemetry:main Jul 5, 2026
30 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants