워크플로 디버그하기

약 25분 · 단계 하나 실행, 데이터 미리 보기, 로그 읽기, 입력 추적

워크플로의 무언가가 이상합니다. 단계가 빨간색으로 표시되었거나, 하위 단계의 숫자가 잘못되어 보이거나, 실행이 중간에 멈췄습니다. 이 튜토리얼에서는 그 이유를 찾아내는 수동 도구 모음을 차례로 살펴봅니다. 단계 하나를 단독으로 실행하고, 생성된 결과를 미리 보고, 워크플로 로그를 읽고, 종속성 감사로 입력이 어디서 왔는지 추적하고, 오류 자체를 읽습니다. 각 도구는 서로 다른 질문에 답하며, 함께 사용하면 대개 추측 없이 원인에 도달할 수 있습니다.

설명을 들으며 진행하고 싶으신가요? AI 지원 방식은 같은 조사를 대화로 진행합니다. 이 튜토리얼은 수동 버전으로, 여기 있는 모든 것을 직접 진행합니다. 어시스턴트가 실제로 무엇을 보고 있는지 알 수 있도록 최소한 한 번은 해 볼 만한 가치가 있습니다.

디버깅 루프

대부분의 워크플로 디버깅은 어떤 도구부터 사용하든 같은 짧은 루프를 따릅니다.

각 도구는 질문 하나에 답합니다. 네 가지를 모두 사용해야 하는 경우는 드물지만, 이 순서로 진행합니다.

사전 요구 사항

• 추적할 문제(빨간색 단계, 잘못된 결과 또는 중지된 실행)가 있는 프로젝트와 워크플로가 있는 PlaidCloud 워크스페이스.
• 대부분의 작업을 수행하게 될 캔버스인 시각적 워크플로 디자이너에 대한 이해.

1단계: 문제가 있는 단계만 실행하기

변경 사항 하나를 테스트하기 위해 전체 워크플로를 다시 실행하지 마십시오. 느리고, 이미 신뢰하는 작업까지 다시 수행하게 됩니다. 조사 중인 단계 하나만 실행하십시오.

1. 시각적 워크플로 디자이너에서 워크플로를 엽니다.
2. 테스트할 단계를 마우스 오른쪽 버튼으로 클릭하고 컨텍스트 메뉴에서 단계 실행을 선택합니다.
3. 단계는 소스 테이블에 이미 존재하는 데이터를 대상으로 단독 실행됩니다.

디버깅할 때는 마지막 요점이 중요합니다. 단계는 소스 테이블을 현재 상태 그대로 읽습니다. 상위 단계가 아직 실행되지 않았거나 오래된 데이터로 실행되었다면, 이 단계를 단독으로 실행해도 그 상태가 그대로 반영됩니다. 바로 4단계에서 이를 잡아내는 방법을 설명합니다.

자세한 내용은 워크플로에서 단계 하나 실행하기를 참고하십시오.

2단계: 단계가 생성한 내용 미리 보기

단계가 실행되면, 올바른지 판단하기 전에 실제로 무엇이 기록되었는지 확인하십시오. 데이터 미리 보기 드로어는 단계의 출력 데이터를 캔버스 하단에 고정된 형태로, 형식이 지정된 열과 함께 처음 100개 행을 보여 줍니다.

드로어에 들어가는 방법은 세 가지이며, 모두 같은 드로어로 연결됩니다.

• 단계 타일 위에 마우스를 올립니다. 타일 오른쪽 아래 모서리에 작은 찾아보기(테이블) 글리프가 서서히 나타납니다. 이를 클릭합니다.
• 단계를 마우스 오른쪽 버튼으로 클릭하고 출력 데이터 미리 보기를 선택합니다.
• 인스펙터에서 단계의 출력 섹션에 있는 출력 카드에서 눈 아이콘을 클릭합니다.

무엇을 확인할지는 증상에 따라 다릅니다.

증상	미리 보기에서 확인할 내용
잘못되었거나 누락된 열	단계가 예상한 열을 생성했습니까? 조인이나 열 선택이 잘못된 경우 여기에서 가장 먼저 드러납니다.
행이 너무 적거나 많음	머리글에 전체 약 M개 행 중 처음 N개 표시가 나타납니다. 총 개수가 대략 맞습니까?
빈 출력	드로어에 테이블이 비어 있음(실행되었으나 행 없음) 또는 아직 데이터 없음 — 단계를 실행하십시오(실행된 적 없음)가 표시됩니다.
의심스러운 값	열을 정렬하여 null이나 이상값을 맨 위로 올립니다.

드로어가 열려 있는 동안에는 다른 단계를 클릭하면 미리 보기가 해당 단계의 출력으로 전환되므로, 단계 체인을 따라 내려가면서 데이터가 처음 잘못되는 지점을 확인할 수 있습니다. 필터링하거나, 일부만 보거나, 처음 100개 행을 넘어서 보려면 드로어 머리글에서 테이블 탐색기에서 열기를 클릭하십시오.

자세한 내용은 단계 데이터 미리 보기에 있습니다.

3단계: 워크플로 로그 읽기

미리 보기는 출력이 어떻게 생겼는지 알려 주고, 로그는 단계가 실행될 때 무슨 일이 있었는지 알려 줍니다. 실패했다면 오류 메시지도 포함됩니다.

단계가 실행되고 경고가 발생하면 해당 이벤트가 워크플로 로그에 기록되며, 프로젝트 영역의 로그 탭에서 볼 수 있습니다. 시각적 워크플로 디자이너 안에서는 도구 모음의 로그 보기 버튼이 열려 있는 워크플로로 이미 필터링된 같은 보기를 엽니다.

1. 도구 모음의 로그 보기 버튼이나 프로젝트 영역의 로그 탭에서 로그 탭(프로젝트 로그)을 엽니다.
2. 로그 메시지 옆의 필터 컨트롤을 사용하여 관심 있는 단계와 실행으로 범위를 좁힙니다.
3. 로그 항목을 열어 세부 정보를 읽습니다. 실패한 단계의 오류 메시지가 여기에 있습니다.

프로젝트 수준 로그는 문제가 둘 이상의 워크플로에 걸쳐 있을 수 있는 경우를 위해 여러 워크플로에 걸친 보다 포괄적인 보기를 제공합니다. 워크플로 로그 보기를 참고하십시오.

오류 메시지 읽기. 로그 항목의 정확한 텍스트를 복사하십시오. 잘못된 조인 키, 형식 불일치, 누락된 소스 테이블은 각각 다르게 표시됩니다. 단계에서 오류가 발생하는 가장 흔한 두 가지 원인은 테이블 간 조인 키 불일치와 계산 열의 예기치 않은 null 값입니다. 메시지가 단계의 구성이 아니라 데이터를 가리킨다면 입력을 추적해야 한다는 신호입니다.

실제 예시. 변환 단계가 빨간색으로 바뀌었다고 가정해 봅시다. 로그를 열면 column "revenue" does not exist라고 표시됩니다. 소스 테이블에는 revenue가 아니라 net_revenue 열이 있습니다. 한 줄로 해결하려면 단계의 식에서 열 이름을 수정하면 됩니다. 해당 단계만 다시 실행하면 녹색으로 돌아옵니다. 한 번의 패스로 전체 루프가 끝난 것입니다.

4단계: 종속성 감사로 입력 추적하기

단계가 올바르게 구성되어 있는데도 잘못된 데이터를 생성하는 경우가 있습니다. 순서가 어긋나게 채워진 입력을 대상으로 실행되었기 때문입니다. 테이블에 데이터가 이미 있으면 단계는 오래되었거나 아직 업데이트되지 않은 데이터를 읽었는데도 정상적으로 실행되고 올바르게 보입니다. 아무 오류도 발생하지 않으므로 로그로는 볼 수 없는 실패입니다.

워크플로 종속성 감사는 바로 이런 경우를 위해 존재합니다. 서로 연결된 워크플로 전체의 데이터 및 워크플로 종속성을 분석하여, 입력이 읽히는 시점에 비추어 잘못된 순서로 채워지는 단계를 식별합니다.

다음과 같은 경우에 사용하십시오.

• 단계의 출력은 잘못되었지만 단계 자체에는 오류가 없는 경우.
• 단계의 순서를 바꾸거나 추가한 후 어떤 단계도 테이블이 만들어지기 전에 읽지 않는지 확인하려는 경우.
• 워크플로가 전체 실행에서는 “정상 작동”하지만 단계 하나만 실행하면 다른 숫자가 나오는 경우. 순서 종속성의 전형적인 징후입니다.

감사를 열고 읽는 방법은 종속성 감사 보기를 참고하십시오.

5단계: 워크플로가 오류를 처리하는 방식 결정하기

원인을 파악했다면, 앞으로 이 단계가 실패할 때 워크플로가 어떻게 동작할지 결정하십시오. 각 단계의 오류 처리는 단계 양식에서 설정하며 PlaidCloud는 세 가지 수준을 제공합니다.

동작	결과	사용 시점
워크플로 중지	실행이 중단되고 단계와 워크플로 모두에 오류 표시가 나타납니다.	기본값이자 가장 일반적입니다. 워크플로는 일반적으로 오류 없이 실행되어야 합니다.
계속 처리	단계에 오류가 표시되지만 워크플로는 이를 완료된 것으로 처리하고 계속 진행합니다.	누락된 데이터로 인해 오류가 발생해도 무방한 단계. 참고로 워크플로에는 오류 표시가 아니라 실행 중 표시가 나타납니다.
수정 워크플로 트리거	현재 워크플로가 중지되고 대신 수정 워크플로가 시작됩니다.	자동 알림 또는 수정. 계속 처리로 설정된 단계에는 작동하지 않습니다.

PlaidCloud는 실패한 단계를 지정한 횟수만큼, 초에서 시간 단위까지 선택적 지연을 두고 자동으로 다시 시도할 수도 있습니다. 실제 로직 버그가 있는 단계가 아니라 간헐적으로 실패하는 원격 시스템이나 데이터 소스에 연결하는 단계에 적합한 도구입니다. 단계 오류 관리를 참고하십시오.

6단계: 수정, 재실행, 확인

1. 조사 결과가 가리키는 변경을 수행합니다. 조인 키를 수정하거나, 상위 단계를 추가하거나, null을 생성하는 식을 수정하거나, 단계 순서를 바꿉니다.
2. 해당 단계만 다시 실행(1단계)하고 출력을 미리 봅니다(2단계). 실행 중에 드로어가 열려 있었다면 실행이 완료되는 즉시 자동으로 새로 고쳐집니다.
3. 단계가 올바르면 워크플로를 처음부터 끝까지 실행하고 로그를 보면서 전체 파이프라인에 문제가 없는지 확인합니다.

워크플로가 수행하는 작업(단계, 함수, 변수)을 영구 기록으로 남기려면 워크플로 계층의 보고서 아이콘에서 온디맨드 워크플로 보고서를 생성하십시오. 워크플로의 현재 상태를 반영하며, 수정이 끝난 후 문서로 활용하기 좋습니다. 워크플로 보고서 보기를 참고하십시오.

이것이 전체 루프입니다. 단계 하나를 단독으로 실행하고, 기록된 내용을 미리 보고, 로그에서 오류를 읽고, 종속성 감사로 입력을 추적한 다음, 다시 실행하여 수정을 확인했습니다. AI 어시스턴트가 하는 조사와 같지만, 이제 직접 진행할 수 있습니다.

다음 단계

• AI 어시스턴트로 워크플로 수정하기 — 같은 조사를 대화로 진행합니다
• 워크플로에서 단계 하나 실행하기 — 단계 하나를 단독으로 실행합니다
• 단계 데이터 미리 보기 — 데이터 미리 보기 드로어
• 워크플로 로그 보기 — 실행 이벤트와 오류가 기록되는 위치
• 종속성 감사 보기 — 순서가 어긋난 데이터 종속성을 찾아냅니다
• 단계 오류 관리 — 중지, 계속, 수정, 다시 시도
• 워크플로 보고서 보기 — 전체 워크플로에 대한 온디맨드 문서