OpenTelemetry 属性の命名に関する 5 つのベスト プラクティス

トラブルシューティングや事後検証の際にデータの価値を高めるには、プロパティ名がすべてのテレメトリ タイプ、ツール、サービスにわたって一貫している必要があります。

OpenTelemetry 属性の命名に関するベスト プラクティス トップ 5 から翻訳された著者の Carl Brahms は、Chronosphere カスタマー サクセス チームのメンバーであり、監視、観察、イベント管理プラットフォームで長年の経験を持っています。彼は、チームがリアルタイムのデータ洞察を発見できるように支援すること、生成型人工知能、そして...という 3 つのことに情熱を注いでいます。

OpenTelemetry (OTel) を使用した分散トレース データに関しては、データを収集するだけでは十分ではありません。データを簡単に見つけ、他のデータと関連付けられるようにするための手順を実行する必要があります。これが、適切なプロパティ命名のための標準を持つ目的です。

効果的な属性の命名は単なるベストプラクティスではありません。それは重要な要件です。データがトラブルシューティングや事後分析に役立つようにするには、プロパティ名がすべてのテレメトリ タイプ、すべてのツール、すべてのサービスにわたって一貫している必要があります。この一貫性がなければ、OTeL データの有用性は大幅に低下します。

OTel のセマンティック規則とベスト プラクティスにより、データの相互接続性、移植性が向上し、クラウド ネイティブ環境での利用可能性が高まります。コンテキスト データは、可観測性チーム内で保持するデータの中で最も有益なタイプであり、ベスト プラクティスにより、そのデータの使用と影響を最大限に高めることができます。

これらのガイドラインとベスト プラクティスは、組織が収集した追跡データから最大限の利益を得るのに役立ちます。

OTeL属性の効果的な導入を確立する

効果的で有用な OTeL 属性を実装するには、影響を受けるすべてのチームの早期の関与が重要です。導入を成功させるには、スタックのすべてのレイヤーにわたって明確で一貫した命名標準を持つことのプラスの効果について全員に教育するワークショップを開催することを検討する必要があります。一貫性は明確さを生み出し、インシデント対応とデバッグの際に重要です。

命名標準の利点を説明し、会社やアプリケーションに関連する領域に焦点を当てることで、ソフトウェアおよびシステム アーキテクトの賛同を得ます。

次に、構文、構造、例など、命名規則を概説した詳細なドキュメントを作成します。標準を改訂し、フィードバックを通じて改善し、事後に見つかったギャップに対処するためのプロセスを開発します。

OTel プロパティの命名に関するベスト プラクティス

観測可能性データを最大限に活用するには、OTel プロパティの命名規則の一部として従うべき 5 つの重要なベスト プラクティスがあります。

1. 意味的属性と説明的属性を使用する

セマンティック名は、効率的な根本原因分析に役立ちます。

• 属性が明確で、説明的であり、記述するリソース全体に適用可能であることを確認してください。 http.status_code や db.system などの名前は簡単に認識でき、問題がデータベース内か Web サービス内かを問わず、問題の性質に関する洞察をすぐに提供します。
• attribute、info、session_data などの意味のない名前は一般的すぎるため、後でテレメトリ データを分析するときに混乱を招く可能性があります。

例: app.service.version

• 属性の名前空間を定義します。

• 例：

  アプリコンポーネント名

• これは、複数のサービス チームが独自の標準プロパティを持っている場合に特に重要です。

• 属性名は短くしてください。

• 例：

  url

• エラー範囲にエラー プロパティを設定します。

• 例：

  クライアントエラー

説明的なプロパティ名を使用すると、リソースを簡単に表示し、そのコンテンツと関連性を理解するために必要なすべてのコンテキストを得ることができます。既存のセマンティック規則の優れた説明については、公式仕様を参照してください。ここでは、一般的なプロパティとシステム プロパティについて学習し、テクノロジ固有の規則を含むシグナルまたは操作タイプ (HTTP やデータベースなど) 別に整理できます。

2. 共有ライブラリの使用

既知のプロパティのライブラリを作成すると、重要なデータをカタログ化し、顧客にとって重要なデータを文書化するのに役立ちます。

複数のチームがプロパティを共有する場合は、矛盾を避けるためにプロパティを標準化することが重要です。チーム間で属性の命名規則が異なると、データの相関が困難または不可能になる可能性があります。たとえば、バックエンド チームが「latency」という名前を付け、フロントエンド チームが「duration」という名前を付けた場合、サービス間でレイテンシを比較または集計するクエリは正しく機能しません。標準化されたプロパティにより、チームは共有リソース (ダッシュボードやアラートなど) を活用し、複数のシステムやサービスにわたる分析情報を得ることができます。

3. カスタム属性を作成する

場合によっては、会社またはアプリケーションの特定の側面に合わせて新しいプロパティを作成する必要があります。これを実行する前に、OpenTelemetry プロパティ レジストリを参照して、必要なプロパティがまだ存在していないことを確認することをお勧めします。必要な属性に一致する属性がないことを確認したら、新しい属性を作成できます。作成プロセス中は、特にプレフィックスの使用に関して、OTel 属性の命名ガイドラインのヒントに従うことが重要です。

属性名にプレフィックスを使用すると、カスタム属性名を標準名、他のプロジェクトで選択された名前、または協力しているベンダーや会社で選択された名前と区別しやすくなります。カスタム属性が誤って別の属性と名前を共有している場合、誤った結論や決定、ダッシュボードやアラートの欠陥につながり、トランザクションのフローやステータスの追跡が困難になる可能性があります。

他のプロジェクト、ベンダー、または企業との競合を避けるには、io.chronosphere.myapp のように、会社のドメイン名に基づいたプレフィックスを逆順で使用することを検討することをお勧めします。

名前がアプリケーション外部では決して使用されず、社内でのみ使用されることが確実な場合でも、プレフィックスを付けるということは競合を防ぐ重要な手段です。 bluebook.widget_count など、アプリケーションまたはプロジェクトに関連付けられたプレフィックス名の使用を検討してください。

OpenTelemetry や他のプロジェクトやベンダーに属する既存のプレフィックスを活用することもできます。プレフィックスを共有すると、その後の名前の競合につながる可能性があり、インシデント発生時に同僚が他の人のデータを自分のデータから分離する方法を見つけるのに苦労することになります。

4. サービスレベルに重点を置く

追跡に適用する属性を決定するときは、アプリケーションの目的は顧客に高品質のソフトウェア エクスペリエンスを提供することであることを忘れないでください。このミッションは、サービス/アプリケーションのサービス レベル目標 (SLO) に、おそらく 99.999% の稼働率の期待値という形でエンコードされます。 SLO から、どのサービス レベル インジケーター (SLI) が SLO の達成を最もサポートしているか、または最も脅かしているかを絞り込むことができます。プロパティはサービス レベルをサポートする必要があります。

たとえば、トラフィックの異なるセグメント間にレイテンシ SLO がある場合、ProductID、FeatureID、RegionID などのセグメント ディメンションを提供する属性を使用すると、それに応じてアラートを整理できます。

5. 新しいユースケースを考える

プロパティは、分散システムにおけるパターン マッチングのルートであると考えてください。カテゴリやクラス間の関係を調査したい場合、属性は並べ替えや比較のためのツールとなります。

さまざまなプロパティを徐々に試して、何が起こるかを確認します。例を考えてみましょう。

プレミアム顧客は請求書のエラーについてサポートに問い合わせていますか?注文サービスは数分前に新しいバージョンをデプロイしませんでしたか? service.version や membership.level などのプロパティを比較し、サービス名 order のエラー メトリックを相関させることで、プレミアム メンバーシップのエラー率の増加が、新しいバージョンの order サービスと高い相関関係にあるかどうかを判断するのに役立ちます。

便利なプロパティタイプ

OpenTelemetry の標準プロパティの開発には多くの慎重な検討が払われており、リストは常に進化しています。ここですべてのカテゴリを挙げることは不可能ですが、社内の命名基準を策定する際には既存のものを調べ、回帰を調査する際にはチームにとって役立ったものを強調すると役立ちます。レジストリからの例をいくつか示します。

• 一般プロパティ: 一般プロパティは、全体的な環境とネットワークに関する広範なコンテキスト情報を提供します。

server.address: サーバーのアドレス。

destination.address: 宛先のアドレス。

network.carrier.name: ネットワークキャリアの名前。

code.filepath: コードのファイルパス。

• メッセージ システム: メッセージ処理の問題を追跡および診断するのに役立つメッセージ システムに関連するプロパティ。

• メッセージングの送信先:

  メッセージが公開される論理エンティティについて説明します。

• messagesing.kafka.consumer.group:

  メッセージを処理する Kafka コンシューマー グループ。

• メッセージング.メッセージ本文.サイズ:

  メッセージ本文のサイズ（バイト単位）。

• HTTP: HTTP リクエストと応答をトレースし、Web トランザクションに関する洞察を提供するために不可欠です。

• http://www.google.com/dp/b/link/?linkid=1500000&linkcode=1

  完全な HTTP リクエスト URL。

• http.ステータスコード:

  HTTP 応答ステータス コード。

• ユーザーエージェントオリジナル:

  クライアントの HTTP User-Agent ヘッダーの値。

• リソース属性: これらの属性は、サービス、インフラストラクチャ、および運用環境に関する詳細なコンテキストを提供します。

• サービスバージョン:

  サービスのバージョン。

• k8s.クラスター名:

  Kubernetes クラスターの名前。

• gcp.gce.インスタンス名:

  Google Compute Engine インスタンスの名前。

• aws.ecs.コンテナ:

  ECS コンテナの Amazon リソース名 (ARN)。

その事件はどうなったんですか？

見落とされがちな、span イベント ログと呼ばれる特別なタイプの span 属性があります。スパンのイベントはログと非常に似ていますが、トランザクションの問題のトラブルシューティングを行うときに非常に役立つコンテキスト情報を配置するのに適した場所です。

スパンのイベント ログに何を入れるかを検討するときは、ペイロードからプライベート ユーザー データを削除し、発生した事象の簡単な概要、例外や完全なエラー メッセージ、追加のコンテキスト情報など、スパン内で発生したイベントを追加する必要があります。

避けるべき属性の実践

これまでは属性の「方法」に焦点を当ててきましたが、ここでは回避すべき属性の落とし穴について詳しく見ていきます。

• errorcode などのわかりにくい意味属性名を使用すると、混乱が生じ、情報の取得が困難になります。
• 業界内の他のアプリケーションにその名前が適切であると思われる場合を除き、otel.* 名前空間を使用してください。この場合、新しい名前をセマンティック規則に追加する提案を送信できます。
• 将来誰かにとって役に立つかもしれないように見えても、使用しないプロパティを作成します。プロパティが有用であるという確固たる証拠がない限り、現時点では追加しない方がよいでしょう。
• スタック トレース、uuid (一意のユーザー ID)、または例外情報をカスタム プロパティに配置します。発生した場合は、スパンのイベントとしてログに記録することをお勧めします。イベントの名前は「例外」にする必要があります。詳細については、仕様の例外セクションを参照してください。
• 重複したプロパティ キー - 同じスパンでキーを上書きするか、異なる名前で 2 つの同一の値を持ちます。属性キーが重複すると競合が発生し、データが上書きされる可能性があります。また、クエリと分析も複雑になります。
• 値が設定されていないか空です。値が設定されていない場合、有用な情報は提供されません。値のない属性はストレージスペースを占有しますが、トラブルシューティングや分析には役立ちません。また、合計を歪めることによって分析を歪める可能性もあります。これも混乱を引き起こす可能性があります。

OpenTelemetry のドキュメントにはさらに多くの有用な情報とアドバイスが記載されているため、属性標準が開発されるたびに最新の仕様を参照することをお勧めします。

結論は

追跡データ収集は、可観測性の重要な部分です。しかし、そのためには、データが有用で、アクセスしやすく、洞察に富んでいることを保証するプロセスを確立する必要があります。命名規則には事前にいくらかの作業が必要ですが、意味の明確さの確保、統合リポジトリの維持、データの理解、サービス レベルとの整合、新しいユース ケースの予測に至るまで、これらのベスト プラクティスを採用することで、チームはテレメトリの有用性を高めることができます。

このアプローチはトラブルシューティングを簡素化するだけでなく、組織内で効果的な観察文化を確立するのにも役立ちます。この作業の結果、アクセス可能な洞察が満載の豊富な OTeL データセットが得られ、よりスマートで迅速な意思決定が可能になります。