可観測性

GitLab可観測性 (O11y) を使用して以下を行います:

• 統合された可観測性ダッシュボードを通じてアプリケーションのパフォーマンスをモニタリングします。
• 単一のプラットフォームで分散トレーシング、ログ、メトリクスを表示します。
• アプリケーションのパフォーマンスのボトルネックを特定し、トラブルシューティングを行います。

可観測性をGitLab自体に追加することで、ユーザーはこれらの（計画された）機能を利用できるようになります。

概要については、GitLab Experimental Observability (O11y) Introductionを参照してください。

GitLab O11yの興味深い使用方法に関する会話に、GitLab O11y Discordチャンネルで参加してください。

GitLabの可観測性を選ぶ理由

• Cost-effective open source model（費用対効果の高いオープンソースモデル）: 可観測性をあらゆる規模のチームが利用できるように、シート単位のライセンスではなく、コンピューティングリソースに対してのみ料金を支払います。機能や修正に直接コントリビュートすることで、プラットフォームが特定のニーズを満たすように進化することを保証できます。
• Simplified access management（簡素化されたアクセス管理）: 新しいエンジニアは、コードリポジトリへのアクセス権を取得すると、自動的に本番環境の可観測性データへのアクセス権を取得し、時間のかかるプロビジョニングプロセスを排除できます。この統合されたアクセスモデルにより、チームメンバーは管理上の遅延なしに、トラブルシューティングやモニタリングの取り組みにすぐにコントリビュートできるようになります。
• Enhanced development workflow（強化された開発ワークフロー）: 開発者はコードの変更をアプリケーションのパフォーマンスメトリクスと直接関連付けることができるため、デプロイでイシューが発生した場合でも簡単に特定できます。このコードコミットとランタイムの動作間の緊密なインテグレーションにより、デバッグが迅速化され、平均解決時間が短縮されます。
• Shift-left observability（シフトレフト可観測性）: チームは、可観測性データを開発プロセスに統合することで、開発サイクルのできるだけ早い段階でパフォーマンスのイシューやアノマリを検出できます。このプロアクティブなアプローチにより、問題の修正にかかるコストと影響が軽減されます。オープンソースの性質により、本番環境の可観測性をミラーリングする包括的なステージング環境をより簡単かつ費用対効果の高い方法でオーケストレーションを行うことができます。
• Streamlined incident response（合理化されたインシデント対応）: イシューが発生した場合、チームは最近のデプロイ、コードの変更、および関係する開発者に関するコンテキストをより迅速に把握し、より迅速なトリアージと解決を支援できます。このインテグレーションは、コードと運用データの両方に対して、単一の画面を提供します。
• Data next to decisions（意思決定に役立つデータ）: リアルタイムのパフォーマンスメトリクスとユーザーの行動データが開発環境でアクセスできるようになり、チームは機能の優先順位、技術的負債、および最適化の取り組みについて情報に基づいた意思決定を行うことができます。
• Compliance and audit trails（コンプライアンスと監査証跡）: このインテグレーションにより、コードの変更をシステムの動作にリンクする包括的な監査証跡が作成されます。これは、コンプライアンス要件およびインシデント後の分析に役立ちます。
• Reduced tool switching（ツール切り替えの削減）: 開発チームは、使い慣れたGitLab環境を離れることなく、モニタリングデータ、アラート、パフォーマンスのインサイトにアクセスできるため、生産性の向上と認知的オーバーヘッドの削減に役立ちます。

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'

OpenTelemetry::SDK.configure do |c|
resource = OpenTelemetry::SDK::Resources::Resource.create({
'service.name' => 'your-service-name',
'service.version' => '1.0.0',
'deployment.environment' => 'production'
})
c.resource = resource

c.add_span_processor(
OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
OpenTelemetry::Exporter::OTLP::Exporter.new(
endpoint: 'YOUR_OTEL_ENDPOINT_URL'
)
)
)
end

sudo mkdir -p /mnt/data
sudo mount /dev/xvdbb /mnt/data  # Replace xvdbb with your volume name
sudo chown -R $(whoami):$(whoami) /mnt/data

echo '/dev/xvdbb /mnt/data ext4 defaults,nofail 0 2' | sudo tee -a /etc/fstab

sudo apt update
sudo apt install -y docker.io docker-compose
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $(whoami)

sudo dnf update
sudo dnf install -y docker
sudo systemctl enable docker
sudo systemctl start docker
sudo usermod -aG docker $(whoami)

newgrp docker

sudo mkdir -p /mnt/data/docker
sudo bash -c 'cat > /etc/docker/daemon.json << EOF
{
  "data-root": "/mnt/data/docker"
}
EOF'
sudo systemctl restart docker

docker info | grep "Docker Root Dir"

cd /mnt/data
git clone -b main https://gitlab.com/gitlab-org/embody-team/experimental-observability/gitlab_o11y.git
cd gitlab_o11y/deploy/docker
docker-compose up -d

COMPOSE_HTTP_TIMEOUT=300 docker-compose up -d

http://[your-instance-ip]:8080

GitLabで可観測性を使用する

GitLab O11yを構成した後、GitLabに埋め込まれたダッシュボードにアクセスするには:

1. 左側のサイドバーで、検索または移動先を選択し、機能フラグが有効になっているグループを見つけます。
2. 左側のサイドバーで、可観測性を選択します。

左側のサイドバーに可観測性が表示されない場合は、http://<gitlab_instance>/groups/<group_path>/-/observability/servicesに直接アクセスしてください。

テレメトリデータをGitLabの可観測性に送信する

OpenTelemetry SDKを使用してサンプルテレメトリデータを送信することにより、GitLab O11yのインストールをテストできます。この例ではRubyを使用していますが、OpenTelemetryには多くの言語のSDKがあります。

前提要件:

• Rubyがローカルマシンにインストールされていること

• 必要なgem:

  gem install opentelemetry-sdk opentelemetry-exporter-otlp

基本的なテストスクリプトを作成する

次のコンテンツを含むtest_o11y.rbという名前のファイルを作成します:

require 'opentelemetry/sdk'
require 'opentelemetry/exporter/otlp'

OpenTelemetry::SDK.configure do |c|
  # Define service information
  resource = OpenTelemetry::SDK::Resources::Resource.create({
    'service.name' => 'test-service',
    'service.version' => '1.0.0',
    'deployment.environment' => 'production'
  })
  c.resource = resource

  # Configure OTLP exporter to send to GitLab O11y
  c.add_span_processor(
    OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
      OpenTelemetry::Exporter::OTLP::Exporter.new(
        endpoint: 'http://[your-o11y-instance-ip]:4318/v1/traces'
      )
    )
  )
end

# Get tracer and create spans
tracer = OpenTelemetry.tracer_provider.tracer('basic-demo')

# Create parent span
tracer.in_span('parent-operation') do |parent|
  parent.set_attribute('custom.attribute', 'test-value')
  puts "Created parent span: #{parent.context.hex_span_id}"

  # Create child span
  tracer.in_span('child-operation') do |child|
    child.set_attribute('custom.child', 'child-value')
    puts "Created child span: #{child.context.hex_span_id}"
    sleep(1)
  end
end

puts "Waiting for export..."
sleep(5)
puts "Done!"

[your-o11y-instance-ip]をGitLab O11yインスタンスのIPアドレスまたはホスト名に置き換えます。

テストを実行する

1. スクリプトを実行します:

   ruby test_o11y.rb

2. GitLab O11yダッシュボードを確認します:

   • http://[your-o11y-instance-ip]:8080を開きます
   • 「サービス」セクションに移動します
   • 「test-service」サービスを探します
   • それを選択して、トレーシングとスパンを表示します

アプリケーションをインストルメントする

アプリケーションにOpenTelemetry計測を追加するには:

1. 言語のOpenTelemetry SDKを追加します。
2. GitLab O11yインスタンスを指すようにOTLPエクスポーターを構成します。
3. 操作とメタデータを追跡するために、スパンと属性を追加します。

言語固有のガイドラインについては、OpenTelemetryドキュメントを参照してください。

GitLab可観測性テンプレート

GitLabは、可観測性を迅速に開始できるように、事前に構築されたダッシュボードテンプレートを提供します。これらのテンプレートは、Experimental Observability O11y Templatesで入手できます。

利用可能なテンプレート

Standard OpenTelemetry dashboards（標準のOpenTelemetryダッシュボード）: 標準のOpenTelemetryライブラリでアプリケーションをインストルメントする場合は、これらのプラグアンドプレイダッシュボードテンプレートを使用できます:

• アプリケーションパフォーマンスモニタリングダッシュボード
• サービス依存関係の可視化
• エラー率とレイテンシーの追跡

GitLab-specific dashboards（GitLab固有のダッシュボード）: GitLab OpenTelemetryデータをGitLab O11yインスタンスに送信する場合は、これらのダッシュボードを使用して、すぐに使用できるインサイトを得ます:

• GitLabアプリケーションパフォーマンスメトリクス
• GitLabサービスのヘルスモニタリング
• GitLab固有のトレーシング分析

CI/CD observability（CI/CD可観測性）: このリポジトリには、GitLab O11y CI/CDダッシュボードテンプレートJSONファイルで動作するOpenTelemetry計測を備えた、サンプルGitLab CI/CDパイプラインが含まれています。これにより、CI/CDパイプラインのパフォーマンスをモニタリングし、ボトルネックを特定できます。

テンプレートを使用する

1. リポジトリからテンプレートを複製またはダウンロードします。
2. サンプルアプリケーションダッシュボードのサービス名を、サービス名と一致するように更新します。
3. JSONファイルをGitLab O11yインスタンスにインポートします。
4. アプリケーションをインストルメントするセクションで説明されているように、標準のOpenTelemetryライブラリを使用してテレメトリデータを送信するようにアプリケーションを構成します。
5. ダッシュボードは、GitLab O11yのアプリケーションのテレメトリデータで使用できるようになりました。

トラブルシューティング

GitLab可観測性インスタンスのイシュー

コンテナのステータスを確認します:

docker ps

コンテナログを表示します:

docker logs [container_name]

メニューが表示されない

1. 機能フラグがグループに対して有効になっていることを確認します:

   Feature.enabled?(:observability_sass_features, Group.find_by_path('your-group-name'))

2. O11Y_URL環境変数が設定されていることを確認します:

   group = Group.find_by_path('your-group-name')
   group.observability_group_o11y_setting&.o11y_service_url

3. ルートが適切に登録されていることを確認します:

   Rails.application.routes.routes.select { |r| r.path.spec.to_s.include?('observability') }.map(&:path)

デバッグに関する問題

SSH接続の問題が発生している場合、またはパフォーマンスが低下している場合:

• インスタンスタイプが最小要件（2 vCPU、8 GB RAM）を満たしていることを確認します
• より大きなインスタンスタイプへのサイズ変更を検討してください
• ディスク容量を確認し、必要に応じて増やしてください

テレメトリが表示されない

テレメトリデータがGitLab O11yに表示されない場合:

1. セキュリティグループでポート4317および4318が開いていることを確認します。

2. 次のコマンドで接続をテストします:

   nc -zv [your-o11y-instance-ip] 4317
   nc -zv [your-o11y-instance-ip] 4318

3. コンテナログにエラーがないか確認します:

   docker logs otel-collector-standard
   docker logs o11y-otel-collector
   docker logs o11y

4. gRPC（4317）の代わりにHTTPエンドポイント（4318）を使用してみてください。

5. OpenTelemetryのセットアップに詳細なデバッグ情報を追加します。