다음을 통해 공유


API를 사용하여 모니터 만들기

이 페이지에서는 Databricks SDK를 사용하여 Databricks에서 모니터를 만드는 방법을 설명하고 API 호출에 사용되는 모든 매개 변수를 설명합니다. REST API를 사용하여 모니터를 생성 및 관리할 수도 있습니다. 참조 정보는 Lakehouse 모니터링 SDK 참조REST API 참조를 참조하세요.

Unity 카탈로그에 등록된 관리형 또는 외부 델타 테이블에 모니터를 만들 수 있습니다. 단일 모니터만 모든 테이블에 대한 Unity 카탈로그 메타스토어에서 만들 수 있습니다.

요구 사항

Lakehouse 모니터링 API는 databricks-sdk 0.28.0 이상에 기본 제공됩니다. 최신 버전의 API를 사용하려면 Notebook 시작 부분에 다음 명령을 사용하여 Python 클라이언트를 설치합니다.

%pip install "databricks-sdk>=0.28.0"

사용자 환경에서 Databricks SDK를 사용하도록 인증하려면 인증을 참조하세요.

프로필 유형

모니터를 만들 때 TimeSeries, InferenceLog 또는 스냅샷 프로필 유형 중 하나를 선택합니다. 이 섹션에서는 각 옵션에 대해 간략하게 설명합니다. 자세한 내용은 API 참조 또는 REST API 참조를 확인하세요.

참고 항목

  • 시계열 또는 유추 프로필을 처음 만들 때 모니터는 생성 30일 전의 데이터만 분석합니다. 모니터를 만든 후에는 모든 새 데이터가 처리됩니다.
  • 구체화된 뷰 및 스트리밍 테이블에 정의된 모니터는 증분 처리를 지원하지 않습니다.

TimeSeriesInference 프로필의 경우 테이블에서 CDF(변경 데이터 피드)를 사용하도록 설정하는 것이 가장 좋습니다. CDF를 사용하도록 설정하면 새로 고칠 때마다 전체 테이블을 다시 처리하는 대신 새로 추가된 데이터만 처리됩니다. 이렇게 하면 실행이 더 효율적이며 여러 테이블에서 모니터링을 확장할 때 비용이 절감됩니다.

TimeSeries 프로필

TimeSeries 프로필은 시간 창의 데이터 분포를 비교합니다. TimeSeries 프로필의 경우 다음을 제공해야 합니다.

  • 타임스탬프 열(timestamp_col). 타임스탬프 열 데이터 형식은 TIMESTAMP 또는 to_timestamp PySpark 함수를 사용하여 타임스탬프로 변환할 수 있는 형식이어야 합니다.
  • 메트릭을 계산할 granularities 집합입니다. 사용 가능한 세분성은 "5분", "30분", "1시간", "1일", "1주", "2주", "3주", "4주", "1개월", "1년"입니다.
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"])
)

InferenceLog 윤곽

InferenceLog 프로필은 TimeSeries프로필과 유사하지만 모델 품질 메트릭도 포함합니다. InferenceLog 프로필의 경우 다음 매개 변수가 필요합니다.

매개 변수 설명
problem_type MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION 또는 MonitorInferenceLogProblemType.PROBLEM_TYPE_REGRESSION
prediction_col 모델의 예측 값을 포함하는 열입니다.
timestamp_col 유추 요청의 타임스탬프를 포함하는 열입니다.
model_id_col 예측에 사용되는 모델의 ID를 포함하는 열입니다.
granularities 시간에 따라 창에서 데이터를 분할하는 방법을 결정합니다. 가능한 값: "5분", "30분", "1시간", "1일", "1주", "2주", "3주", "4주", "1개월", "1년".

선택적 매개 변수도 있습니다.

선택적 매개 변수 설명
label_col 모델 예측에 대한 기본 진리를 포함하는 열입니다.
from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorInferenceLog, MonitorInferenceLogProblemType

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  inference_log=MonitorInferenceLog(
        problem_type=MonitorInferenceLogProblemType.PROBLEM_TYPE_CLASSIFICATION,
        prediction_col="preds",
        timestamp_col="ts",
        granularities=["30 minutes", "1 day"],
        model_id_col="model_ver",
        label_col="label", # optional
  )
)

InferenceLog 프로필의 경우 조각은 model_id_col의 고유 값에 따라 자동으로 만들어집니다.

Snapshot 프로필

TimeSeries와는 달리 Snapshot 프로필은 시간이 지남에 따라 테이블의 전체 내용이 어떻게 변경되는지 모니터링합니다. 메트릭은 테이블의 모든 데이터에 대해 계산되며 모니터를 새로 고칠 때마다 테이블 상태를 모니터링합니다.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorSnapshot

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  snapshot=MonitorSnapshot()
)

새로 고침 및 모니터 결과 보기

메트릭 테이블을 새로 고치려면 run_refresh를 사용합니다. 예시:

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.run_refresh(
    table_name=f"{catalog}.{schema}.{table_name}"
)

Notebook에서 run_refresh을 호출하면 모니터 메트릭 테이블이 생성되거나 업데이트됩니다. 이 계산은 Notebook이 연결된 클러스터가 아닌 서버리스 컴퓨팅에서 실행됩니다. 모니터 통계가 업데이트되는 동안 Notebook에서 명령을 계속 실행할 수 있습니다.

메트릭 테이블에 저장된 통계에 대한 자세한 내용은 메트릭 테이블 모니터링을 참조하세요. 메트릭 테이블은 Unity Catalog 테이블입니다. Notebook 또는 SQL 쿼리 탐색기에서 쿼리하고 카탈로그 탐색기에서 볼 수 있습니다.

모니터와 연결된 모든 새로 고침의 기록을 표시하려면 list_refreshes을 사용합니다.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.list_refreshes(
    table_name=f"{catalog}.{schema}.{table_name}"
)

큐에 대기, 실행 또는 완료된 특정 실행의 상태를 얻으려면 get_refresh를 사용합니다.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.get_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id = run_info.refresh_id
)

대기 중이거나 실행 중인 새로 고침을 취소하려면 cancel_refresh를 사용합니다.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
run_info = w.quality_monitors.run_refresh(table_name=f"{catalog}.{schema}.{table_name}")

w.quality_monitors.cancel_refresh(
    table_name=f"{catalog}.{schema}.{table_name}",
    refresh_id=run_info.refresh_id
)

모니터 설정 보기

API get_monitor를 사용하여 모니터 설정을 검토할 수 있습니다.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.get(f"{catalog}.{schema}.{table_name}")

일정

예약된 기준으로 실행되도록 모니터를 설정하려면 create_monitorschedule 매개 변수를 사용합니다.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorCronSchedule

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  schedule=MonitorCronSchedule(
        quartz_cron_expression="0 0 12 * * ?", # schedules a refresh every day at 12 noon
        timezone_id="PST",
    )
)

자세한 내용은 cron 식을 참조하세요.

Notifications

모니터에 대한 알림을 설정하려면 create_monitornotifications 매개 변수를 사용합니다.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.catalog import MonitorTimeSeries, MonitorNotifications, MonitorDestination

w = WorkspaceClient()
w.quality_monitors.create(
  table_name=f"{catalog}.{schema}.{table_name}",
  assets_dir=f"/Workspace/Users/{user_email}/databricks_lakehouse_monitoring/{catalog}.{schema}.{table_name}",
  output_schema_name=f"{catalog}.{schema}",
  time_series=MonitorTimeSeries(timestamp_col=ts, granularities=["30 minutes"]),
  notifications=MonitorNotifications(
        # Notify the given email when a monitoring refresh fails or times out.
        on_failure=MonitorDestination(
            email_addresses=["your_email@domain.com"]
        )
    )
)

이벤트 유형당 최대 5개의 이메일 주소가 지원됩니다(예: "on_failure").

메트릭 테이블에 대한 액세스 제어

모니터에서 만든 메트릭 테이블 및 대시보드는 모니터를 만든 사용자가 소유합니다. Unity 카탈로그 권한을 사용하여 메트릭 테이블에 대한 액세스를 제어할 수 있습니다. 작업 영역 내에서 대시보드를 공유하려면 대시보드 오른쪽 위에 있는 공유 단추를 사용합니다.

모니터 삭제

모니터를 삭제하려면 다음을 수행합니다.

from databricks.sdk import WorkspaceClient

w = WorkspaceClient()
w.quality_monitors.delete(table_name=f"{catalog}.{schema}.{table_name}")

이 명령은 모니터에서 만든 프로필 테이블 및 대시보드를 삭제하지 않습니다. 별도의 단계에서 해당 자산을 삭제하거나 다른 위치에 저장할 수 있습니다.

예제 Notebook

다음 예제 Notebook에서는 모니터를 만들고, 모니터를 새로 고치고, 만든 메트릭 테이블을 검사하는 방법을 보여 줍니다.

Notebook 예제: 시계열 프로필

이 Notebook에서는 TimeSeries 형식 모니터를 만드는 방법을 보여 줍니다.

TimeSeries Lakehouse Monitor 예제 Notebook

Notebook 가져오기

Notebook 예제: 유추 프로필(회귀)

이 Notebook에서는 회귀 문제에 대한 InferenceLog 형식 모니터를 만드는 방법을 보여줍니다.

유추 Lakehouse Monitor 회귀 예제 Notebook

Notebook 가져오기

Notebook 예제: 유추 프로필(분류)

이 Notebook에서는 분류 문제에 대한 InferenceLog 형식 모니터를 만드는 방법을 보여 줍니다.

추론 Lakehouse Monitor 분류 예제 Notebook

Notebook 가져오기

Notebook 예제: 스냅샷 프로필

이 Notebook에서는 Snapshot 형식 모니터를 만드는 방법을 보여 줍니다.

스냅샷 레이크하우스 모니터 예제 Notebook

Notebook 가져오기