Yoshi Yamaguchi

仕様書の原則

この記事は英語の原文を日本語に翻訳したものです。原文: https://opentelemetry.io/docs/specs/otel/specification-principles/

翻訳元: open-telemetry/opentelemetry-specification v1.60.0（コミット 29ae8c7）

このドキュメントは、設計者が新しい用途に対応したり問題を修正したりするためにOpenTelemetryの仕様書を作成・拡張する際に助けとなる共通の原則を定義します。

OpenTelemetryのミッションと価値観

このドキュメントは、OpenTelemetry全体の価値観の文脈で捉える必要があります。そこでは以下の中核となる価値観が示されています。

さらに、以下の中核となるエンジニアリングの価値観も示されています。

これらの中核的な価値観に加えて、仕様書の作業を通じて学んできたことがいくつかあり、それらが仕様書の書き方を導いています。

仕様書の原則

OpenTelemetry仕様書の主要な原則は以下のとおりです。

これらの原則は互いに対立することがある点に注意してください。例えば、安定性を保つことは、実現可能なシンプルさに制約を課す場合があります。これらの原則は設計を導く基準であり、仕様書への追加や変更を評価する際の指標を形成します。

それぞれをもう少し詳しく見ていきましょう。

ユーザー起点であること

仕様書は、それが可能にするエコシステムなしには無意味です。変更は、実世界の使用ケースと実際のユーザーのニーズに焦点を当てるべきです。加えて、変更はOpenTelemetryのエコシステム全体で実装可能であるべきです。

これは、提案が「ちょっとした機能を1つ追加する」のではなく「end-to-endで」考えるべきということを意味します。

プロジェクトと提案は、仕様書への変更が行われる前に、プロトタイプまたは実装を提供すべきです。

プロトタイプに関しては、いくつかの簡単な指針があります。

  • API/SDKの変更は3つの言語でプロトタイプ化すべきです。目標は特定の言語ではなく、可能なAPI設計を広く網羅することです。
    • 1つの言語は、型付きのオブジェクト指向エコシステム（Java、.NETなど）を対象とすべきです。
    • 1つの言語は、動的型付けのエコシステム（Python、JavaScript）を対象とすべきです。
    • 1つの言語は、構造的なエコシステム（Go、Rust）を対象とすべきです。
  • プロトコルの変更は、クライアント側とサーバー側の両方でプロトタイプ化すべきです。
  • プロトタイプは、マージされていないプルリクエストや既存のプロジェクトなどでも構いませんが、その機能が仕様化されれば成功するという確信を示せなければなりません。

汎用的であること

仕様書は、幅広い言語、フレームワーク、エコシステム、コミュニティにわたって実装可能である必要があります。仕様書は、OpenTelemetryのコンポーネントがそれぞれのユーザーにイディオマティックな体験を提供できるようにするべきです。

仕様書はどのようにではなく何をに焦点を当てるべきです。どのように行うかを記述する場合は、非規範的な言葉遣いや、このドキュメントのような補足のガイドラインを使ってください。

安定していること

ユーザーを、壊さない。

これは安定性についてのOpenTelemetry全体のミッションの繰り返しです。それだけ安定性が重要だということです。

「テレメトリーは組み込みであるべき」というOpenTelemetryのミッションを達成するには、ユーザーが安心して依存できるコンポーネント群を作る必要があります。不安定さは信頼を損ない、アプリケーションやライブラリの作者が標準で（out of the box）自分のソフトウェアに統合したいと思えるソリューションであろうとするミッションを損ないます。

変更が発生する場合、仕様書（および実装）は、OpenTelemetryのエコシステムにシームレスで滑らかな体験を保証するための重い作業を担うべきです。

一貫していること

OpenTelemetryで関わる機能ごとに、ユーザーに新しい概念や振る舞いを学ばせないようにします。これには3つの副原則があります。

  • シンプルで広く適用可能な機能を優先する。
  • シグナル間で類似の概念と振る舞いを優先する。
  • 可能な限り、シグナルとコンポーネント間で命名規則を再利用する。

シンプルであること

シンプルさは複雑さに勝ります。抽象化は、それに見合う価値を生むべきです。OpenTelemetryは大きなスコープと多くのコンポーネントを持っています。複雑な問題をシンプルな設計と解決策で解くことは、保守の負担をはるかに小さくし、将来の進化を容易にします。

さらに、仕様書は多くの個人によって読まれ、解釈されます。複雑な言葉遣い、微妙なニュアンスを持つ表現、不明瞭な記述は混乱を招き、しばしば意図した通りにセクションが解釈されないことによる、良くないユーザー体験につながります。