otel-weaver

OpenTelemetry Weaver

組織が上流の OTel の上に独自のセマンティック規約を定義し、そこから言語バインディングを生成する場合に、このスキルを使用します。

使用方法：

• otel-semantic-conventions と併用し、上流にすでに存在し、ローカルレジストリで再宣言すべきでない属性を判断します
• 最新の Weaver バージョン：Weaver が掲載されている場合は otel-sdk-versions インデックス、そうでない場合は https://github.com/open-telemetry/weaver/releases。references/ci-integration.md には、オフラインでの回答に使える、日付入りの Weaver／semconv 互換性記録があります

関連スキルを利用できない場合：

• 作業を中断しないでください
• 公式ソースで確認できるガイダンスを、記憶だけに頼って回答しないでください
• Weaver リポジトリ、schemas/semconv-syntax.v2.md、および docs/usage.md ／ docs/validate.md を参照してください
• 使用した代替手段を明示し、未検証の項目は未解決のままにしてください

基本的な考え方

構成要素は 3 つです。

1. レジストリ — YAML ファイルのディレクトリです。manifest.yaml は必須で、その schema_url（OTel スキーマ URL 形式：http[s]://host/path/<version>）はレジストリの名前を示し、末尾のパスセグメントにバージョンを保持します。依存関係のエントリにも schema_url と、任意の registry_path が必要です。それ以外では attributes、metrics、spans、events、entities を宣言します。schema_url のバージョンセグメントは自分で管理し、変更のたびに更新してください。（semconv_version と schema_base_url は schema_url に置き換えられ、非推奨です。トップレベルの name は v0.26.1 のマニフェストフィールドではありません。）
2. テンプレート — MiniJinja ファイルのディレクトリです（Jinja2 と互換性がありますが、Jinja2 の全機能を備えているわけではありません。v0.22.0 以降、自動エスケープはデフォルトで無効であり、ループ内の break ／ continue がサポートされています）。また、対象言語ごとに weaver.yaml を用意し、実行するテンプレート、適用するフィルター、application_mode、出力ファイル名を指定します。
3. ポリシー — Regorus（OPA 互換）エンジンで評価される Rego ルールで、4 つのパッケージがあります。before_resolution（解析済みの未処理グループ。--v2 ではサポートされず、スキップされます）、after_resolution（解決済みレジストリ）、comparison_after_resolution（--baseline-registry を渡した場合のみ）、live_check_advice（live-check 中、サンプルごと）です。組み込みの OTel ポリシーが最低限の基準となり、カスタムポリシーを重ねて組織固有のルールを適用します。

この 3 つの要素で、独自に作成した const.go（またはそれに相当するもの）を置き換えます。定数ブロックはレジストリになり、それを書く作業はコード生成に置き換わり、暗黙知はポリシーになります。

譲れないルール

• https://github.com/open-telemetry/weaver#install に記載されているいずれかの方法（リリースバイナリ、otel/weaver:vX.Y.Z Docker イメージ、または setup-weaver GitHub Action）で Weaver をインストールしてください。brew install weaver は実行しないでください。無関係な Scribd のツールがインストールされます。
• 上流の semconv 属性は再定義せず、ref で参照してください。境界ドメイン（http、db、messaging、rpc、network、gen-ai など）は、ローカルレジストリではなく上流の OTel semconv に属します。実行時には、それらの属性に言語 SDK の semconv パッケージを使用してください。
• すべての属性とシグナルの定義には stability が必要です。v2 構文ガイドの要件に従い、列挙型のメンバーにも指定してください。Weaver v0.26.1 は、定義に stability がない場合はエラーにしますが、通常モードでは列挙型メンバーの stability がない場合は致命的でない警告のみを報告します。
• v2 では、属性参照で brief、note、examples、annotations などのフィールドは詳細化できますが、stability や deprecated は変更できません。これらは常に属性定義から取得されます。
• 組織内の属性、メトリクス、スパンには、ドメインプレフィックス（例：ecommerce.、acme.）を使用してください。
• 生成された出力には、言語フォーマッター（gofmt -w、prettier、ruff format など）を実行してください。Jinja の空白処理により複数の空行が生成されるため、フォーマットしないと CI の差分チェックで誤って失敗します。
• テンプレートを作成する前に、解決後のスキーマ形状を確認してください。definition/2 レジストリでは、グループ化された jq ヘルパーを {"v2": true} とともに呼び出してください。v2 テンプレートの ctx には、属性の key、メトリクスの name、スパンの type／kind と構造化された span.name.note、さらにエンティティの type／identity／description などのフィールドが保持されます。正確な形状の出力方法については、references/template-authoring.md を参照してください。

ワークフロー

1. Weaver をインストールするか、場所を確認します。 https://github.com/open-telemetry/weaver#install の上流のインストール手順に従い、バージョンを固定したリリースバイナリ、otel/weaver:vX.Y.Z Docker イメージ、または setup-weaver GitHub Action を選択してください。CI と再現可能なローカル実行には Docker を使用してください。
2. レジストリを作成します。 必須なのは manifest.yaml と、属性、属性グループ、メトリクス、スパン、イベント、またはエンティティを宣言する 1 つ以上の definition/2 YAML ファイルです。references/registry-authoring.md を参照してください。
3. テンプレートを作成します。 templates/registry/<lang>/ 以下に言語ごとのターゲットディレクトリを作成し、weaver.yaml と *.j2 を配置してください。references/template-authoring.md を参照してください。
4. 検証して生成します。 素早くフィードバックを得るには、weaver registry check --v2 -r ./telemetry/registry/ を実行してください。コードを生成するには、weaver registry generate --v2 --registry ./telemetry/registry/ --templates ./telemetry/templates/ <lang> <output-dir> を実行してください。出力には言語フォーマッターを実行してください。
5. CI に組み込みます。 3 つのゲートがあります。check（スキーマ）、generate と git diff --exit-code（チェックイン済みコードが最新であること）、ベースブランチとの差分（破壊的変更を検出）です。references/ci-integration.md を参照してください。

Weaver CLI には、このワークフローで扱う以外にも多くのサブコマンドがあります。レジストリの簡易チェックには stats と json-schema、ドキュメント内の semconv の抜粋を最新に保つには update-markdown、ライブの OTLP テレメトリを扱うには emit／live-check／infer、自己完結型の解決済みレジストリアーティファクト（非推奨の resolve の後継）を書き出すには package、LLM ツールにレジストリを公開するには mcp、HTTP＋UI モードには serve を使用できます。これらはここでは対象外ですが（以下を参照）、check／generate／diff が機能のすべてだと思い込む前に、存在を知っておくとよいでしょう。

注意点

時間がかかり、上流ドキュメントからは分かりにくい点です。

1. brew install weaver では、別のツールがインストールされます。GitHub のリリースまたは Docker を使用してください。
2. 生成された出力はフォーマッターで整形された状態ではありません。weaver registry generate の後には、必ず言語のフォーマッターを実行してください。
3. Jq ヘルパーのデフォルトは、レガシースキーマを対象としています。definition/2 では {"v2": true} を渡し、保持される v2 フィールド（属性の key、メトリクスの name、スパンの type``/kindとspan.name.note、さらにエンティティの type/`identity/description）を使用してください。テンプレートを書く前に、必ずフィルタリング済みの ctx を生成して確認してください。
4. comment Jinja フィルターはキーワード引数を取ります：attr.brief | comment(format="go")。// のプレフィックスはすでに出力されるため、追加しないでください。
5. 属性、メトリクス、スパン、イベント、エンティティには、それぞれグループ化済みの jq フィルター（semconv_grouped_attributes、semconv_grouped_metrics、semconv_grouped_spans、semconv_grouped_events、semconv_grouped_entities）が用意されています。definition/2 では、たとえば semconv_grouped_spans({"v2": true}) を折りたたみ形式の YAML スカラーとして使用してください。引数なしのヘルパーは、デフォルトでレガシースキーマを選択します。
6. weaver registry check は、カスタム v2 定義ファイルに対して「File format definition/2 is not yet stable」（警告）を出力します（references/ci-integration.md の日付付き記録でも同様です）。これは通常の動作であり、失敗として扱わないでください。
7. --future は明示的に指定する必要がありますが、カスタム v2 レジストリでは definition/2 の不安定性に関する警告をエラーに引き上げます。形式が安定するまでは指定しないでください。
8. generate の CLI 引数の順序では、ターゲットディレクトリ名は位置引数として --registry と --templates の後に置きます。出力ディレクトリはその後に続きます。--templates には、言語固有のサブディレクトリではなく、ターゲットディレクトリを含む親ディレクトリを指定します。
9. レジストリ内のスパン名と実行時のスパン名について：必須のスキーマフィールドは、type、kind（client/server/producer/consumer/internal）、brief、stability、および構造化された name: { note: "..." } です。内部ビジネススパンでは、ドット区切りの型識別子を name.note に入れ、実行時には解決済みの span.name.note 文字列を出力する方法がすっきりしています。
10. ローカルレジストリに含めないもの。 DB、HTTP、メッセージング、RPC、ネットワーク、GenAI などの境界スパン／属性は、上流の OTel セマンティック規約に従います。上流の規約をマニフェスト依存関係として取り込むまでは、これらの計装では言語 SDK のセマンティック規約パッケージを直接参照してください。これは最もよくあるモデル化の間違いです。
11. Counter と UpDownCounter の名前には、_total を追加しないでください。これは semconv v1.44.0 の命名規則です。
12. 時間の長さを測るインストゥルメントでは、semconv v1.44.0 の単位ガイダンスに従い、秒（s）を使用してください。

必要に応じて読み込む参考資料

• レジストリ YAML フィールドのリファレンス：references/registry-authoring.md
• Jinja2 のパターン、jq フィルター、解決済みの形状の早見表：references/template-authoring.md
• すぐに利用できる GitHub Actions の例と、日付付きのバージョン互換性記録：references/ci-integration.md
• 手動管理の定数からレジストリへの移行手順：references/migration-playbook.md
• セマンティック規約スキル：otel-semantic-conventions
• 手動計装スキル：manual-instrumentation

対象外

次の項目は自然な次のステップですが、このスキルの対象ではありません。

• 下流の利用者向けにレジストリをバージョン付きアーティファクトとして公開すること（weaver registry package）
• 上流のセマンティック規約をマニフェスト依存関係として宣言すること
• ライブ OTLP テレメトリに対する weaver registry live-check/emit/infer
• weaver registry mcp / weaver serve
• 組み込み以外のカスタム Rego ポリシー
• ヘルパー関数のコード生成（MyMetricName(meter) ラッパー）

検証契約

Weaver レジストリ、テンプレート、または CI 統合を作成または変更した場合は、次の手順を実施してください。

• 完了前に、変更したファイルを再度開いて確認します。
• definition/2 レジストリに対して weaver registry check --v2 を実行し、結果を記録します。
• weaver registry generate --v2 と言語フォーマッターを実行し、その後 git diff --exit-code がクリーンであることを確認します。
• 該当する各項目を、コードベースの根拠とともに確認します。

最終確認結果には、次の記号を使用してください。

• [x] 完了
• [~] 該当なし（理由を記載）
• [ ] 未解決

次の項目を使用してください。

• レジストリに manifest.yaml があり、schema_url の末尾のパス要素がバージョンになっている
• すべての定義と列挙型メンバーに stability がある
• 組織固有の属性／メトリクス／スパンにドメインプレフィックスが付いている
• 境界ドメイン（http/db/messaging/rpc/network/gen-ai）の項目がローカルで重複定義されていない
• Counter と UpDownCounter の名前に _total サフィックスが付いていない
• duration ヒストグラムで s（秒）を使用している
• テンプレートが、解決済みスキーマに一致する jq フィルターを使用している（definition/2 では、事前構築済みの semconv_grouped_* ヘルパーを {"v2": true} とともに呼び出す）
• 生成された出力がフォーマッターに準拠している
• CI で check、generate と git diff --exit-code、およびベースブランチとの差分確認を実行している
• 変更したファイルを再度読み直している
• 残っているリスクや不足事項を明記している