A StreamingQueryListener 在每個微批次結束時,會從正在執行的結構化串流查詢中接收進度指標,例如輸入列數、處理速率及批次持續時間。 這個教學會引導你如何附加一個監聽器,檢查查詢是否跟上輸入,當查詢落後時會警告,並將每個批次的狀態記錄到你用 SQL 查詢的 Unity 目錄資料表中。 此範例可在無伺服器運算及支援 Unity Catalog 的運算上執行。
欲了解監聽者回報的指標與事件欄位的完整參考,請參閱 Azure Databricks 上的監控結構化串流查詢。
本教學課程包含下列步驟:
- 建立筆記本
- 建立 Unity Catalog 物件
- 定義接聽程式
- 定義週期性寫入器
- 使用監控啟動查詢
- 查詢已記錄的健康資料
- 停止查詢並清理
Requirements
您必須滿足下列需求,才能完成本教學課程:
- 您的工作區必須已啟用 Unity Catalog。 請參閱什麼是 Unity Catalog?。
- 你必須能使用無伺服器運算或支援 Unity Catalog 的叢集。 關於
StreamingQueryListener支援的 Databricks 執行時版本和存取模式,請參見 在 Azure Databricks 上監視結構化串流查詢。 - 您必須擁有在 Unity Catalog 的 catalog 中建立結構、磁碟區和資料表的權限。 本教學使用名為
main的目錄。 用一個可寫入的型錄來替代。
步驟一:建立筆記本
你可以使用 Databricks 筆記本來定義監聽器並執行串流查詢。
建立筆記本:
- 在側邊欄點選 「新」 ,然後點選
筆記本。
- 在 Compute 下拉式選單中,選擇無伺服器運算或啟用 Unity Catalog 的叢集。
- 選擇 Python 作為預設語言。
步驟 2:建立 Unity Catalog 物件
監聽器會將每批次的健康狀況記錄到 Unity 目錄管理的資料表,串流查詢則寫入第二個受管理資料表,查詢則將其檢查點儲存在 Unity 目錄卷中。 要建立結構與磁碟區並定義物件名稱,執行:
catalog = "main"
schema = "streaming_monitoring"
spark.sql(f"CREATE SCHEMA IF NOT EXISTS {catalog}.{schema}")
spark.sql(f"CREATE VOLUME IF NOT EXISTS {catalog}.{schema}.checkpoints")
health_table = f"{catalog}.{schema}.streaming_health"
target_table = f"{catalog}.{schema}.rate_target"
checkpoint_path = f"/Volumes/{catalog}/{schema}/checkpoints/rate_target"
步驟 3:定義監聽器
監聽器會讓每次回呼都輕量化。 對於每個微批次,它會比較處理速率與輸入速率,查詢落後時會印出警告,並將批次的健康狀態附加到記憶體中的緩衝區。 要定義監聽者,執行:
import threading
from pyspark.sql.streaming import StreamingQueryListener
class HealthListener(StreamingQueryListener):
def __init__(self):
self._lock = threading.Lock()
self._buffer = []
def onQueryStarted(self, event):
print(f"Query started: {event.id}")
def onQueryProgress(self, event):
progress = event.progress
input_rate = progress.inputRowsPerSecond
processed_rate = progress.processedRowsPerSecond
# The query is falling behind when it processes data slower than it arrives.
falling_behind = input_rate > 0 and processed_rate < input_rate
if falling_behind:
print(f"WARNING batch {progress.batchId}: falling behind "
f"({processed_rate:.1f} processed/s < {input_rate:.1f} input/s)")
with self._lock:
self._buffer.append((int(progress.batchId), int(progress.numInputRows),
float(input_rate), float(processed_rate),
bool(falling_behind)))
def drain(self):
with self._lock:
records, self._buffer = self._buffer, []
return records
def onQueryIdle(self, event):
pass
def onQueryTerminated(self, event):
print(f"Query terminated: {event.id}")
監聽者會覆寫以下事件方法:
| 方法 | Description |
|---|---|
onQueryStarted |
當查詢開始時執行。 |
onQueryProgress |
每次微批次結束時都會執行。 此範例比較處理速率與輸入速率,查詢落後時發出警告,並暫存批次的健康狀態。 |
onQueryIdle |
當查詢閒置等待新資料時執行。 |
onQueryTerminated |
當查詢停止時執行,無論是否發生錯誤。 |
該 drain 方法傳回緩衝紀錄並清除緩衝區。 鎖會保護緩衝區,因為監聽者會從監聽者執行緒將資料附加到其中,而下一步的寫入者則從另一個執行緒讀取。
Note
onQueryProgress 執行在監聽執行緒上,因此繁重的工作會延遲該工作階段中每個查詢的進度報告。 這也是為什麼監聽器只在回調中緩衝,並從獨立執行緒寫入。 請參閱 Azure Databricks 上的 Monitoring Structured Streaming 查詢中的附註。
步驟四:定義週期性寫入器
背景執行緒會以固定間隔將緩衝的記錄寫入健康資料表,因此監聽器不會在自己的執行緒上執行 Spark 工作。 函 publish 式是唯一寫入記錄的地方。 若要將度量傳送至其他系統,如 Apache Kafka,請替換 publish 的主體。 要定義寫入器及其區間迴路,執行:
def publish(records):
if not records:
return
(spark.createDataFrame(records,
"batchId long, numInputRows long, inputRowsPerSecond double, "
"processedRowsPerSecond double, fallingBehind boolean")
.write.mode("append").saveAsTable(health_table))
stop_event = threading.Event()
def flush_loop(listener, interval_seconds=10):
while not stop_event.wait(interval_seconds):
publish(listener.drain())
迴圈每 10 秒寫入一批記錄,直到 stop_event 被設為已設定狀態。 每次寫入會一次附加多列,避免了每批次寫入所產生的小檔案。
步驟 5:使用監控開始查詢
註冊監聽器,啟動寫入執行緒,然後啟動查詢,從內建速率來源讀取並寫入目標資料表。 速率來源以固定速率產生列,因此監聽者在沒有外部資料來源的情況下也能報告穩定的進度。 要開始監控並執行查詢,請執行:
listener = HealthListener()
spark.streams.addListener(listener)
flusher = threading.Thread(target=flush_loop, args=(listener,), daemon=True)
flusher.start()
query = (
spark.readStream.format("rate").option("rowsPerSecond", 5).load()
.writeStream.format("delta")
.option("checkpointLocation", checkpoint_path)
.toTable(target_table)
)
讓查詢持續執行一兩分鐘,讓幾次刷新間隔過去。 每個微批次都會觸發 onQueryProgress,當查詢落後時會印出警告,並暫存該批次的健康狀態資訊。 寫入者每 10 秒將緩衝紀錄附加到資料表,這樣你可以在串流執行時查詢它們。
步驟 6:查詢已記錄的健康狀況
閱讀健康表,了解每批資料送達的速度、查詢處理速度,以及查詢是否落後。 要顯示紀錄,請執行:
display(spark.sql(f"""
SELECT batchId, numInputRows,
round(inputRowsPerSecond, 1) AS input_per_second,
round(processedRowsPerSecond, 1) AS processed_per_second,
fallingBehind
FROM {health_table}
ORDER BY batchId
"""))
前一個查詢每完成一批回傳一列,例如:
batchId numInputRows input_per_second processed_per_second fallingBehind
0 2 0.0 1.9 false
1 5 4.8 5.7 false
2 5 5.7 4.6 true
3 5 4.6 6.0 false
4 4 4.8 5.0 false
5 4 5.0 4.4 true
6 5 5.5 6.1 false
7 4 4.8 4.1 true
一個健康的查詢處理資料的速度至少與抵達相當,因此 processed_per_second 保持在或高於 input_per_second ,且 fallingBehind 為 false。 單一批次常低於輸入速率,如第2、第5和第7批次所示。 這種抖動是正常的。 如果 fallingBehind 持續 true 連續好幾個批次,查詢就無法跟上輸入。 透過增加計算量、減少每批次的工作量,或降低輸入速率來進行排查。
關於每個進度事件的完整來源、匯與狀態指標,請參閱「在 Azure Databricks 上監控結構化串流查詢」。
步驟七:停止查詢並清理
停止查詢、停止寫入執行緒、寫入還在緩衝區裡的記錄,然後丟棄你建立的物件,這樣它們就不會繼續產生成本。 若要清理,請執行:
query.stop()
stop_event.set()
flusher.join()
publish(listener.drain())
spark.streams.removeListener(listener)
spark.sql(f"DROP SCHEMA IF EXISTS {catalog}.{schema} CASCADE")