マーケットプレイス連携
マーケットプレイスでは、外部サービスをArchylに接続し、そのデータをアーキテクチャダッシュボード上のライブウィジェットとして表示できます。デプロイメントの監視、コード品質の追跡、メトリクスの監視、セキュリティアラートのレビューを、すべてC4モデルと並べて直接行えます。
概要
マーケットプレイス連携は3つの層で動作します。
- プロダクト — 連携可能な外部サービス（Datadog、GitHub、SonarQubeなど）
- 接続 — プロダクトのAPIで認証するための、組織スコープの認証情報
- ウィジェット — プロジェクトダッシュボードに配置し、接続から取得したライブデータを表示するビジュアルカード
1つの接続で、異なるプロジェクトにある複数のウィジェットを動かせます。ウィジェットは30秒ごとに自動更新されます。
対応プロダクト
Datadog
インフラストラクチャとアプリケーションの健全性を監視します。
| ウィジェット | タイプ | 説明 |
|---|---|---|
| モニターステータス | ステータス | タグで絞り込んだDatadogモニターの健全性 |
| メトリクスクエリ | カウンター | Datadogメトリクスクエリの現在値 |
| アクティブアラート | リスト | 現在トリガーされているモニターの一覧 |
| 埋め込みダッシュボード | 埋め込み | 埋め込まれたDatadogダッシュボードまたはノートブック |
GitHub
リポジトリ、ワークフロー、セキュリティの検出結果を追跡します。
| ウィジェット | タイプ | 説明 |
|---|---|---|
| ワークフローステータス | ステータス | 最新のCIワークフロー実行の状態 |
| オープンプルリクエスト | リスト | ステータスバッジ付きのアクティブなPR |
| リポジトリ統計 | カウンター | スター数、フォーク数、オープンなIssue数、またはオープンなPR数 |
| Dependabotアラート | リスト | オープンな依存関係の脆弱性アラート |
| Dependabotステータス | ステータス | Dependabotアラート全体の重大度 |
| シークレットスキャンアラート | リスト | リポジトリで検出されたシークレット |
| コードスキャンアラート | リスト | CodeQLまたはサードパーティのコードスキャンの検出結果 |
| コードスキャンステータス | ステータス | コードスキャン全体の健全性 |
GitLab
パイプライン、マージリクエスト、セキュリティスキャナーを監視します。
| ウィジェット | タイプ | 説明 |
|---|---|---|
| パイプラインステータス | ステータス | 最新のパイプライン実行の状態 |
| オープンマージリクエスト | リスト | ステータス付きのアクティブなMR |
| プロジェクト統計 | カウンター | スター数、フォーク数、オープンなIssue数、またはオープンなMR数 |
| 脆弱性アラート | リスト | 依存関係スキャンの検出結果 |
| 脆弱性ステータス | ステータス | 脆弱性全体の重大度 |
| SASTアラート | リスト | 静的解析の検出結果 |
| シークレット検出アラート | リスト | 検出されたシークレット |
| DASTアラート | リスト | 動的解析の検出結果 |
Prometheus
メトリクスをクエリし、ターゲットを監視します。
| ウィジェット | タイプ | 説明 |
|---|---|---|
| インスタントクエリ | カウンター | PromQLクエリの現在値 |
| レンジクエリ | グラフ | 設定可能な期間の時系列折れ線グラフ |
| ターゲットUpステータス | ステータス | ジョブ名ごとのスクレイプターゲットの健全性 |
SonarQube
コード品質とセキュリティ分析を追跡します。
| ウィジェット | タイプ | 説明 |
|---|---|---|
| Quality Gateステータス | ステータス | プロジェクトのQuality Gateの合否 |
| プロジェクト測定値 | カウンター | カバレッジ、バグ、脆弱性、コードスメル、技術的負債など |
| イシュー | リスト | 重大度別のバグ、脆弱性、コードスメル |
| セキュリティホットスポット | リスト | セキュリティレビューが必要なコード箇所 |
| セキュリティ評価 | ステータス | プロジェクト全体のセキュリティ評価 |
ArgoCD
Kubernetesアプリケーションのデプロイメントを監視します。
| ウィジェット | タイプ | 説明 |
|---|---|---|
| アプリケーションステータス | ステータス | 単一アプリの健全性と同期状態 |
| アプリケーション一覧 | リスト | 健全性と同期インジケーター付きの全アプリケーション |
| アプリケーションリソース | リスト | 特定のアプリケーションのKubernetesリソース |
| アプリケーション数 | カウンター | アプリケーションの総数（任意でフィルター可能） |
PagerDuty
インシデント、オンコールスケジュール、サービスの健全性を監視します。
| ウィジェット | タイプ | 説明 |
|---|---|---|
| インシデントステータス | ステータス | トリガー済みおよび確認済みインシデントの概要 |
| アクティブインシデント | リスト | 緊急度とサービス付きの、現在アクティブなインシデント |
| オンコール中 | リスト | 現在オンコールのチームメンバー |
| サービスステータス | ステータス | PagerDutyサービスの健全性の概要 |
| インシデント数 | カウンター | オープンなインシデントの総数 |
接続の設定
接続は組織レベルで管理されます。接続を作成・変更できるのは組織管理者のみです。
1. マーケットプレイスに移動
組織設定に移動し、統合タブを選択します。利用可能なすべてのプロダクトがカテゴリ別に一覧表示されます。
2. 接続の追加
- 接続したいプロダクトを見つけます
- 接続をクリックします
- 接続名を入力します（例: 「本番 Datadog」、「GitHub - バックエンドリポジトリ」）
- 必要な認証情報を入力します
必要な設定項目はプロダクトごとに異なります。
| プロダクト | 必須項目 |
|---|---|
| Datadog | APIキー、アプリケーションキー、サイトURL |
| GitHub | パーソナルアクセストークン |
| GitLab | パーソナルアクセストークン、GitLab URL |
| Prometheus | サーバーURL |
| SonarQube | トークン、サーバーURL |
| ArgoCD | トークン、サーバーURL |
| PagerDuty | APIキー |
3. 接続のテスト
保存する前に接続をテストをクリックします。Archylが認証情報を検証し、成功またはエラーのメッセージを表示します。テストに失敗した場合は、次の点を確認してください。
- APIキーまたはトークンに必要な権限がある
- サーバーURLにインターネットから到達できる
- 認証情報の有効期限が切れていない
4. 保存
テストに合格したら保存をクリックします。これで、その接続は組織内のすべてのプロジェクトで利用できるようになります。
接続の管理
- 編集: 既存の接続の名前や認証情報を更新します
- 削除: 接続を削除します。その接続を使用しているウィジェットは動作しなくなり、エラー状態で表示されます
- ステータスインジケーター: 緑（アクティブ）、赤（エラー）、グレー（切断）
同じプロダクトに対して複数の接続を作成できます。たとえば、ステージング用と本番用のDatadogアカウントに別々の接続を用意できます。
ウィジェットの追加
ウィジェットは、接続から取得したライブデータをプロジェクトダッシュボードに表示します。
1. 統合タブを開く
プロジェクト内の統合ビューに移動し、カスタマイズをクリックして編集モードに入ります。
2. ウィジェットの追加
- ウィジェットを追加ボタンをクリックします
- ステップ1 — 接続を選択: 使用する接続を選択します。接続はプロダクトごとにグループ化されています。
- ステップ2 — ウィジェットタイプを選択: ウィジェットのタイプ（ステータス、カウンター、リスト、グラフ、埋め込み）を選択します。利用できるタイプはプロダクトによって異なります。
- ステップ3 — 設定: ウィジェットのタイトルとプロダクト固有のオプションを設定します
3. ウィジェットオプションの設定
ウィジェットタイプごとに固有の設定項目があります。
GitHubウィジェットで必要な項目:
- オーナー: GitHubの組織名またはユーザー名
- リポジトリ: リポジトリ名
- 重大度フィルター（セキュリティウィジェット）: アラートの重大度で絞り込み
Datadogウィジェットで必要な項目:
- モニタータグ（モニター/アラート）: カンマ区切りのタグフィルター
- Datadogクエリ（メトリクス）: Datadogメトリクスのクエリ文字列
- 時間枠（メトリクス）: 1h、4h、1d、1w のいずれか
- 埋め込みURL（ダッシュボード）: 共有ダッシュボードのURL
Prometheusウィジェットで必要な項目:
- PromQLクエリ: PromQL式
- 時間枠（グラフ）: 15m、1h、4h、1d、1w のいずれか
- Y軸ラベルと単位（グラフ）: 任意の表示フォーマット
- ジョブフィルター（ターゲットステータス）: スクレイプジョブ名
SonarQubeウィジェットで必要な項目:
- プロジェクトキー: SonarQubeのプロジェクト識別子
- メトリクス（測定値）: coverage、bugs、vulnerabilities、code_smells など
- 重大度フィルターとイシュータイプ（イシュー）: 任意のフィルター
ArgoCDウィジェットで必要な項目:
- アプリケーション名（ステータス/リソース）: 単一のアプリ名
- アプリケーションフィルター（一覧/件数）: アプリ名にマッチする正規表現パターン
- プロジェクトフィルター（一覧）: ArgoCDプロジェクトによるフィルター
- ヘルスフィルター（件数）: 正常（Healthy）、劣化（Degraded）、進行中（Progressing）など
PagerDutyウィジェットで必要な項目:
- サービスID（インシデント/ステータス）: PagerDutyサービスによる任意のフィルター
- エスカレーションポリシーID（オンコール）: エスカレーションポリシーによる任意のフィルター
ウィジェットタイプ
カウンター
単一の数値を大きく表示します。CPU使用率、リクエスト数、カバレッジ率、スター数などのメトリクスに使用します。
- 単位（任意）付きでフォーマットされた大きな数値
- 値の下に任意のラベル
- ウィジェットのサイズに合わせて文字サイズを調整
ステータス
色分けされた健全性インジケーターを表示します。CIステータス、Quality Gate、モニターの健全性、デプロイメントの同期状態などに使用します。
- 色分けされたバッジ: 緑（正常）、黄（警告）、赤（クリティカル）
- 任意の内訳件数（正常、警告、アラート）
- 利用可能な場合はコンテキストに応じたメッセージ
リスト
スクロール可能なアイテムの一覧を表示します。プルリクエスト、アラート、イシュー、アプリケーションの一覧などに使用します。
- 各アイテムにタイトル、任意のサブタイトル、ステータスバッジを表示
- アイテムをクリックすると外部サービスに移動
- 色分けされたステータスバッジ（成功、警告、エラー、クリティカル、保留中）
グラフ
時系列の折れ線グラフを描画します。Prometheusのレンジクエリや、時間の経過に伴うあらゆるメトリクスに使用します。
- 色分けされた線による複数系列のサポート
- 期間に応じた時間軸のフォーマット
- フォーマット済みの値を表示するホバーツールチップ
- 任意のY軸ラベルと単位
埋め込み
外部ページをiframeで表示します。Datadogダッシュボード、Grafanaパネル、その他埋め込み可能な任意のURLに使用します。
- iframeによる完全な描画
- セキュリティのためにサンドボックス化
- ウィジェットのサイズに合わせてレスポンシブに表示
ウィジェットの整理
セクション
ウィジェットは名前付きのセクションで整理されます。デフォルトのセクションはGeneralです。
- セクションの作成: 編集モードで、セクション入力フィールドを使って新しいセクションを追加します
- 名前の変更: セクションヘッダーの鉛筆アイコンをクリックします
- 削除: ゴミ箱アイコンをクリックします。削除したセクション内のウィジェットはGeneralに移動します
- 折りたたみ/展開: シェブロンをクリックしてセクションの表示を切り替えます
並べ替え
編集モードでは次の操作ができます。
- ウィジェットをドラッグして、セクション内で位置を変えたり、別のセクションに移動したりする
- セクションヘッダーをドラッグして、セクション全体を並べ替える
- 右下のハンドルからウィジェットのサイズを変更する
ウィジェットの位置とセクションへの割り当ては自動的に保存されます。
ウィジェットグリッド
グリッドは12カラムのレイアウトです。ウィジェットの幅は1カラムから全12カラムまで、高さは3行から任意の高さまで変更できます。グリッドは縦方向に詰められ、ウィジェットは空きを埋めるように上へ積み上がります。
スコープ
ウィジェットは3つのレベルでスコープを設定できます。
| スコープ | 表示範囲 | ユースケース |
|---|---|---|
| 組織 | すべてのプロジェクトで表示 | 全社的なダッシュボード |
| プロジェクト | 特定のプロジェクト内でのみ表示 | プロジェクト固有のメトリクス |
| 要素 | C4要素に紐付け | サービスごとの監視 |
組織全体のウィジェットは、トップレベルの統合ページで設定します。プロジェクトと要素のウィジェットは、プロジェクトの統合タブ内で設定します。
トラブルシューティング
ウィジェットに「認証情報が無効です」と表示される
接続の認証情報が期限切れになったか、失効しています。組織設定 > 統合に移動して該当する接続を見つけ、認証情報を更新してください。接続をテストをクリックして確認します。
ウィジェットに「データを読み込めません」と表示される
外部サービスに到達できないか、クエリが無効である可能性があります。次の点を確認してください。
- サービスが稼働していてアクセス可能である
- クエリまたはフィルターの設定が正しい
- 接続のAPIキーに、要求したリソースへのアクセス権限がある
ウィジェットの追加時に利用可能な接続がない
接続は組織レベルで作成されます。管理者でない場合は、組織の管理者に組織設定 > 統合で接続を設定するよう依頼してください。
ベストプラクティス
接続に明確な名前を付ける
環境と目的がわかる名前を使用します。
- 「Datadog — 本番」
- 「GitHub — バックエンドチーム」
- 「SonarQube — メインプロジェクト」
セクションで整理する
関連するウィジェットをセクションにまとめます。
- 「監視」: DatadogとPrometheusのウィジェット
- 「セキュリティ」: SonarQubeとGitHubのセキュリティスキャンウィジェット
- 「CI/CD」: ワークフローステータスとデプロイメントのウィジェット
- 「インシデント対応」: PagerDutyのインシデントとオンコールのウィジェット
ステータスウィジェットから始める
ステータスウィジェットを使うと、健全性の概要を素早く把握できます。重要なメトリクスを特定したら、より詳しく見るためにカウンターやリストのウィジェットを追加しましょう。
要素スコープのウィジェットを使う
ウィジェットをC4要素に直接紐付けると、アーキテクチャダイアグラムにライブな運用コンテキストが表示されます。たとえば、APIサービスを表すコンテナにGitHubのワークフローステータスウィジェットを紐付けます。
次のステップ
- リリース管理 — アーキテクチャ全体のデプロイメントを追跡
- アーキテクチャインサイト — アーキテクチャの問題を検出
- フロー — データがシステム内をどのように流れるかを可視化