コンテンツにスキップ

未翻訳のページは英語で開き、英語と表示されます。

このページは英語の原文の機械翻訳です。内容は英語の原文が優先されます。 Machine-translated from the English page, which is authoritative.

トラッカーレコードコントラクト

tracker.* op、および code.* と loom_search のトラッカー部分は、チーム自身の ClickHouse から、読み取り専用の認証情報を使って、チームの issue、プルリクエスト、インシデントをライブで読み取ります。Loom はレコードをコピーしません。すべてのステートメントは、下記のテーブルとカラムからなる 1 つの論理モデル、つまりコントラクトに対して記述されます。

チームは、次の 2 つの方法のいずれかでスキーマを接続します。

モード 方法
ビュー チームがコントラクトのテーブル名とカラム名を持つビューを作成します。Loom はそれらをそのまま読み取ります。
マッピング Loom は認証情報で読み取れるテーブルを一覧表示し、マッピングを提案します。確定したマッピングはデータとして保存され、リモート側では何も作成されません。

マッピングはコントラクトの手前にある射影にすぎないため、どのソースに対しても同じステートメント、テスト、プライバシー述語が実行されます。コード上のコントラクトは server/tracker/domain/contract.py(REQUIRED、OPTIONAL、FEATURES、ALIASES)、マッピングは server/tracker/domain/mapping.py、テーブルごとに読み取るカラムは server/tracker/domain/columns.py の COLUMNS_READ です。

トラッカーソースの追加

  1. readonly = 2 で、Loom 用の読み取り専用 ClickHouse ユーザーを作成します。 readonly = 1 では、Loom がすべての読み取りに付与するクエリ単位の設定が拒否されるため、どの読み取りも実行されません(CREDENTIAL_READONLY_MODE)。

    CREATE USER loom_ro IDENTIFIED BY '…' SETTINGS readonly = 2;
    GRANT SELECT ON system.columns TO loom_ro;
    -- views mode: the views only
    GRANT SELECT ON loom_tracker.* TO loom_ro;
    -- mapping mode instead: each mapped table
    GRANT SELECT ON tracker_db.tickets TO loom_ro;
    
  2. views モードのみ:ビューを作成します。 データベース(例:loom_tracker)に github_issues、github_prs、edges を作成し、データがあるオプションのテーブルも追加します。ビューは DEFINER = CURRENT_USER SQL SECURITY DEFINER で作成してください。これにより、loom_ro に必要なのはビューへの SELECT だけで、背後のテーブルへの権限は不要です。通常のビューは読み取り側自身の権限で読み取るため、すべての読み取りが ACCESS_DENIED で失敗します。登録時のチェックがこれを検出し、修正方法を示します。ClickHouse 以外のソースは、PostgreSQL、MySQL、S3 エンジンのテーブルの背後に置けます。tracker.contract は、すべてのテーブルとカラムについて保持する内容と、テーブルごとの空のビューテンプレートを返します。これには、項目の id 用の loom_uuid5(name) SQL 関数も含まれます。

  3. ソースを登録します。 組織にサインインしているメンバーであれば誰でも、ダッシュボードの Add a tracker フロー(トラッカーの概要)または以下の op で登録できます。登録者は、そのトラッカーの名前空間の最初の admin になります。何かを書き込む前に、Loom は次の点を確認します。ホストが公開アドレスに解決されること(HOST_REFUSED)、認証情報が読み取り専用であること(CREDENTIAL_NOT_READONLY、CREDENTIAL_READONLY_MODE)、接続できること(SOURCE_UNREACHABLE)、スキーマまたはマッピングがコントラクトを満たすこと(CONTRACT_FAILED)です。読み取り専用とは、SHOW GRANTS と SHOW GRANTS FINAL が列挙するすべてのアクセス種別(付与されたロールの種別を含む)が、SELECT、データベース・テーブル・カラム・ディクショナリの SHOW、dictGet、CREATE TEMPORARY TABLE のいずれかであり、WITH GRANT OPTION や WITH ADMIN OPTION で付与されたものが(ネストされたロールも含め)ないことを意味します。それ以外の種別は拒否されます。ユーザーに付与されたロールはすべてデフォルトロールである必要があり、これによりチェックがロールの連鎖全体を確認できます。SHOW GRANTS FINAL を受け付けないサーバーは拒否されます(SOURCE_UNREACHABLE)。dry_run: true を指定すると、スキーマが不合格の場合は代わりにレポートが返され、不合格のテーブルごとに CREATE OR REPLACE VIEW の草案が付きます。

    Op 内容
    tracker.contract 接続の前に、コントラクトとビューテンプレートを返します。
    tracker.source.inspect 接続して、読み取り可能なすべてのテーブルをカラムとともに一覧し、マッピング案も示します。何も書き込みません。
    tracker.source.add name、host、port(8443)、secure(true)、database、user、password、namespaces、オプションの mapping。dry_run: true はすべてのチェックを実行し、何も書き込みません。
    tracker.source.set_mapping 登録済みソースのマッピングを置き換えます(dry_run も可)。mapping: null で views モードに戻します。
    tracker.source.check コントラクトチェックを今すぐ再実行します。
    tracker.source.rotate 認証情報を置き換えます。
    tracker.source.remove ソースとその名前空間を廃止します(confirm)。
    tracker.source.list 組織のすべてのソースについて、コントラクトの判定、ブレーカーの状態、名前空間、各名前空間での呼び出し元の立場を返します。認証情報は一切返されません。

    namespaces の各要素は {namespace, repos, restricted, join_policy} です。repos は、その名前空間が読み取れる source_id の Org/repo プレフィックスです(一覧にないリポジトリは読み取られません)。restricted は、その名前空間を非公開の記録にします。join_policy は open(デフォルト)で、標準の名前空間では approval も指定できます。セルフサービス登録には LOOM_TRACKER_ORG が必要で、デフォルトで有効です(LOOM_TRACKER_SELF_SERVICE_ENABLED。組織あたり最大 LOOM_TRACKER_SELF_SERVICE_MAX_SOURCES 件、デフォルトは 10。ローカル開発用の ClickHouse には LOOM_TRACKER_SELF_SERVICE_ALLOW_PRIVATE_HOSTS=true)。パスワードは暗号化して保存され、返されることはありません。名前での inspect には、そのソースのいずれかの名前空間に対する admin が必要です。set_mapping、rotate、remove は、ソースのすべての名前空間の読み取り内容を変えるため、それをすべての名前空間に対して持っている必要があります。標準の名前空間は admin でのゲートにより判定され、制限付きの名前空間は、トークンがその名前空間を指定する必要がない点を除き、制限付きゲートのルールにより判定されます。登録者の権限が取り消された後は、ソースを登録しただけでは足りません(制限付き名前空間)。プラットフォーム管理者以外のダッシュボードセッションは writer トークンであるため、非公開(制限付き)の名前空間を持つソースを変更または廃止できません。それには admin ロールのトークンが必要で、オペレーターが loom mint-token --roles admin で発行します。ページにはこれらのボタンが理由付きで無効表示されますが、判断するのはサーバーです。

    オペレーターは、代わりに同じソースを設定ファイルで構成することもできます(設定)。設定されたエントリは、同名の登録済みエントリより優先され、変更は設定でのみ行えます(SOURCE_FROM_CONFIG)。

  4. Loom が名前空間のディレクトリ行を作成します。 kind = tracker、非公開で、制限付きの名前空間は classification = restricted です。join_policy は、標準の名前空間では open(または approval)、制限付きの名前空間では approval になります。

  5. 読み取り側が参加します。 オープンなトラッカー名前空間への role: "viewer" を指定した namespace.join は、サービスアカウントを含め、即座に承認されます。制限付きの名前空間は、その管理者の承認を待ち、読み取り側のトークンがその名前空間を指定する必要があります(ID と名前空間)。

  6. トラッカーをリポジトリにリンクします。 これにより、そのチェックアウトで作業するエージェントがトラッカーを読めるようになります。方法は、tracker_namespaces を指定した code.repo.set_source(リポジトリの admin)、ダッシュボードのリポジトリカード、またはオペレーター自身のリポジトリに限り LOOM_TRACKER_CODE_NAMESPACE_BINDINGS_JSON です。1 つのリポジトリに複数のトラッカーを順番にリンクでき、最初のものがプライマリで、その番号がリポジトリの issue 番号と PR 番号になります(トラッカーのリンク)。tracker.binding は、コード名前空間が呼び出し元に対して何に解決されるかを返します。

設定

同じエントリのオペレーター向けの形式:

LOOM_TRACKER_ORG=acme
LOOM_TRACKER_SOURCES_JSON='{
  "sources": {
    "widgets": {"host": "abc.clickhouse.cloud", "port": 8443, "secure": true, "database": "loom_tracker"}
  },
  "namespaces": {
    "tracker-widgets":         {"source": "widgets", "repos": ["acme/widgets"]},
    "tracker-widgets-private": {"source": "widgets", "repos": ["acme/widgets-private"], "restricted": true}
  }
}'
LOOM_TRACKER_CREDENTIALS_JSON='{"widgets": {"user": "loom_ro", "password": "…"}}'
LOOM_TRACKER_CODE_NAMESPACE_BINDINGS_JSON='{"code-widgets*": ["tracker-widgets", "tracker-helpdesk"]}'

認証情報はマップとは別の変数に置くため、シークレットを含めずにマップを表示したり差分を取ったりできます。バインディングの値は、1 つのトラッカー名前空間、または先頭をプライマリとする順序付きのリストです。キーはオペレーターのリポジトリのコード名前空間名に対する glob です(セルフサービスのリポジトリは、そのメンテナーがリンクします)。メンテナーが行う code.repo.set_source のリンクは、そのリポジトリについてはマップを置き換えます。トラッカー名前空間は LOOM_TRACKER_ORG に属します。これが空の場合、トラッカー名前空間は一切提供されません。

ソースエントリのオプション

ソースエントリには、次の項目も指定できます。

  • "mapping":保存済みのマッピング(マッピングモード)。指定がない場合はビューモードになります。
  • "checks": {"from": "<table or table function>", "repo": "Org/repo"}:トラッカーの CI 結果が置かれている場所で、tracker.flaky と tracker.test_signal が読み取ります。解決順序は、このエントリ、次にソース自身の checks テーブル、最後に LOOM_TRACKER_CHECKS_FROM / LOOM_TRACKER_CHECKS_REPO(どちらもデフォルトは空で、CI チェックなしを意味します)です。テーブル関数を包んだビューではなく、テーブル関数そのものを指定してください。ビューのフィルターはスキャンの後にリモート側で実行されるためです。repo を指定しない場合、リポジトリが 1 つだけの名前空間はそのリポジトリを使います。
  • "bisect": {"code_prefixes": ["src/"]}:bisect でソースコードとみなすパスです。指定がない場合は、docs、tests、CI、examples、benchmarks のいずれの配下でもないすべてのパスが対象です。トラッカーのないリポジトリでも、Loom 自身の PR 履歴に対して bisect を行います(その場合、回答には candidates_from: "code_history" が含まれます)。
  • "columns": {"<table>": {"<contract column>": "<your column>"}}:お使いのテーブルが別の名前で持っているコントラクトのカラムです。たとえば {"github_issues": {"triage_bisect_outcome": "bisect_result"}} のように指定します。実際のカラムも、対応するコントラクトのカラムと同様に検査されます。使用できるのは単純な識別子のみです。

ルール:

  • 未知のソースを指定した名前空間は提供されません(起動時にエラーを 1 行出力するだけで、推測はしません)。
  • 各ソースは独自の接続、サーキットブレーカー、時間予算を持つため、あるチームのサービスが遅くなっても、他のチームのブレーカーが作動することはありません。
  • 登録済みのソース(loom.qa_sources)は LOOM_TRACKER_SOURCES_REFRESH_SECONDS(60)秒ごとに再読み込みされます。同じプロセス内での書き込みは、すぐに反映されます。

トラッカーの全設定は設定リファレンスにあります。

公開と非公開

トラッカーの名前空間は standard または restricted のいずれかで、Loom がステートメントごとに強制します。

  • standard 名前空間では、すべてのステートメントに is_private = 0 が付与されます。非公開データのみを保持するテーブル(core_incidents、support_cases、slack_threads)は、読み取りの前に拒否されます。
  • restricted 名前空間ではこの述語が外れ、その名前空間自身の repos のみを読み取ります。アクセスは restricted 名前空間のルールによって制御され、その名前空間を指定するトークンと直接の許可(grant)が必要です。

次の 3 つの構成が使えます。

  • is_private 列を持つ 1 組のビューを用意し、両方の名前空間から読み取る構成(読み取り専用ユーザーに対して is_private の行ポリシーを設定すると、ClickHouse 側でも確認が加わります)。
  • 2 組のビューと 2 人のユーザーを用意し、一方は公開行のみを保持させ、2 つのソースとして登録する構成。
  • restricted 名前空間のみの構成。

契約

型はファミリー単位で比較します。String、LowCardinality(String)、Nullable(String)、FixedString、Enum は同一ファミリー、DateTime、DateTime64、Date は同一ファミリー、UInt* と Int* の各型と Bool は同一ファミリーです。Array(x) は x で比較します。別のストアに対するビューは、コーデックや null 許容性が異なっていてもかまいませんが、構造が異なってはいけません。ビューテンプレートでは、各ファミリーを最も幅の広い型(UInt64、DateTime64(3) など)で記述します。

必須テーブル

これらがないソースは提供されません。

github_issues:issue ごとに 1 行です。

カラム ファミリー 意味
id UUID uuid5(NAMESPACE_DNS, 'github_issue:' \|\| source_id)(プライベート行では github_issue_private:)。edges が使うキーです
source_id String Org/repo#number。リポジトリは tracker 名前空間に列挙されているものでなければなりません
number UInt issue 番号
url, title, body, author String 人が開けるリンク、すべての検索が読むタイトル、重複チェックが読むテキスト、issue を作成した人
labels, assignees Array(String)
primary_component, severity_level String チームの分類体系。ない場合は ''
state_reason String completed、not_planned、duplicate、または ''
affected_versions, fix_versions Array(String) issue が影響するバージョン、修正を含むバージョン
is_flaky_test, is_crash_ci, is_performance UInt 0/1 のフラグ。不明な場合は 0
has_test UInt 関連するテストがあるか。不明な場合は NULL
error_code UInt 報告が示すサーバーのエラーコード。ない場合は 0
is_private UInt プライベートリポジトリの行では 1
created_at, updated_at, closed_at DateTime closed_at は未クローズの間はエポック 0
triage_bisect_outcome, triage_introduced_commit, triage_component, triage_confidence String トリアージボットの判定。tracker にない場合は '' として提供されます
triage_reproduces_on, triage_clean_on Array(String) 同様に、ない場合は [] として提供されます

github_prs:プルリクエストごとに 1 行です。

カラム ファミリー 意味
id UUID uuid5(NAMESPACE_DNS, 'github_pr:' \|\| source_id)(github_pr_private:)
source_id, number, url, title, body, author 上記と同じ
pr_number UInt number と同じ
primary_component, severity_level, is_private, created_at, updated_at, closed_at 上記と同じ
state String open、closed、または merged
is_merged, has_test, review_requests_test UInt
test_types, reviewers, src_components Array(String)
ci_result, changelog_category, minor_version, base_branch String
is_backport_pr, is_cherrypick_pr, is_sync_pr UInt 派生 PR。アクティビティの読み取りからは除外されます
upstream_pr_number UInt バックポートが繰り返す元の PR。ない場合は 0
additions, deletions, time_to_merge_days UInt

edges:アイテム間のリンクです。

カラム ファミリー 意味
from_id, to_id UUID 上記のアイテム id
from_type, to_type String github_issue, github_pr, github_issue_private, github_pr_private, core_incident, support_case
rel_type String fixes, related_to, duplicate_of, caused_by, backport_of, reverts, …
created_at DateTime

Loom はアイテムの id をローカルで導出し、それをキーに edges を結合するため、ビューはまったく同じ値を生成する必要があります。ClickHouse には uuid5() がありません。tracker.contract が返す loom_uuid5 関数は、RFC 4122 のバージョン 5 の構成を SQL で実装したもので、Python の uuid.uuid5 と同じ値になります。

任意テーブル

テーブルがない場合、それを必要とする op は not_provided を返します。テーブルはあっても最小カラム(contract.py の OPTIONAL)のいずれかが欠けている場合は incomplete と報告され、ないものとして扱われます。

テーブル 最小カラム
core_incidents id, source_id, title, body, primary_component, severity_level, stack_functions Array(String)(スタックフレームの照合), error_code, created_at
support_cases id, source_id, title
slack_threads source_id, title, body
component_risk_snapshot computed_at, component
release_items release_version, issue_number
release_health_snapshot computed_at, release_version
version_history, version_history_private commit_sha, version
checks check_name, test_name
cloud_instances instance_id
rel_instance_mentions from_id, instance_id
slack_incidents incident_id

core_incidents、support_cases、slack_threads は、制限付きの名前空間を通してのみ読み取られます。

機能カラム

必須テーブル上の任意カラムで、存在するか存在しないかが報告されます。ソースにない機能カラムは、そのエイリアス、なければデフォルトとして読み取られます(エイリアスを参照)。それを読むステートメントは、そのカラムを持たない行に対するものとして応答し、機能は存在しないままになります。

機能 カラム 有効になるもの
bisect github_prs.diff, github_prs.affected_file_paths bisect 候補と原因コミットのスキャン
merge_time github_prs.merged_at マージ時間に関する事実
vector github_issues.embedding, github_prs.embedding 報告のみ。tracker.similar は Loom 自身が計算する埋め込みを使用します

エイリアス

ソースに契約のカラムがない場合でも、contract.py の ALIASES が、そのソースにあるカラム上で受け入れ可能な式を指定していれば、契約を満たします。チェックはエイリアス自身のカラムをファミリーで検証し、aliased として報告します。ステートメントは引き続き契約上の名前を読みます。テーブル参照が、エイリアスを追加する射影に置き換えられるためです(クエリアナライザーが、ステートメントが読むカラムに絞り込みます)。自身のカラムを持たないエイリアスはデフォルト(defaulted)です。すべての行が ''、0、[]、NULL のいずれかとして読まれ、レポートにもその旨が示されるため、デフォルトがデータと取り違えられることはありません。

テーブル カラム 受け入れられる形式(順序どおり)
github_issues severity_level severity
github_issues has_test toUInt8(metadata.has_test.:Bool)(JSON の metadata カラム)、なければ NULL
github_issues triage_bisect_outcome, triage_introduced_commit, triage_component, triage_confidence ''
github_issues triage_reproduces_on, triage_clean_on []
github_prs has_test toUInt8(metadata.has_test.:Bool)、なければ toUInt8(tests_added > 0)
github_prs upstream_pr_number ifNull(toUInt32(metadata.original_pr_number.:Int64), 0)、なければ 0
github_prs review_requests_test NULL
github_prs test_types, src_components []
github_prs merged_at if(is_merged = 1, closed_at, toDateTime64(0, 3))
github_prs, core_incidents severity_level ''
qa_bugs(回答ルートのクロスソースビュー) severity_level, has_test severity、toUInt8(metadata.has_test.:Bool)、なければ NULL

契約に載っていないリネームは、依然としてカラム欠落として扱われます。ソースエントリの columns マップ(ソースエントリのオプション)で宣言するか、contract.py に Alias を追加して、すべてのソースで別の表記を受け入れるようにしてください。

マッピングモード

マッピングは、論理テーブルごとに、チームのどのテーブルを読み取るかを指定し、論理カラムごとに、そのテーブルのカラムに対する式を指定します。

{
  "version": 1,
  "tables": {
    "github_issues": {
      "source": "tracker_db.tickets",
      "final": true,
      "columns": {
        "source_id": { "concat": [{ "lit": "acme/widgets#" }, "ticket_no"] },
        "number": "ticket_no",
        "title": "summary",
        "body": "description",
        "created_at": "opened_at",
        "state_reason": { "lower": "resolution" }
      }
    }
  }
}
  • 式はデータであり、SQL ではありません:実テーブルが持つカラム名(または {"col": …})、{"lit": …}、あるいは concat、coalesce、eq、in、has、cast([expr, family])、lower、digits(キー末尾の数字。PROJ-1234 → 1234)のいずれかです。Loom は識別子をバッククォートで、リテラルを引用符で囲んで式を生成し、各式をステートメントが読み取るファミリーに変換して、読み取り専用の認証情報で実行します。
  • source は db.table で指定します。トラッカーのデータベース内のテーブルであれば table だけで指定できます。final: true を指定すると、テーブルを FINAL 付きで読み取ります(Replacing、Collapsing、Aggregating、Summing の各エンジンで提案されます)。
  • Loom は、マッピングされた source_id から各アイテムの id を、マッピングされた from_ref / to_ref(Org/repo#number)からエッジの from_id / to_id を導出します。これらはマッピングしません。
  • マッピングする各テーブルには、コアカラムが必要です。github_issues は source_id、number、title、created_at、github_prs は source_id、pr_number、title、created_at、edges は from_ref、to_ref、from_type、to_type、rel_type、core_incidents は source_id、title、created_at です。マッピングでは github_issues を必ずマッピングしてください。マッピングされていないカラムにはデフォルト値が入るか、値が導出されます(PR の state はマージ済みとクローズ済みのフィールドから導出されます)。レポートにはそれらが一覧表示されます。マッピングで指定されていない論理テーブルは、空のテーブルとして読み取られます。
  • レポートの capabilities(items、duplicate_check、duplicate_calibration、pull_requests、links、severity_board、bisect、incidents、ci_checks)は、マッピングされたデータで Loom が何に答えられるかを示します。

読み取り時には、各論理テーブルへの参照がマッピングされたプロジェクションに置き換えられるため、すべてのソースに対して同じステートメント、テスト、プライバシー述語が実行されます。

ソースの確認

loom tracker-contract-check                           # every configured source
loom tracker-contract-check --source widgets          # one source
loom tracker-contract-check --namespace tracker-widgets
loom tracker-contract-check --json

サーバーは、プロセスごとの最初のトラッカー読み取り時に同じチェックを実行します。ソース自身の認証情報でスキーマを読み取り(system.columns、それが非表示の場合はテーブルごとの DESCRIBE)、結果を LOOM_TRACKER_CONTRACT_TTL_S(3,600 秒)のあいだキャッシュします。失敗した結果は 60 秒だけキャッシュするため、修正したビューは 1 分以内に反映されます。チェックに失敗したソースは、不足している内容を示す tracker_unavailable をすべての読み取りに返し、部分的な応答は返しません。tracker.source.check を使うと、チェックをオンデマンドで実行できます。

関連ドキュメント