Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

CLI 參考

Osprey 包含下列以 console scripts 安裝的 command-line tools。可從 repository root 使用 uv run <command> 執行，若 package 已安裝在 environment 中，也可以直接使用 <command>。

osprey-cli

通用 Worker 管理工具，可以 push Rules、開啟 debug shell，以及手動套用 Labels。

osprey-cli push-rules

osprey-cli push-rules RULES_PATH [--dry-run/--no-dry-run] [--suppress-warnings]

驗證 RULES_PATH 的 Rules 並 push。使用 --dry-run 可以只驗證而不 push。驗證失敗時會以非零狀態結束。

osprey-cli compute-and-upload-dependencies-mapping

osprey-cli compute-and-upload-dependencies-mapping RULES_PATH [--suppress-warnings]

計算 RULES_PATH 中 Rules 的 dependency graph 並上傳，供 Rules Visualizer 使用。

osprey-cli shell

osprey-cli shell [-i / --auto-import / --no-auto-import]

開啟 interactive shell。若已安裝 IPython 則使用 IPython，否則使用備用的 code.InteractiveConsole。Shell 會預先 import labels、access_audit_log、stored_execution_result storage modules，以及 EntityT、EntityLabelMutation 與 LabelStatus。使用預設啟用的 --auto-import 時，也會 import 在 osprey_lib 中找到的所有 model classes，適合互動檢查已保存資料。

Interactive shell 可能直接讀取或修改敏感資料。正式環境應限制使用權限，避免將查詢結果、tokens 或個人資料留在 shell history，並記錄必要的管理操作。

osprey-cli apply-label

osprey-cli apply-label ENTITY_TYPE ENTITY_ID LABEL_NAME LABEL_STATUS \
  [--reason REASON] [--description DESCRIPTION] [--expire-instantly]

手動為單一 Entity 套用 Label，主要用於除錯或從外部來源匯入個別 Labels。--reason 預設為 CliLabelMutationWithoutEffects；--description 預設為 "Manually changed from the command line for debugging."。--expire-instantly 會讓 Label 幾乎立即到期，而非持續存在。

Osprey instance 必須先設定 labels provider，否則 command 會以 assertion error 失敗。

osprey-cli bulk-apply-label

osprey-cli bulk-apply-label ENTITY_TYPE ENTITY_IDS_FILE_PATH LABEL_NAME LABEL_STATUS \
  [--reason REASON] [--description DESCRIPTION] [--expire-instantly]

功能與 apply-label 相同，但會從 ENTITY_IDS_FILE_PATH 逐行讀取 Entity IDs，為全部 Entities 套用 Label，並在過程中印出進度。這是從外部來源匯入大量 Label 清單的 CLI 路徑。透過介面操作的流程請見 Bulk Actions。

批次套用前應先驗證檔案來源、Entity type、數量、Label、原因與到期設定，並以小型樣本 dry run 或在隔離環境測試。這個 command 可能大量改變後續 Rule 判斷，應搭配授權、稽核及回復流程。

osprey-stress

由 osprey_worker 安裝，entry point 是 osprey.worker.stress.cli:main。工具會對執行中的 Osprey Worker 進行 end-to-end stress test，產生 synthetic Events、消費產生的 Execution Results，再回報 drop rate 與 latency。適合驗證 dependency bumps、測量 throughput regressions，以及用 pipeline health 作為 CI gate。

osprey-stress run

osprey-stress run \
  --events 10000 --rate 1000 \
  --threshold-drop-rate 0.01 --threshold-p95-ms 500 \
  --report json

以每秒 --rate 個 Events 的速度產生 --events 個 synthetic Events 至 input topic。--events 預設為 1000，--rate 預設為 100.0。接著最多等待 --drain-seconds，預設 30.0 秒，讓 Worker 完成處理再回報。

常用 flags 如下。

  • --report {human,json}　輸出格式，預設為 human
  • --verbose　定期將進度輸出至 stderr，頻率由 --verbose-interval-seconds 控制，預設為 2.0
  • --bootstrap-servers 預設 localhost:9092、--input-topic 預設 osprey.actions_input、--output-topic 預設 osprey.execution_results
  • --threshold-drop-rate 與 --threshold-p95-ms　設定後，若觀察到的 drop rate 或 p95 latency 超過 threshold，command 會以非零狀態結束，可用來阻擋 CI Job

Stress test 會向指定 topic 寫入大量 Events，只能針對已確認的測試環境執行。執行前應確認 bootstrap servers、topics、速率與資料隔離，避免對正式流量或共用資源造成影響。

osprey-stress measure

osprey-stress measure [--duration SECONDS] [--report {human,json}]

此 command 保留給針對外部產生 Events 的 open-loop measurement，例如 JetStream input stream sample #236。Measurement layer 尚未完成，目前只會印出 stub message 並以非零狀態結束。現階段請使用 run 進行 closed-loop synthetic testing。

osprey-async-cli

由 osprey_async_worker 安裝，entry point 是 osprey.async_worker.cli.main:cli。這是 experimental 的 asyncio-native Worker prototype，不使用 gevent 或 monkey-patching，用來驗證 asyncio-based executor 能否取代 gevent 版本。目前不適合正式環境。

osprey-async-cli run

osprey-async-cli run --rules-path PATH [--input-file PATH] [--max-concurrent 12] \
  [--with-plugins] [--input-source {file,kafka}] \
  [--kafka-topic TOPIC] [--kafka-bootstrap-servers SERVERS] \
  [--kafka-group-id GROUP] [--kafka-offset-reset {latest,earliest}]

使用必要的 --rules-path 指定 static Rules directory，執行 async Worker。預設只使用 stdlib UDFs，並將 Results 印至 stdout。--with-plugins 會載入完整 async Plugin system，包括透過 osprey_async_plugin entry-point group 註冊的 UDFs、validators 與 output sinks，因此需要相關外部服務都能使用。

使用 --input-source 控制 input source。

  • file，預設值　從 --input-file 讀取 JSONL actions。省略時不提供 input，適合只驗證 Worker 能否啟動
  • kafka　從 --kafka-topic 消費資料，預設為 osprey.actions_input，並透過 --kafka-bootstrap-servers 連線，預設為 localhost:9092

osprey-async-cli benchmark

osprey-async-cli benchmark --rules-path PATH --input-file PATH \
  [--max-concurrent 12] [--iterations 1000] [--warmup 50]

若能 import gevent，此 command 會使用相同 Rules 與 input data，比較 async executor 與 gevent executor。先執行 --warmup 次 iterations，再執行 --iterations 次計時 iterations，最後印出 throughput 與 latency 比較。