워크플로 모니터링

이 페이지에서는 워크플로 배포 및 실행을 모니터링하는 데 도움이 되는 정보를 제공합니다.

워크플로 배포 및 삭제 로그 액세스

Google Cloud 콘솔에서 워크플로 배포 및 삭제와 관련된 오류 로그에 액세스할 수 있습니다.

Google Cloud 콘솔에서 Workflows 페이지로 이동합니다.

Workflows로 이동
워크플로 이름을 클릭하여 워크플로 세부정보 페이지를 표시합니다.
로그 탭을 클릭합니다.
심각도별로 로그를 필터링하려면 기본값 목록에서 표시할 로그 유형을 선택합니다.

워크플로 실행 결과에 액세스

Google Cloud Console에서 또는 gcloud CLI를 사용하여 워크플로 실행 결과에 액세스할 수 있습니다.

콘솔

Google Cloud 콘솔에서 Workflows 페이지로 이동합니다.

Workflows로 이동
워크플로 실행 결과에 액세스하려면 워크플로 이름을 클릭하여 워크플로 세부정보 페이지로 이동합니다.
특정 실행에 대한 자세한 내용을 확인하려면 실행 탭의 목록에서 실행 ID를 클릭하여 실행 세부정보 페이지로 이동합니다.

참고: 실행 세부정보 페이지에 액세스하려면 workflows.workflows.get, workflows.executions.get, workflows.stepEntries.list 권한이 포함된 역할이 있어야 합니다. 자세한 내용은 Workflows 역할 및 권한과 액세스 관리를 참조하세요.
요약 탭에서 각 실행에는 다음 정보가 포함됩니다.
- 실행 상태: 현재 또는 최종 워크플로 단계를 포함하여 워크플로의 종료 상태를 나타냅니다.
- 실행 시작: 실행이 시작된 시간입니다.
- 실행 종료: 실행이 종료된 시간입니다.
- 실행 기간: 경과된 총 시간입니다. 이 정보는 네트워크 오류나 연결 문제가 있음을 나타낼 수 있습니다.
- 워크플로 이름: 워크플로 이름입니다.
- 워크플로 버전: 실행 시점의 현재 버전입니다.
- 호출 로깅 수준: 실행 중에 적용된 호출 로깅 수준입니다. 이 문서에서 호출 로깅을 참조하세요.
- 입력: 워크플로에 전달된 런타임 인수입니다(있는 경우).
- 출력: 워크플로의 출력입니다. 실행이 실패하면 실행 오류로 이어진 예외가 포함됩니다. 이 문서에서 실행 오류 메시지를 참조하세요.
워크플로 실행 기록을 단계 항목 목록으로 보려면 단계 탭을 클릭합니다. 자세한 내용은 실행 단계 기록 보기를 참조하세요.
워크플로 실행 로그를 보려면 로그 탭을 클릭합니다.
실행 로그를 필터링하려면 테이블 상단의 필터 필드를 사용합니다. 예를 들어 실패한 실행 시도만 표시하려면 필터의 텍스트 필드에 failed를 입력합니다.

gcloud

워크플로 실행에 대한 전체 목록을 보려면 다음 명령어를 입력합니다.
```
gcloud workflows executions list WORKFLOW_NAME
```
WORKFLOW_NAME을 워크플로 이름으로 바꿉니다. 관심 있는 실행의 실행 ID를 복사합니다.

워크플로 실행 로그를 보려면 다음 명령어를 입력합니다.

gcloud workflows executions describe \
    --workflow=WORKFLOW_NAME \
    EXECUTION_ID

다음을 바꿉니다.

WORKFLOW_NAME: 워크플로의 이름
EXECUTION_ID: 실행의 고유 ID입니다.

이 명령어는 다음과 유사한 출력을 반환합니다.

argument: 'null'
endTime: '2022-07-19T12:40:07.070039707Z'
error:
 context: |-
    The argument of 'in' must be a dict or an array; got: null
    in step "checkSearchTermInInput", routine "main", line: 12
 payload: "{"message":"The argument of 'in' must be a dict or an array; got: null"

    ,"tags":["TypeError"]}"
 stackTrace:
    elements:
    - position:
       column: '26'
       length: '24'
       line: '12'
       routine: main
       step: checkSearchTermInInput
name: projects/1051295516635/locations/us-central1/workflows/myFirstWorkflow/executions/17ffc89c-0a27-4d2f-8356-e681d949a3d3
startTime: '2022-07-19T12:40:07.024823663Z'
state: FAILED
status:
 currentSteps:
 - routine: main
    step: checkSearchTermInInput
workflowRevisionId: 000001-ac2

출력에는 다음 정보가 포함됩니다.

argument: 워크플로에 전달된 런타임 인수입니다(있는 경우).
endTime: 실행이 종료된 시간입니다.
error: 실행 실패를 일으킨 예외의 일부로 발생한 오류 메시지입니다.
name: 프로젝트 이름, 워크플로 위치, 워크플로 이름, 실행 ID를 포함한 실행의 전체 이름입니다.
startTime: 실행이 시작된 시간입니다.
state: 워크플로의 종료 상태를 나타냅니다.
status: 실행의 현재 또는 최종 워크플로 단계입니다.
workflowRevisionID: 실행 시점의 현재 버전입니다.

실행 오류 맵

실행 중 워크플로에서 try/except 블록으로 포착되지 않은 오류가 발생하면 실행이 실패하고 오류를 설명하는 오류 맵(JSON 딕셔너리)이 반환됩니다.

워크플로 실행 중 발생한 오류에는 오류 원인을 파악하는 데 도움이 되는 태그가 포함됩니다. 예를 들어 커넥터에서 반환된 오류에는 다음과 비슷한 두 개의 키(tags 및 message)가 있을 수 있습니다.

{'tags': ['SystemError'], 'message': 'an error has occurred'}

둘 이상의 태그가 있을 수 있습니다. 특정 태그를 확인하려면 표현식을 사용하면 됩니다. 예를 들면 다음과 같습니다.

${'SystemError' in e.tags}

문자열로 반환된 오류 데이터에 액세스

일부 커넥터 및 HTTP API는 오류를 반환하기 전에 오류를 문자열로 직렬화합니다. 표준 라이브러리 함수를 사용하여 페이로드를 원래 오류로 복원할 수 있습니다. 예를 들어 오류 문자열을 맵으로 변환하려면 json.decode 및 text.encode 함수를 사용하면 됩니다.

json.decode(text.encode(ERROR_FROM_API))

오류 태그

다음 표에서는 여러 오류 태그의 의미를 설명합니다.

태그	설명
AuthError	HTTP 요청에 대한 사용자 인증 정보 생성이 실패할 때 발생합니다.
ConnectionError	엔드포인트에 연결이 성공적으로 설정되었지만 데이터 전송 중에 연결에 문제가 있으면 발생합니다. 전체 응답이 수신되기 전에 연결이 종료되며 메시지가 엔드포인트로 전송되지 않았을 수 있습니다. 재시도가 멱등적이지 않을 수 있습니다.
ConnectionFailedError	API 엔드포인트로 연결이 설정되지 않았을 때 발생합니다. 예를 들어 잘못된 도메인 이름, DNS 변환 문제 또는 기타 네트워크 문제로 인해 발생할 수 있습니다. 재시도가 멱등적입니다.
HttpError	HTTP 오류 상태와 함께 HTTP 요청이 실패할 때 발생합니다. 이 예외가 발생하면 응답은 다음 요소가 포함된 지도입니다. `tags`—`HttpError` 문자열이 있는 목록 `message`—인간이 읽을 수 있는 오류 메시지 `code`—HTTP 응답 상태 코드 `headers`—응답 헤더 `body`—응답 본문
IndexError	시퀀스 하위 스크립트가 정수 범위를 벗어날 때 발생합니다.
KeyError	지도 키가 기존 키 집합에 없을 때 발생합니다.
OperationError	장기 실행 작업이 실패할 때 발생합니다.
ParallelNestingError	병렬 단계를 중첩할 수 있는 최대 깊이가 초과될 때 발생합니다.
RecursionError	인터프리터에서 최대 호출 스택 깊이 초과를 감지하면 발생합니다.
ResourceLimitError	일부 리소스 한도가 소진될 때 발생합니다. 내부적으로 발생할 때 이러한 유형의 오류는 포착될 수 없으며, 즉각적인 실행 실패를 일으킵니다.
ResponseTypeError	장기 실행 작업이 잘못된 유형의 응답을 반환할 때 발생합니다.
SystemError	인터프리터에서 내부 오류가 발견될 때 발생합니다.
TimeoutError	시스템 함수가 시스템 수준에서 시간 초과될 때 발생합니다.
TypeError	작업 또는 함수가 호환되지 않는 유형의 객체에 적용될 때 발생합니다. 연결된 값은 유형 불일치에 대한 세부정보를 제공하는 문자열입니다.
UnhandledBranchError	하나 이상의 브랜치 또는 반복에서 처리되지 않은 런타임 오류가 최대 개수까지 발생할 때 발생합니다.
ValueError	작업 또는 함수에 유형이 올바르지만 값이 잘못된 인수가 수신될 때 발생하며, `IndexError`와 같이 보다 정확한 예외로 상황이 설명되지 않습니다.
ZeroDivisionError	나누기 또는 모듈로 연산의 두 번째 인수가 0일 때 발생합니다. 연결된 값은 피연산자 유형 및 연산을 나타내는 문자열입니다.

raise 문법을 사용하여 커스텀 예외를 발생시킬 수도 있습니다.

실행 상태 확인

워크플로 실행 상태를 확인하는 데에는 유용한 몇 가지 명령어가 있습니다.

워크플로의 실행 시도와 해당 ID의 목록을 검색하려면 다음 명령어를 입력합니다.
```
gcloud workflows executions list WORKFLOW_NAME
```
WORKFLOW_NAME을 워크플로 이름으로 바꿉니다.

이 명령어는 다음과 비슷한 NAME 값을 반환합니다.

projects/PROJECT_NUMBER/locations/REGION/workflows/WORKFLOW_NAME/executions/EXECUTION_ID

다음 명령어에 사용할 실행 ID를 복사합니다.
실행 시도 상태를 확인하고 시도가 완료될 때까지 기다리려면 다음 명령어를 입력합니다.
```
gcloud workflows executions wait EXECUTION_ID
```
EXECUTION_ID를 실행 시도의 ID로 바꿉니다.

이 명령어는 실행 시도가 완료될 때까지 기다린 후 결과를 반환합니다.
마지막 실행이 완료될 때까지 기다린 후 완료된 실행 결과를 반환하려면 다음 명령어를 입력합니다.
```
gcloud workflows executions wait-last
```
동일한 gcloud 세션에서 이전 실행 시도를 수행한 경우 이 명령어는 이전 실행 시도가 완료될 때까지 기다린 후 완료된 실행 결과를 반환합니다. 이전 시도가 없으면 gcloud가 다음 오류를 반환합니다.
```
ERROR: (gcloud.workflows.executions.wait-last) [NOT FOUND] There are no cached executions available.
```
마지막 실행 상태를 가져오려면 다음 명령어를 입력합니다.
```
gcloud workflows executions describe-last
```
동일한 gcloud 세션에서 이전 실행 시도를 수행한 경우에는 이 명령어가 실행 중인 상태일지라도 마지막 실행 결과를 반환합니다. 이전 시도가 없으면 gcloud가 다음 오류를 반환합니다.
```
ERROR: (gcloud.beta.workflows.executions.describe-last) [NOT FOUND] There are no cached executions available.
```

실행 필터링

workflows.executions.list 메서드에서 반환된 워크플로 실행 목록에 필터를 적용할 수 있습니다.

다음 필드를 필터링할 수 있습니다.

duration
endTime
executionId
label
startTime
state
stepName
workflowRevisionId

예를 들어 라벨(labels."fruit":"apple")을 필터링하려면 다음과 비슷한 API 요청을 수행할 수 있습니다.

GET https://workflowexecutions.googleapis.com/v1/projects/MY_PROJECT/locations/MY_LOCATION/workflows/MY_WORKFLOW/executions?view=full&filter=labels.%22fruit%22%3A%22apple%22"

각 항목의 의미는 다음과 같습니다.

view=full는 반환된 실행에 입력해야 하는 필드를 정의하는 뷰를 지정합니다. 이 경우에는 모든 데이터입니다.
labels.%22fruit%22%3A%22apple%22는 URL 인코딩 필터 구문입니다.

자세한 내용은 AIP-160 - 필터링을 참조하세요.

Cloud Logging에 로그 전송

Workflows는 Cloud Logging에 워크플로 실행에 대한 실행 로그를 자동으로 생성합니다.

호출 로깅을 사용 설정할 수도 있습니다. 또는 소스에서 sys.log 함수를 사용하는 커스텀 로그를 만들 수 있습니다. 호출 로깅과 커스텀 로그를 사용하면 워크플로 실행 중에 로그가 Logging으로 전송되는 시기를 제어할 수 있습니다. 이는 특히 워크플로를 디버깅할 때 유용합니다.

engine_call 및 executions_system 로깅 proto 파일을 포함한 자세한 내용은 이 GitHub 저장소를 참조하세요.

실행 로그

각 워크플로 실행마다 실행이 시작될 때와 끝날 때 각각 하나씩 최소 2개의 실행 로그가 자동으로 트리거됩니다.

Logging에서 제공되는 Workflows 플랫폼 로그에 대한 자세한 내용은 Google Cloud Platform 로그를 참조하세요.

호출 로깅

워크플로 실행 중 각 호출 단계가 로깅되고 단계 이름, 함수 이름, 함수 인수, 호출 응답이 반환되도록 플래그를 설정할 수 있습니다. 또는 포착된 예외나 호출을 중지하는 예외를 모두 로깅할 수 있습니다.

명시적인 호출 단계만 로깅됩니다. 예를 들어, 하위 워크플로 또는 라이브러리 함수 호출 등이 있습니다. 표현식 내에서 또는 표준 라이브러리 함수 내에서의 호출(예: sys.log에서 http.post)과 커넥터 내에서의 호출은 로깅되지 않습니다.

HTTP Authorization 요청 헤더는 HTTP 호출의 로그에서 수정됩니다.

워크플로 정의 또는 워크플로 실행에 호출 로깅을 적용할 경우 필요한 로깅 수준을 지정할 수 있습니다. 실행 로그 수준이 지정되지 않은(기본값) 한 실행 로그 수준이 워크플로 로그 수준보다 우선합니다. 이 경우 워크플로 로그 수준이 적용됩니다.

Cloud Logging에서 설정한 로그 항목 크기 한도는 호출 로깅에도 적용됩니다.

커스텀 로그

워크플로를 실행하는 동안 Logging에 로그 항목을 만들려면 표준 라이브러리 sys.log 함수를 호출하는 워크플로에서 단계를 정의합니다.

YAML

  - step1:
      assign:
          - varA: "Hello"
          - varB: "World"
  - logStep:
      call: sys.log
      args:
          text: TEXT
          severity: SEVERITY 
  - step2:
      return: ${varA + " " + varB}

JSON

    [
      {
        "step1": {
          "assign": [
            {
              "varA": "Hello"
            },
            {
              "varB": "World"
            }
          ]
        }
      },
      {
        "logStep": {
          "call": "sys.log",
          "args": {
            "text": "TEXT",
            "severity": "SEVERITY"
          }
        }
      },
      {
        "step2": {
          "return": "${varA + " " + varB}"
        }
      }
    ]

로그 항목을 만들 때 다음을 정의합니다.

TEXT: 필수 항목입니다. 로깅할 텍스트입니다. 지도의 값을 로깅해야 하면 ${json.encode_to_string(myMap)}을 사용합니다.
SEVERITY: 선택사항입니다. 로그 항목의 심각도 수준입니다. 예를 들면 INFO, WARNING, CRITICAL입니다.

자세한 내용은 sys.log 함수 참조를 확인하세요.

필수 권한

호출 로깅을 적용하거나 Logging에 커스텀 로그를 전송하려면 logging.logEntries.create 권한이 포함된 서비스 계정(예: roles/logging.logWriter 역할)에 워크플로를 연결해야 합니다. 워크플로로 업데이트된 서비스 계정을 변경해야 하면 워크플로 업데이트를 참조하세요. 서비스 계정 만들기 및 역할 할당에 대한 자세한 내용은 프로젝트, 폴더, 조직 액세스 관리를 참조하세요.

워크플로 로그 보기

Workflows 또는 Logging에서 로그를 볼 수 있습니다. 단일 워크플로의 로그를 보려면 Workflows에서 로그 탭을 사용합니다. 모든 워크플로의 로그에 대한 집계 뷰를 가져오려면 Logging에서 로그 탐색기 페이지를 사용합니다.

Workflows에서 로그 보기

Workflows에서 워크플로의 로그를 보려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 Workflows 페이지로 이동합니다.

Workflows로 이동
워크플로 로그에 액세스하려면 워크플로 이름을 클릭하여 세부정보 페이지로 이동합니다.
로그를 보려면 로그를 클릭합니다.
심각도별로 로그를 필터링하려면 기본값 목록에서 표시할 로그 유형을 선택합니다. 기본적으로 모든 심각도 수준의 로그가 표시됩니다.

워크플로 세부정보 페이지의 로그 탭에는 다음 유형의 로그가 표시됩니다.

Logging으로 전송되는 로그
워크플로 정의 업데이트와 같이 워크플로에서 수행되는 모든 작업의 감사 로그

Logging에서 로그 보기

Logging에서 로그를 보려면 다음 안내를 따르세요.

Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.

로그 탐색기로 이동
쿼리 빌더에서 리소스를 클릭하고 workflow를 입력합니다. 목록에서 Cloud Workflow를 선택하고 추가를 클릭합니다.
쿼리 실행을 클릭합니다.

Logging에서 로그 보기에 대해 자세히 알아보려면 로그 탐색기 사용을 참조하세요.