Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Cortex Framework 관측 가능성

엔터프라이즈급 데이터 플랫폼을 성공적으로 실행하고 운영하려면 파이프라인 실행, 데이터 품질, 운영 오류를 파악하는 것이 중요합니다.

Cortex Framework는 두 가지 고유한 수명 주기에 걸쳐 관측 가능성을 분류합니다.

배포 시간 관측 가능성: CLI 도구 실행 중에 구성 로드, 템플릿 컴파일, 검증 체크, 배포 작업, API 원격 분석을 추적합니다.
런타임 관측 가능성: 내에서 실행되는 배포된 데이터 파이프라인의 실행, 파이프라인 진행률, 쿼리 성능, 데이터 품질 어설션, 자동 알림을 추적합니다 Google Cloud.

배포 시간 관측 가능성

배포 시간 관측 가능성은 CLI 도구 (예: uv run cortex-build, uv run cortex-deploy, uv run cortex-build-and-deploy, uv run cortex-demo, uv run cortex-kc-sync)의 실행에 중점을 둡니다.

로컬 콘솔 로깅

CLI 명령어를 실행하면 Cortex Framework가 진행률을 콘솔 (stdout)에 직접 로깅합니다.

로그 수준: 기본적으로 로그는 INFO 수준으로 출력됩니다.
시각적 강조표시: 메시지는 오류와 경고를 동적으로 강조표시하도록 색상으로 구분됩니다:
- ❌ 오류 (빨간색)는 실행을 중지하는 심각한 실패를 나타냅니다.
- ⚠️ 경고 (주황색)는 잠재적인 구성 이상 또는 차단되지 않는 문제를 나타냅니다.
타임스탬프 및 소스: 모든 로그 줄에는 정확한 추적을 위해 실행 시간과 활성 Python 클래스 또는 모듈 이름이 표시됩니다.

영구 로컬 로그 파일

모든 명령어 실행 시 Python 오케스트레이터는 전체 실행 로그를 시스템의 임시 디렉터리에 있는 임시 로그 파일로 자동 스트리밍합니다.

/tmp/cortex-framework-logs-<YYYYMMDD-HHMM>.log

정확한 경로는 CLI 도구가 시작되는 동안 콘솔에 출력됩니다. 이러한 파일에는 포괄적인 로그 세부정보 (예상치 못한 오류의 스택 트레이스 포함)가 포함되어 있으며 CLI 도구를 실행하는 동안 발생한 문제를 디버깅하거나 지원 요청에 연결할 때 매우 유용합니다.

Google Cloud 환경 검증

빌드, 배포 또는 동기화 작업을 실행하기 전에 오케스트레이션 엔진이 GcpEnvironmentChecker 유틸리티를 실행합니다. 이 검사는 다음을 검증합니다.

필수 API: 중요한 Google Cloud API가 사용 설정되어 있는지 확인합니다 (예: bigquery.googleapis.com, dataform.googleapis.com).
데이터 세트 존재: 필요한 원시 데이터 세트와 타겟 데이터 세트가 존재하거나 생성될 수 있는지 확인합니다.
위치 및 리전: 타겟 데이터 세트가 소스 데이터 세트의 지리적 리전과 일치하는지 확인합니다.
용량 및 설정: 예약 설정 및 카탈로그 구성을 검증합니다.

불일치는 서비스 호출을 하기 전에 이를 해결하는 방법에 대한 권장사항과 함께 오류로 로깅됩니다. Google Cloud

원격 분석

배포 및 동기화 프로세스 중에 Cortex Framework는 익명의 채택, 변형, 프레임워크 버전 원격 분석을 에 로깅합니다. Google Cloud작동 방식에 대한 세부정보와 선택 해제 방법에 대한 안내는 원격 분석을 참조하세요.

런타임 관측 가능성

빌드 및 배포되면 Cortex Framework에 부합하는 데이터 레이어와 데이터 제품이 Dataform 및 BigQuery 내에서 완전히 실행됩니다. 따라서 런타임 관측 가능성은 Google Cloud 운영 제품군과 직접 통합됩니다.

파이프라인 실행 로깅

배포된 모든 파이프라인은 Cloud Logging 및 실행 도구를 사용하여 추적됩니다.

Dataform 실행 로그: Dataform은 모든 컴파일 및 실행 이벤트를 로깅합니다. 이러한 세부정보는 Google Cloud 콘솔에서 액세스하거나 Dataform API를 사용하여 프로그래매틱 방식으로 액세스할 수 있습니다.
BigQuery 작업 기록: Dataform 파이프라인으로 구체화된 각 테이블과 뷰는 BigQuery 내에서 SQL 쿼리를 실행합니다. 자세한 리소스 사용량, 쿼리 성능, 처리된 바이트, 실행 타임스탬프는 BigQuery 작업 기록에 로깅됩니다.

파이프라인 모니터링

파이프라인 상태, 출시 구성, 실행 기록을 시각적으로 또는 프로그래매틱 방식으로 모니터링할 수 있습니다.

Dataform 웹 UI: Dataform 콘솔로 이동하여 다음 작업을 실행합니다.
- 컴파일된 데이터 모델을 검사하고 컴파일된 그래프를 시각화합니다.
- 출시 구성, 컴파일된 템플릿, 활성 환경의 상태를 확인합니다.
- 현재 및 이전 워크플로 실행의 기록과 세부정보를 모니터링합니다.
Cloud Monitoring 통합: 커스텀 대시보드 패널을 통해 실행 기간, 활성 컴파일, 워크플로 작업 실패율과 같은 Dataform 파이프라인 측정항목을 추적합니다.

알림 및 데이터 품질

데이터 무결성을 보장하고 파이프라인 실패를 자동으로 신고하려면 다음 메커니즘을 사용하여 알림을 구성하세요.

데이터 품질 어설션

.sqlx 어설션 파일을 만들어 커스텀 데이터 검증 규칙 (예: 열이 null이 아닌지 확인, 기본 키가 고유한지 확인, 숫자 범위 검증)을 정의할 수 있습니다.

--assertions 매개변수를 사용하여 커스텀 어설션 파일을 제공할 수 있습니다. bash uv run cortex-deploy --config config/config.yaml --assertions config/assertions.sqlx
파이프라인 실행 중에 Dataform은 이러한 검증 쿼리를 실행합니다. 어설션 쿼리가 행을 하나 이상 반환하면 검증이 실패하고 파이프라인 실행이 즉시 실패로 표시됩니다.
데이터 검증 규칙 작성에 대한 자세한 내용은 공식 Dataform 어설션 문서를 참조하세요.

어설션 파일 예시 (`assertions.sqlx`)

NULL 값과 중복된 고객 레코드를 확인하는 Dataform 어설션 쿼리의 예시입니다. 이 쿼리가 행을 반환하면 어설션이 실패하고 실행 워크플로가 중지됩니다.

config {
  type: "assertion",
  description: "Ensure customer_number_kunnr is not null and unique"
}

-- Check for NULL values
(
  SELECT
    "customer_number_kunnr is NULL" AS error_message
  FROM
    ${ref("customers")}
  WHERE
    customer_number_kunnr IS NULL
)
UNION ALL
-- Check for duplicate keys
(
  SELECT
    CONCAT("Duplicate customer number found: ", customer_number_kunnr) AS error_message
  FROM
    ${ref("customers")}
  GROUP BY
    customer_number_kunnr,
    client_mandt
  HAVING
    COUNT(*) > 1
)

Cloud Alerting 정책

문제가 발생할 때 엔지니어링 또는 운영팀에 알리도록 표준 Google Cloud Alerting 정책을 설정합니다.

로그 기반 알림: 로그에서 오류 이벤트, 실패한 워크플로 실행 또는 컴파일러 문제가 감지될 때 트리거되는 Cloud Logging에서 알림을 만듭니다.
측정항목 기반 알림: 실행 기간 또는 컴파일 실패를 기반으로 Cloud Monitoring에서 기준점을 정의합니다.
알림 채널: 이러한 알림을 구성하여 문제를 팀의 기본 커뮤니케이션 채널로 라우팅합니다.