Making Semantic Conventions Work for You With OpenTelemetry Weaver

データセットには数百の属性があります。中には自明なものもあります：http.response.status_code、server.address。一方で自明でないものもあります：meta.refinery.reason、dataset.slug, sli.latency_target_ms。属性の意味がわからなければ、適切なクエリを作成できません。また、AIエージェントが意味を理解できなければ、推測に頼ることになります。

OpenTelemetryのセマンティック規約は、この問題の一部を解決します。標準的なテレメトリ属性のための共通語彙を定義し、http.response.status_code がどのサービスや言語で生成されたかに関わらず同じ意味を持つようにします。しかし、セマンティック規約はOpenTelemetryレイヤーまでしかカバーしません。プラットフォーム固有の内部属性や組織固有のドメイン属性は文書化されておらず、それらを作成した人以外には見えません。

この記事では、OpenTelemetry Weaver がセマンティック規約スキーマを定義・階層化・検証し、人間とエージェントの両方がテレメトリ内のすべての属性に関する完全なコンテキストを得られるようにする方法を紹介します。また、Honeycombで3層レジストリを構築し、AIエージェントにデータセット内のすべてのカラムに関する情報を提供するためにどのように使用しているかも紹介します。

OpenTelemetry Weaverとは？

OpenTelemetry Weaverは、セマンティック規約を使用してテレメトリスキーマを定義・検証・進化させるためのツールセットです。基本的な考え方は、テレメトリを公開APIのように扱うことです。APIエンドポイントを文書化してバージョン管理するのと同じように、Weaverではテレメトリ属性を文書化してバージョン管理できます。

WeaverはYAMLで定義されたセマンティック規約スキーマで動作します。各スキーマは、属性のグループを名前、型、説明、安定性レベル、例とともに記述します。Weaverはこれらのスキーマをレジストリに解決します。レジストリとは、属性の意味に関する単一のクエリ可能な信頼できる情報源です。

Weaverの機能はレジストリ構築にとどまりません。スキーマから型安全なSDKを生成したり、スキーマバージョンの差分を計算して移行ガイダンスを提供したり、ライブテレメトリをスキーマに対して検証したりできます。ここではレジストリとHoneycombでの使用方法に焦点を当てます。

階層化スキーマ：OpenTelemetry、Honeycomb、そしてあなた自身のもの

Weaverの最も強力な機能の1つは、スキーマ依存関係のサポートです。すべてをゼロから定義する必要はありません。まずOpenTelemetryのセマンティック規約をベースとして使用し、その上に独自の定義を重ねていきます。

Honeycombでは3層モデルを採用しています：

1. OpenTelemetryベースは業界標準の属性をカバーします：HTTP、データベース、メッセージング、ランタイムメトリクスなど。

2. Honeycombオーバーレイは、Honeycombが取り込み時に作成するプラットフォーム固有の属性を追加します。トレースメタデータ、Refineryサンプリングフィールド、ブラウザのCore Web Vitalsなどです。

3. カスタマードメインオーバーレイ（任意）は、組織独自のドメイン固有属性を追加します。

OpenTelemetryベース

OpenTelemetryのセマンティック規約は、すべてのシグナルタイプにわたる数百の属性を定義します。Weaverはこれらを解決し、継承された属性や解決された参照を含む、完全に展開された属性を備えた自己完結型のレジストリを作成します。これが、すべてを構築するための基盤となります。

Honeycombオーバーレイ

OpenTelemetryベースの上に、Honeycomb固有の属性を記述するHoneycombスキーマを追加します。これらは、Honeycombの取り込みパイプラインがテレメトリを処理する際に作成する属性や、Honeycombがデータを整理する方法に固有の概念です。Honeycomb固有であるため、OpenTelemetry仕様には存在しません。

以下は、Honeycombのワークスペース概念を記述するスニペットです：

groups:
  - id: hny.workspace
    type: attribute_group
    brief: Honeycomb workspace concepts used as query scope identifiers
    note: >
      Honeycomb organizes data as: Team -> Environment -> Dataset -> Events.
      These identifiers are used as scope parameters in API calls and tool inputs.
    stability: stable
    attributes:
      - name: team.slug
        type: string
        brief: Unique identifier for a Honeycomb team
        note: >
          Used as a scope parameter in Honeycomb API calls.
          All data in Honeycomb is scoped to a team.
        stability: stable
        examples:
          - my-company
          - acme-corp
      - name: dataset.slug
        type: string
        brief: Unique identifier for a dataset within a Honeycomb environment
        note: >
          Datasets are collections of events within an environment.
          Each dataset has its own set of queryable columns.
        stability: stable
        examples:
          - my-service
          - frontend-events

以下は、Refineryサンプリングメタデータを記述する別のグループです：

  - id: hny.refinery
    type: attribute_group
    brief: Metadata added by Refinery during trace processing
    note: >
      These attributes are only present when traces pass through a Refinery
      instance. They are not set for traces sent directly to Honeycomb.
    stability: stable
    attributes:
      - name: meta.span_count
        type: int
        brief: Total number of spans in the trace
        stability: stable
        examples:
          - 1
          - 15
          - 200
      - name: meta.refinery.reason
        type: string
        brief: Sampling rule name that caused this trace to be kept
        stability: stable
        examples:
          - deterministic
          - dynamic/high-error-rate
      - name: meta.refinery.final_sample_rate
        type: int
        brief: Final effective sample rate applied by Refinery
        stability: stable
        examples:
          - 1
          - 10
          - 100

各属性には名前、型、簡単な説明、および例があります。noteフィールドは必要に応じてより深いコンテキストを提供します。このスキーマがなければ、dataset.slugやmeta.refinery.reasonは単なる不透明なカラム名です。これがあれば、データを見る人はその意味を正確に理解できます。

カスタマードメインオーバーレイ

3番目のレイヤーは、あなたのチームにとって最も強力なものです。OpenTelemetryは標準属性をカバーし、Honeycombはプラットフォーム属性をカバーします。しかし、あなたのビジネスドメインを最もよく知っているのはあなた自身です。

サービスがpayment.method、payment.retry_count、order.fulfillment_statusのような属性を出力する場合、それらの属性は組織にとって意味がありますが、それらを作成した人以外には見えません。ドメインスキーマは、その知識を構造化されクエリ可能な方法で文書化します。

以下は、カスタマードメインスキーマの例です：

groups:
  - id: payments
    type: attribute_group
    brief: Payment processing attributes
    stability: stable
    attributes:
      - name: payment.method
        type:
          members:
            - id: credit_card
              value: credit_card
            - id: debit_card
              value: debit_card
            - id: bank_transfer
              value: bank_transfer
            - id: digital_wallet
              value: digital_wallet
        brief: Payment method used for the transaction
        stability: stable
        examples:
          - credit_card
          - digital_wallet
      - name: payment.retry_count
        type: int
        brief: Number of times this payment was retried after a transient failure
        note: >
          A value of 0 means the payment succeeded on the first attempt.
          Higher values indicate transient failures that were recovered from.
        stability: stable
        examples:
          - 0
          - 1
          - 3
      - name: payment.provider
        type: string
        brief: Payment gateway provider handling the transaction
        stability: stable
        examples:
          - stripe
          - adyen
          - braintree

このスキーマがレジストリに読み込まれると、payment.retry_countは単なるカラム名ではなくなります。「一時的な障害後にこの支払いが再試行された回数」という意味を持ち、型、例、注釈が文書化されます。このコンテキストは、データを扱うすべての人に利用可能になります。

Honeycombはカスタムスキーマのアップロードをサポートしており、このコンテキストは常にレジストリの一部となります。

Honeycombでのレジストリの使用方法

レジストリは、OpenTelemetryの解決済みスキーマとHoneycombオーバーレイをマージして単一のインデックスとして構築されます。カスタムスキーマが設定されている場合、チームごとにその上にマージされます。

自動カラム説明

データセット内のカラムを一覧表示すると、Honeycombはカスタム説明がまだ設定されていないカラムに対して、レジストリから説明を自動的に入力します。つまり、チームの誰もカラムを手動で文書化していなくても、レジストリがコンテキストを補完します。エージェントや人間がデータセットを見ると、次のように表示されます：

- http.response.status_code は「HTTP response status code」と説明されます（OpenTelemetryから）

- meta.span_count は「Total number of spans in the trace」と説明されます（Honeycombオーバーレイから）

- payment.retry_count は「Number of times this payment was retried after a transient failure」と説明されます（ドメインスキーマから）

すでにカラムにカスタム説明を設定している場合は、それが優先されます。レジストリはギャップのみを埋めます。

より深い探索のためのMCPツール

自動説明に加えて、レジストリはHoneycombのCanvasとHoneycomb MCP serverを使用する外部エージェントの両方で利用可能なMCPツールを強化します：

attributes

これらのツールは、エージェントがカラム一覧にない属性を探索する方法を提供します。パフォーマンスの問題を調査するエージェントは、まだ見たことのない関連属性をレジストリで検索したり、属性に関する詳細な注釈を調べてクエリを作成する前にエッジケースを理解したりできます。

たとえば、Refineryメタデータをクエリするエージェントは、get_semconv_attributeをmeta.refinery.reasonで呼び出し、それが「Sampling rule name that caused this trace to be kept」であり、例としてdeterministicやdynamic/high-error-rateがあることを学習できます。このコンテキストにより、不透明なカラムに対するGROUP BYが、サンプリング動作の情報に基づいた分析に変わります。

その結果、エージェントは属性名だけで推測するのではなく、何をクエリし、結果をどのように解釈するかについて情報に基づいた判断を行えるようになります。

レジストリを超えて：Weaverのその他の機能

レジストリは基盤ですが、Weaverには他にも知っておくべき機能がいくつかあります：

- ライブチェックは、実際のテレメトリをスキーマに対して検証します。OTLPソースを指定すると、必須属性の欠落、型不一致、非推奨属性、無効な列挙値などをチェックします。CI/CDパイプラインや開発中にスキーマ違反を本番環境に到達する前に検出するのに便利です。

- コード生成は、Jinjaテンプレートを使用してスキーマから型安全なSDK、ドキュメント、その他の成果物を生成します。アプリケーションの計装を容易にします。

- スキーマ差分は、2つのレジストリバージョンの差分を計算し、規約が進化する際の移行計画に役立ちます。

これらの各機能は深く掘り下げる価値がありますが、すべてはレジストリから始まります。

独自のスキーマの作成

組織用のカスタムスキーマの定義は簡単です。ドメイン属性を関心領域ごとにグループ化して記述するYAMLを作成します。HoneycombがOpenTelemetryベースとの解決とマージを処理します。

以下は、ロジスティクスドメインの最小例です：

groups:
  - id: shipment
    type: attribute_group
    brief: Order fulfillment and shipment tracking attributes
    stability: stable
    attributes:
      - name: shipment.carrier
        type: string
        brief: Logistics carrier handling the shipment
        stability: stable
        examples:
          - fedex
          - ups
          - dhl
      - name: shipment.warehouse_id
        type: string
        brief: Identifier of the warehouse that fulfilled the order
        note: >
          Maps to the internal warehouse code. Use alongside
          deployment.environment to distinguish staging test
          warehouses from production facilities.
        stability: stable
        examples:
          - us-east-1a
          - eu-west-2b
      - name: shipment.sla_tier
        type: string
        brief: Delivery SLA tier promised to the customer
        stability: stable
        examples:
          - next-day
          - standard
          - economy

各属性には最低限、名前、型、および簡単な説明が必要です。期待される値を示す例を追加し、明白でない動作については注釈を追加します。

これをHoneycombにアップロードすると、OpenTelemetryレイヤーとHoneycombレイヤーと並んでレジストリの3番目のレイヤーになります。

はじめに

OpenTelemetry WeaverはGitHubのopen-telemetry/weaverで入手できます。opentelemetry-weaver-examplesリポジトリには、依存関係を持つカスタムレジストリの動作例があります。

Honeycombユーザーの場合は、カスタムスキーマを今日アップロードすることで、AIエージェントがデータを分析する際にドメイン属性を理解できるようになります。

セマンティック規約は、テレメトリを理解可能にするための基盤です。Weaverはそれを組み合わせ可能、クエリ可能、検証可能にします。人間とエージェントの両方が属性を見てその意味をすぐに理解できるとき、観測可能性はすべての人にとってより有用になります。

セマンティック規約のコンテキストがエージェント体験をどのように向上させるかを見てみたいですか？無料のHoneycombアカウントにサインアップしてクエリを開始するか、カスタムスキーマの設定を手伝ってほしい場合は、Developer Advocateの1人とオフィスアワーを予約してください。