weseek__growi/.kiro/specs/opentelemetry/requirements.md

Requirements Document

Introduction

GROWI の OpenTelemetry 統合 (apps/app/src/features/opentelemetry/) を メンテナンスするための大局的な仕様。SDK ライフサイクル、Resource Attribute、Custom Metric、HTTP Anonymization の 4 レイヤがそれぞれ「何を担い、何を担わないか」を明文化し、新規メトリクスや anonymization handler の追加、SDK のバージョンアップ、設定キーの追加・改名といった将来のメンテナンス時に、本 spec を 1 か所の参照点として運用できる状態を目標とする。

本 spec は新規実装 spec ではなく、既に実装・稼働している features/opentelemetry/ の 現状の責務境界をスナップショットとして固定化する 性格を持つ。個別機能の追加・変更は原則として本 spec の Boundary Commitments の範囲内で行われ、境界をまたぐ変更が必要なときは Revalidation Triggers として再評価される。

Boundary Context

• In scope:
  • NodeSDK の起動・有効化制御・Resource 2 段階初期化 (node-sdk.ts, node-sdk-configuration.ts, node-sdk-resource.ts)。
  • Diag Logger の pino アダプタ (logger.ts)。
  • SemConv の不安定 attribute のローカルコピー (semconv.ts)。
  • identity 専用の Resource Attribute 供給 (custom-resource-attributes/)。
  • Custom Metric の emit と合成 (custom-metrics/、合計 4 モジュール: application / user-counts / page-counts / system)。
  • HTTP リクエストの best-effort anonymization (anonymization/、4 個の handler + utility)。
  • otel:* 設定キー 4 種の利用ポリシー。
• Out of scope:
  • growiInfoService / configManager / loggerFactory などの上流サービスの設計や API 変更。
  • 既存メトリクス（growi.users.total / growi.users.active / growi.pages.total / growi.configs / system.* / process.*）の名称変更や再構成。
  • OpenTelemetry のログシグナル統合（log signal は現状未使用）。
  • クライアント側（ブラウザ）からの telemetry 出力。
  • Trace span への独自 attribute 追加（http.target 以外）。
  • OTLP Exporter の wire 仕様や受信側ツールチェイン。
• Adjacent expectations:
  • 上流: growiInfoService.getGrowiInfo({ includeAttachmentInfo, includeUserCountInfo, includePageCountInfo }) の API シグネチャ・返り値型が維持されることに依存する。破壊的変更があった場合は Revalidation Triggers として custom-metrics/ および custom-resource-attributes/application-resource-attributes.ts を再評価する。
  • 上流: configManager.getConfig('otel:*') の 4 キーが現状の意味で参照可能であることに依存する。
  • 下流: OpenTelemetry Collector およびその先のダッシュボード／アラート群が本 spec の Metric Schema / Resource Attribute 表に整合した参照クエリを保持していること。変更時は PR 説明にて運用者へ通知する。

Requirements

Requirement 1: SDK ライフサイクルと有効化制御

Objective: GROWI 運用者として、OpenTelemetry SDK を環境変数 1 つで有効／無効を切り替えられ、無効時にはランタイムオーバーヘッドや誤った OTLP 接続試行が発生しないことを保証したい。

Acceptance Criteria

1. The GROWI server shall otel:enabled 設定が false のとき、NodeSDK インスタンスを生成せず Resource Attribute 取得や Custom Metric の登録も行わない。
2. The GROWI server shall otel:enabled 設定値と OTEL_SDK_DISABLED 環境変数の値が矛盾している場合、OTEL_SDK_DISABLED を上書きして整合性を取り、その旨を warn ログとして出力する。
3. The GROWI server shall NodeSDK 初期化を「SDK 構築・Resource 静的部分のセット」「DB 初期化後の Resource 追加注入」「start() 呼び出しと Custom Metric 登録」の 3 段階で行う。各段階は otel:enabled を再確認した上で実行する。
4. The GROWI server shall 同一プロセス内で initInstrumentation() を二重に呼ばれても、SDK インスタンスを重複生成しない（再初期化は警告を出してスキップする）。

Requirement 2: identity 専用 Resource Attribute

Objective: 受信側インフラ管理者として、GROWI が emit する Resource Attribute がテレメトリ発生元エンティティの identity 情報のみであり、測定値や設定値が紛れ込まないことを保証したい。

Acceptance Criteria

1. The GROWI server shall Resource Attribute として以下のみを emit する: service.name, service.version, service.instance.id（取得できた場合）, os.type, os.platform, os.arch, growi.service.type, growi.deployment.type。
2. The GROWI server shall 測定値（メモリ使用量・カウント等）および GROWI のサブシステム設定値（attachment / auth provider 種別等）を Resource Attribute として emit しない。
3. The GROWI server shall Resource Attribute の取得を 2 段階に分け、1 段階目は DB 非依存（service.name / version / OS info）、2 段階目は DB 初期化後（service.instance.id / growi.service.type / growi.deployment.type）に行う。
4. If Resource Attribute 取得処理で例外が発生した場合, the GROWI server shall 当該段階の Resource Attribute を空オブジェクトで返し、SDK 起動自体は継続する。

Requirement 3: GROWI 設定情報の info-gauge ラベル統合

Objective: 運用者として、GROWI インスタンスの設定情報（site URL、wiki type、外部認証種別、添付ストレージ種別）を 1 つの info-gauge メトリクスから一覧できることを保証したい。

Acceptance Criteria

1. The GROWI server shall growi.configs という ObservableGauge を Prometheus info パターン（値は常に 1、情報はラベルに格納）で emit する。
2. The GROWI server shall growi.configs に以下のラベルを付与する: site_url, site_url_hashed, wiki_type, external_auth_types, attachment_type。
3. If otel:isAppSiteUrlHashed が true, the GROWI server shall site_url を [hashed] リテラルにし、site_url_hashed に SHA-256 ハッシュ値を入れる。false のときは site_url に生 URL を入れ site_url_hashed は undefined（emit されない）。
4. If external_auth_types / attachment_type の値が growiInfoService から取得できない場合, the GROWI server shall 当該ラベルを空文字 '' でフォールバックする。
5. The GROWI server shall ラベル名を snake_case で統一する。

Requirement 4: 業務カウントメトリクス

Objective: 運用者として、GROWI 上の主要エンティティ（ユーザー、ページ）の総数とアクティビティ指標を継続的に観測したい。

Acceptance Criteria

1. The GROWI server shall growi.users.total メトリクスを総ユーザー数で観測する（単位 users）。
2. The GROWI server shall growi.users.active メトリクスをアクティブユーザー数で観測する（単位 users）。
3. The GROWI server shall growi.pages.total メトリクスを総ページ数で観測する（単位 pages）。
4. If growiInfoService からのカウント値取得が失敗した場合, the GROWI server shall 0 で観測するか、当該収集サイクルでの観測をスキップし、diag ロガーに error を記録する。

Requirement 5: コンテナ運用に対応したメモリ系メトリクス

Objective: コンテナ環境（Docker / Kubernetes）で GROWI を運用する管理者として、「コンテナに割り当てられたメモリ上限（cgroup limit）」「ホスト物理メモリ総量」「プロセス RSS」「V8 ヒープの使用／確保／外部メモリ」を別々のメトリクスとして観測できることを保証したい。

Acceptance Criteria

1. The GROWI server shall system.memory.limit を process.constrainedMemory() の戻り値（>0 のとき）で観測する。値が 0 または falsy のときは当該メトリクスのみ観測をスキップする。
2. The GROWI server shall system.host.memory.total を os.totalmem() の戻り値で常に観測する。
3. The GROWI server shall process.memory.usage を process.memoryUsage().rss で観測する。
4. The GROWI server shall process.runtime.v8.heap.used / process.runtime.v8.heap.total / process.runtime.v8.heap.external を v8.getHeapStatistics() および process.memoryUsage().external から観測する。
5. The GROWI server shall 上記すべてのメトリクスを単位 By（bytes）で emit する。

Requirement 6: HTTP リクエストの best-effort anonymization

Objective: プライバシ保護担当者として、otel:anonymizeInBestEffort が true のとき、ユーザーが入力した検索キーワード・ページパス・ユーザー名がトレース span の http.target に平文で残らないことを保証したい。

Acceptance Criteria

1. The GROWI server shall otel:anonymizeInBestEffort が true のとき、HTTP instrumentation の startIncomingSpanHook で anonymizationModules を順次評価し、canHandle(url) が true を返した module の handle() 結果を span attribute としてマージする。
2. The GROWI server shall 検索 API (/_api/search, /_search) の q クエリパラメータを [ANONYMIZED] に置換する。
3. The GROWI server shall page-listing API (/_api/v3/page-listing/{ancestors-children,children,item}) および page API (/_api/v3/pages/list, /_api/v3/pages/subordinated-list, /_api/v3/page/check-page-existence, /_api/v3/page/get-page-paths-with-descendant-count) の path / paths パラメータを匿名化する。
4. The GROWI server shall ページアクセス（非 API、permalink でない、創出可能なページパス）に対し、ユーザー名およびページパスを SHA-256 prefix（16 文字）でハッシュし [USERNAME_HASHED:...] / [HASHED:...] プレースホルダで置換する。permalink（ObjectId）と users top page（/user）はそのまま残す。
5. If otel:anonymizeInBestEffort が false, the GROWI server shall startIncomingSpanHook を渡さず、HTTP instrumentation の標準動作のみを行う。

Requirement 7: Diag Logger と pino の統合

Objective: 開発者として、OpenTelemetry 内部の diag ログが GROWI の通常のアプリケーションログ（pino）と同一フォーマット・同一出力先で観測できることを保証したい。

Acceptance Criteria

1. When NODE_ENV === 'development' かつ otel:enabled が true, the GROWI server shall DiagLogger を pino logger にアダプトする実装 (DiagLoggerPinoAdapter) をグローバルに登録する。
2. The GROWI server shall diag.error/warn/info/debug/verbose で受け取ったメッセージが JSON 文字列の場合に parse して構造化 data に変換し、pino の引数規約（data 第 1 引数・message 第 2 引数）に整合する形で渡す。
3. The GROWI server shall production 環境では initLogger() を呼ばない（OpenTelemetry の diag 既定動作に委ねる）。

Requirement 8: メトリクスエクスポートと SDK 設定

Objective: 運用者として、OTLP メトリクス／トレースエクスポートが OpenTelemetry SDK 標準の環境変数（OTEL_EXPORTER_OTLP_ENDPOINT 等）で制御でき、内部で勝手な default endpoint が固定されないことを保証したい。

Acceptance Criteria

1. The GROWI server shall OTLPTraceExporter および OTLPMetricExporter をコンストラクタ引数なしで生成し、エンドポイントなど exporter 設定は OpenTelemetry SDK 標準の環境変数で解決させる。
2. The GROWI server shall PeriodicExportingMetricReader の exportIntervalMillis を 300000（5 分）で初期化する。
3. The GROWI server shall auto-instrumentation のうち @opentelemetry/instrumentation-pino および @opentelemetry/instrumentation-fs を明示的に無効化する（pino: log signal を使用しないため、fs: トレース量が膨大すぎるため）。

Requirement 9: SemConv の不安定 attribute のローカルコピー

Objective: 開発者として、@opentelemetry/semantic-conventions の incubating attribute をランタイムコードから直接 import せず、本モジュール内のローカルコピーを参照することで、上流の minor リリースでの破壊的変更からアプリケーションを保護したい。

Acceptance Criteria

1. The GROWI server shall incubating attribute（service.instance.id, http.target）を semconv.ts 内に文字列定数として定義し、ランタイムコードはこれを import する。
2. The GROWI server shall @opentelemetry/semantic-conventions/incubating からの import をランタイムコードに含めない。

Requirement 10: 拡張・追加時の境界遵守

Objective: 機能を追加・変更するエンジニアとして、新規 Custom Metric や新規 Anonymization Handler を本 spec の境界に従って実装し、レイヤ責務の汚染を回避したい。

Acceptance Criteria

1. When 新規 Custom Metric モジュールを追加する, the GROWI server shall custom-metrics/ 配下にファイルを追加し、addXxxMetrics(): void をエクスポートし、custom-metrics/index.ts の setupCustomMetrics() から呼び出す。
2. When 新規 Anonymization Handler を追加する, the GROWI server shall anonymization/handlers/ 配下に AnonymizationModule 実装ファイルを追加し、handlers/index.ts の anonymizationModules 配列に登録する。
3. The GROWI server shall identity 情報を Resource Attribute 経由で、設定値を growi.configs ラベル経由で、観測値を growi.* / system.* / process.* メトリクス経由でそれぞれ emit する責務分離を維持する。