• 要約
• 動機
• Observability グループの目標
  • 目標
• タイムライン
• 提案
  • 主要コンポーネント
  • データの取り込み
  • 限界
  • クエリ API
  • 認証と作成者許可
  • データベーススキーマ
  • UIデザイン
• イテレーション

ディストリビューション・トレース機能

要約

GitLabは既にディストリビューショントレースを機能として持っています。そのため、この提案はこの機能をGAするために必要な変更に焦点を当てています。GitLabのObservability UI(GOUI) を廃止し、GitLab UIでトレースのためのネイティブUIを構築します。

この提案は、新しいUI、APIの変更、新しい方向性をサポートするためのバックエンドの変更を含む、GAでリリースされるものの範囲と技術的アプローチをカバーしています。

分散トレースはプレミアム機能としてGAされ、当初はプレミアムユーザーとアルティメットユーザーのみが利用できます。

動機

2021年12月、GitLabはOpsTraceを買収し、Observabilityの機能をDevOpsプラットフォームにインテグレーションする作業を開始しました。その時点では、GitLabから独立して実行でき、DevSecOpsプラットフォームにうまくインテグレーションできるディストリビューションを作成することを目標としていました。以前の戦略の背景については、内部限定-Argus FAQを参照してください。

2021年12月以降、世界とGitLabでは多くの変化がありました。GitLabの信念として、ObservabilityはGitLab UI内にネイティブに構築されるべきであり、機能の分断を避け、単一のUXを確保する必要があります。そのため、2021年12月にGrafanaのフォークとして始まったGitLab Observability UIを廃止します。

GitLab Observabilityのアーキテクチャと機能の多くは、Grafanaのフォークを中心に構築されました。そのため、この提案は以下のハイレベルな目標を達成するための一連の提案の一部です。

Observability グループの目標

以下のグループレベルの目的は、文脈のために含まれています。以下の目的は、この設計で完全にカバーされるものではありません。この設計はディストリビューション・トレースに焦点を当てています。ロギング、メトリクス、自動モニターなどについては、さらに設計書を作成する予定です。

タイムライン2024年12月までに以下を完了

目標

• 完全な(メトリクス、ログ、トレース)ObservabilityプラットフォームのGA - GitLab.comで利用可能なサービスのGAとセルフマネージドユーザー向けのGAを含む、トレース、メトリクス、ロギングのためのアドオンバイデフォルトセットアップ。ユーザーは、オープンソースのトレーサーを使用してマイクロサービスや分散システムをトレースすることができます。さらに、ユーザーはサンプリングのデフォルトを適切に設定したり、テールベースサンプリングのような高度なテクニックを使用したりすることができます。

• Tailored Triage Workflow - ユーザーはメトリクス、ログ、スパン/トレースの間の点を結ぶ必要があります。タイプに関係なく、すべての遠隔測定データの発見、クエリ、および接続のための設計は、ユーザーが重要なアラートとインシデントをより迅速に解決するのに役立ちます。

• Auto Monitor - 開発者が新しいプロジェクトを開始すると、そのアプリケーションは自動的にインスツルメンテーションされ、アラートが設定され、GitLabアラート管理にリンクされ、スケジュールが作成され、重要なアラートのためにインシデントが作成されます。

目標

GitLab.comのSaaSの一部として、一般的に利用可能なディストリビューション・トレース機能をリリースすること。

具体的な目標

• GitLab Observability Backendプロジェクトで実装された HTTPS 書き込み API は、OTLP (OpenTelemetry Protocol) を使って GitLab に送信されたスパンを受け取ります。ユーザーはOpenTelemetry SDKか OpenTelemetry Collectorを使ってディストリビューショントレースを収集し送信することができます。
• ID、サービス、属性、時間によるトレースのリストとフィルタリング/検索を行うUI
• トレースと対応するスパンの詳細ビューを表示するUI
• GitLabの全階層に対して、トップレベルのネームスペースごとに適切なインジェストとストレージの制限を適用します。

タイムライン

グループの目的を達成するために、GitLabがトレースを段階的に展開するためには、以下のタイムラインを満たす必要があります。

• トレース実験リリース： 16.2
• トレースベータリリース： 16.3
• トレースGAリリース： 16.4

提案

提案するアーキテクチャの多くは既に存在し、GitLab.com でオペレーションされています。分散トレースはすでに内部ベータ版として長い間運用されており、内部ユーザーもいます。これらの UX 要件が、新しい UI 戦略を生み出しました。

以下の図は、GitLab Observability Backendのアーキテクチャの概要と、GitLab UIを含むクライアントがどのようにそれとインタラクションするかを示しています。

主要コンポーネント

• ゲートキーパー：すべての受信リクエストの認証、作成者、およびレート制限の実施を担当します。NGINX-IngressはGatekeeperと直接やり取りします。
• イングレスNGINX-Ingress はすべての受信リクエストの処理に使用されます。
• ClickHouse：ClickHouseは、すべての観測データのバックストアです。
• クエリ・サービス：クエリに応じてClickHouseからデータを取得する水平スケーラブルなサービスです。
• GitLab UI：GitLab.comでホストされているUI。
• Redis：GitLab API レスポンスをキャッシュするための HA Redis クラスター。

データの取り込み

トップレベルのGitLabネームスペースごとに1つのデータインジェストパイプラインがデプロイされます。現在、私たちは_GitLabグループごとに_1つのパイプラインをデプロイ_しており、_このアーキテクチャはマルチテナントのGrafanaインスタンスの存在なしでは不必要に高価で複雑なものになっています。このマルチテナントのインジェストシステムには次のような利点があります：

• レート制限を超えて、ユーザーごとにリソース制限を強制することができ、どのユーザーも割り当てられた以上のシステムリソース（メモリ、CPU）を盗むことができません。
• OTEL Collectorインスタンスを追加することで、各ユーザーパイプラインの水平スケーリングをきめ細かく制御できます。
• GitLabサブスクリプションティアに応じたユーザーテナントの管理（例えば、クォータ、スループット、コールドストレージ、異なるデータベースへのシャードなど
• OpenTelemetry Collectorのような既製のコンポーネントを活用することで、パイプラインの複雑さを軽減し、セキュリティを強化。

パイプラインは、ユーザーがプロジェクトでエラートラッキングを有効にするのと同じように、プロジェクト設定でオブザーバビリティを有効にすることで、初めてユーザーにデプロイされます。ユーザーの名前空間内のプロジェクトでobservabilityが有効になると、パイプラインがデプロイされます。このデプロイはKubernetesのスケジューラオペレータとテナントオペレータによって自動化されます。プロビジョニングは現在 iframe を使って管理されていますが、望ましい方法は RESTful API を使ってプロビジョニングすることです。GitLab UIには、ユーザーが “observabilityを有効にする “ことを可能にするセクションがプロジェクト設定にあるでしょう。

opentelemetryコレクターは、レシーバー、プロセッサー、Exporterの優れたコミュニティ開発のために、パイプラインのコア実装として使われています。ClickHouse用のExporterがコミュニティで開発され、私たちはそれを活用するつもりです。これはトレースだけでなくメトリクスやログのインジェストへの取り組みを加速するのに役立つでしょう。

限界

各インジェストパイプラインの既存のCPUとメモリの制限に加え、以下の制限とクォータが実施されます：

• 100KB（1MBに増加する可能性あり）。トップレベルのネームスペースごとのトレース・インジェスト・レートの合計（1秒あたり
• 30日間のデータ保持
• 総ストレージ容量 TBD GB

上記の制限はすべて変更される可能性があり、トップレベルのネームスペース設定によって駆動されます。したがって、スクリプトや将来的な機能を構築して、各ユーザーまたはサブスクリプション層に対してよりダイナミックに設定することができます。この設定は、テナント・オペレータのカスタムリソースの一部になります。

インジェストレート制限は、クラウドフレアのようなシンプルでパフォーマンスの高いスライディングウィンドウレート制限を実行するために内部Redisクラスターを利用します。このためのコードは、Redisへの接続がすでに管理されているGatekeeperにあります。

データ保持と総ストレージの制限は、テナント・オペレーション内の制御ループによって実施されます。このループは、定期的にClickHouseにクエリを発行し、クォータが超過しなくなるまで、最も古い丸一日のデータを継続的に削除します。これを効率的に行うには、ClickHouseテーブルがtoDate(timestamp) を使用して日ごとにパーティショニングされていることが重要です。

クエリ API

クエリサービスに支えられたクエリAPIは、トレース/スパンをUIに返すための集中型の水平スケーラブルなコンポーネントになります。このクエリサービスの出発点としては、JaegerクエリサービスコードとJaegerクエリサービスswaggerを活用するのが良いでしょう。このクエリサービスは将来的にメトリクスとログをサポートするように拡張され、GitLab UIのvue.jsコードから直接クエリできるようになる予定です。

GAの作業範囲には2つのAPIが含まれます：

• /v1/traces この仕様に準拠
• /v1/traces/{trace_ID} この仕様に準拠

認証と作成者許可

GitLab Observability Backendは、インスタンス全体で信頼されたGitLab OAuthトークンを利用して、GitLab Observability Backend(GOB)に対してGitLabユーザーを認証するシームレスなOAuthフローを実行します。GOBは認証セッションを作成し、セッション識別子をhttp専用のセキュアなクッキーに保存します。ObservabilityのUIがGitLab.comでホストされているUIのネイティブなものになったので、新しいUIのドメインと、これまで依存していた埋め込みiframe（observe.gitLab.comの代わりにGitLab.com）に対して認証が機能するように少し調整する必要があります。

GOB認証されたAPIが消費されなければならないページのみ、GitLab UIに隠されたiframeが埋め込まれます。これにより、GitLab.comのUIは、Railsの中間プロキシレイヤーを必要とせず、プロキシとGOB間のセキュリティの低い共有トークンに依存することなく、GOB APIと直接通信することができます。このiframeは隠され、その唯一の目的はOAuthフローを実行し、GOBユーザーセッションを含むhttpのみのセキュアなクッキーを割り当てることです。このフローはシームレスで、信頼されたGitLab OAuth フローなのでユーザーから完全に隠すことができます。セッションの有効期限は現在30日ですが、これはGOBデプロイフォームで設定可能です。

この方法でGitLab.comから直接observe.gitLab.comへのリクエストを許可するには、すべてのリクエストに{withCredentials: true} 、クッキーを含める必要があります。GitLab.comがトレースデータをクエリするこれらの “readonly “APIのために、私たちはしなければなりません：

• Ingress を"NGINX.Ingress.Kubernetes.io/cors-allow-credentials": "true" と"NGINX.Ingress.Kubernetes.io/cors-allow-origin": "GitLab.com"
• Gatekeeper コンポーネントで効果的な CSRF 防御が有効になっていることを確認します (Gatekeeper はリクエストの承認に責任を持ちます)。

GitLab.comからの全てのリクエストは、observe.gitLab.comが認証するためのGOBセッションクッキーを含みます。作成者の認証はGatekeeperコンポーネントが行い、GitLabのグループ/プロジェクトメンバーシップをチェックし、適切にアクセス処理を行います。開発者以上のメンバーシップを継承している人は、そのプロジェクトのトレースUIにアクセスすることができます。

データベーススキーマ

コミュニティが開発したClickHouse用のOTELエクスポート者は、トレースとスパンを保存するためのデータベーススキーマをすでに実装しています。ClickHouseのこのブログポストでは、コミュニティが開発したエクスポートの詳細をさらに掘り下げており、私たちは提案されたスキーマ設計を出発点として、実験フェーズとベータフェーズでテストするつもりです。スキーマと対応するSQLクエリの詳細については、ブログポストを読むことをお勧めします。

UIデザイン

新しいUIは、GitLabのUXデザインスタンダードに従って、Pajamas Design Systemを使って構築されます。UI は vue.js (上のアーキテクチャ図を参照) から直接 GOB クエリサービスと対話し、{withCredentials: true} のサブドメインobserve.gitLab.com/v1/query にフェッチを送ります。これがどのように有効になっているかについては、上記の認証と認可のセクションを参照してください。

TODO Figma UIのデザインと解説

イテレーション

16.2

• グループCRにアタッチされているすべてのリソースをテナントCRにマイグレーション
• クリックハウスExporterをフォークして構築
• すべてのトレース/スパンにproject_IDを追加
• gatekeeper: メンバーシップをグループレベルではなく、プロジェクトレベルでチェック。
• トレース一覧の基本クエリサービス（フィルタリング/検索なし）
• 隠されたiframeベースのOAuthメカニズムを実装（GOUIで既に行われていることを再利用/適応させる）。
• トレースリストのUI

16.3

• フィルタリング/検索クエリサービス(トレースID、サービス、ステータス、期間最小/最大、開始/終了時間、スパン属性による)
• プロジェクトアクセストークンにread_observability とwrite_observability のスコープを追加し、プロジェクトアクセストークンをプロジェクトレベルのインジェストAPIに書き込めるようにしました。
• プロビジョニングAPI
• 既存のiframeプロビジョニングの削除
• トレース詳細のUI
• トレースのフィルタリング/検索用UI
• プロビジョニング、データ送信、UIでのクエリのための基本的なe2eテスト
• メトリクス、ダッシュボード、アラート

16.4

• 観測可能性を有効にする」ためのUI設定ページ（これはプロビジョニングAPIと相互作用します）
• 本番準備レビュー
• ドキュメンテーション完了
• GitLabNamespaceのCRをテナント（つまりトップレベルの名前空間）のみを表すように変更しました。
• グループCRと対応するコントローラを削除
• まだ追加されていないe2eテスト
• クラスターのスモークテスト