재현 가능한 백링크 리포트를 위한 월간 실행 매뉴얼

월간으로 실행하는 이유

우리의 그래프는 약 한 달에 한 번 갱신됩니다. 매일 실행하면 동일한 수치가 반환됩니다.

더 자주 실행한다고 해서 리포트가 더 최신이 되는 것은 아니며, 설명 비용만 늘어납니다. 30개의 동일한 지점을 본 독자는 파이프라인에 문제가 있다고 생각할 것입니다.

매월 의도적으로 하루를 선택하세요. Ideally 이전 갱신이 안정화된 후 일주일 정도 지난 날짜가 좋습니다. 날짜를 파일 이름에 기록하여 스케줄 자체를 문서화하세요.

캘린더를 먼저 정하고 리포트가 그 일정에 따르도록 하세요. 노트북을 열 때마다 다시 빌드되는 리포트는 명확한 날짜가 없으며, 이는 검토 시 설명하기 어렵습니다.

숫자 외에 저장할 데이터

리포트의 절반은 메타데이터이므로, 숫자와 함께 저장하세요.

가져온 날짜, 작업 이름, 매개변수(per, sort, order) 및 응답의 credits 필드를 스냅샷 옆에 작은 사이드카 파일로 기록하세요. 6개월 후 동료가 10월이 9월과 다르게 보이는 이유를 물을 때, 이 파일이 오후를 허비하는 대신 10초 만에 답변해 줄 것입니다.

스크립트의 git 커밋과 renv의 패키지 버전을 추가하세요. 어떤 코드와 인덱스 상태로 차트가 생성되었는지 알 수 없는 리포트는 티블리얼(tibble)이 아무리 깔끔해도 분석이 아닌 스크린샷입니다.

최소한의 targets 레이아웃

계획이 작다면 세 개의 타겟(target)이면 충분합니다.

첫 번째 타겟은 API에서 데이터를 가져와 날짜가 명시된 파일을 작성하고, 두 번째 타겟은 파일을 읽어 티블리얼을 구축하며, 세 번째 타겟은 Quarto 문서를 렌더링합니다. 네트워크에 접근하는 것은 첫 번째 타겟뿐이므로, 다른 타겟은 원하는 만큼 오프라인에서 다시 실행할 수 있으며 차트가 우연히 변경되지 않습니다.

renv로 패키지 버전을 고정하고, 리포트 하단에 세션 정보를 기록하며, 대량 점수 매기기 페이지의 임계값 테이블을 코드 옆 저장소에 보관하세요. 비용 관련해서는 예산 페이지에서 한 달에 얼마가 들어야 하는지 확인할 수 있습니다.

무언가 실패하면 코드를 먼저 읽어보세요. HTTP 401은 키가 잘못되었거나 누락되었음을 의미합니다. HTTP 402는 크레딧이 부족했음을 의미합니다. 그 외의 모든 오류는 전체 로깅이 필요합니다. 분석에서 해당 단계를 다루며, 조인 예제는 스케줄링할 첫 번째 작업으로 적합합니다.

동료가 알기 전에 실패 사실을 인지하기

조용히 실패하는 재현 가능한 백링크 리포트는 실행되지 않은 리포트보다 더 큰 오해를 불러일으킵니다. 중요한 질문은 작업이 실패할 수 있는지 여부가 아니라, 누군가가 그 사실을 얼마나 빠르게 알게 되느냐입니다.

명확하게 실패하도록 설정하기

스케줄링된 작업은 HTTP 401 또는 402 응답 시 비-zero 상태로 종료하며, 스케줄러는 실패로 표시합니다. 이것이 가장 저렴한 알림 수단이며 추가 서비스가 필요하지 않습니다.

부분적 데이터 가져오기는 위험한 경우입니다. 스크립트가 30개 청크 중 20개 후에 파일을 작성하면 파일이 존재하며 정상처럼 보입니다. 임시 이름으로 작성한 후 성공 시에만 이름 변경을 수행하세요.

실패당 한 번의 메시지 전송

실패 알림 채널을 하나로 정하세요(예: 리포트 소유자에게 보내는 이메일이나 팀 채팅 메시지). 두 채널을 사용하면 확인해야 할 곳이 두 곳이 되어 아무도 확인하지 않을 가능성이 높아집니다.

메시지에는 실패한 타겟, 상태 코드 및 시간을 명시해야 합니다. 나머지 정보는 로깅에 포함하세요.

출력값이 타당한지 확인하기

실행이 성공했더라도 결과가 잘못될 수 있습니다. 행 수를 지난달과 비교하고, 사전에 설정한 임계값을 초과하는 감소가 발생하면 플래그를 지정하세요.

검증은 예상 범위 설정 정도로 간단할 수 있습니다. 목표는 차트가 클라이언트에게 전달되기 전에 반쯤 빈 스냅샷을 발견하는 것입니다.

리포트의 소유자 한 명 지정하기

리포트의 소유자를 한 명 지정하세요. 소유자가 없는 알림은 모두 읽지만 아무도 행동하지 않습니다.

소유자가 반드시 작업을 수정해야 하는 것은 아닙니다. 소유자는 늦은 리포트가 허용 가능한지 여부를 결정하고, 그 내용을 리포트 자체에 명시해야 합니다.

실행 매뉴얼 헤더에 소유자 이름을 기록하고, 소유자가 변경될 때 업데이트하세요. 이전 소유자가 적힌 실행 매뉴얼은 조용한 위험 요소입니다.

날짜 선택 및 첫 번째 작업 수동 실행

타이밍과 첫 번째 실행은 스케줄 유지 여부를 결정합니다. 둘 다 첫 달에 잘못 설정하기 쉽지만, 올바르게 설정하는 것은 비용이 적게 듭니다.

두 가지 결정을 한 번 기록해 두면 나중에 발생할 논쟁을 가장 많이 줄일 수 있습니다. 첫 번째는 날짜입니다. 두 번째는 타이머가 실행되는 위치입니다. 둘 다 실행 매뉴얼에 기록해야 하며, 누군가의 머릿속에 남아서는 안 됩니다.

하루를 선택하고 기록하세요

갱신이 안정화된 후 첫 번째 근무일과 같은 월의 고정된 날짜가月初의 추측보다 설명하기 더 쉽습니다.

날짜를 스케줄 파일 자체에 넣으세요. 그러면 타이밍이 코드의 일부가 되어 누군가의 캘린더에 있는 메모가 되지 않습니다.

첫 번째 작업을 수동으로 실행하세요

첫 스케줄링된 실행은 수동으로 진행해야 합니다. 스크립트를 직접 실행하고, 로그를 읽으며, 파일을 이전 버전과 비교한 후에야 타이머를 넘겨주세요.

첫 번째 실행은 시크릿 저장소도 테스트합니다. 로컬 머신에서는 작동하지만 CI에서는 누락된 키는 첫 스케줄링 실패의 흔한 원인입니다.

사이드카의 정직성 유지하기

사이드카 파일은 실행 내용을 기록합니다. 사람이 직접 작성하면 실행 내용과 어긋납니다. 스크립트가 작성하게 하고 사람은 읽기만 하세요.

스크립트가 건드리지 않은 사이드카는 기록이 아닌 메모이며, 리포트는 기록을 인용해야 합니다.

매월 사이드카와 파일을 비교하세요. 두 파일의 숫자가 다르면 스크립트가 인지하지 못한 방식으로 실행이 실패했다는 의미입니다.

타이머의 위치

호스팅 러너와 로컬 크론 항목은 서로 다른 방식으로 실패합니다. 호스팅 러너는 자체 설정으로 일시 중지될 수 있으며, 로컬 크론 항목은 머신이 절전 모드일 때 중지됩니다. 선택한 옵션을 확인하고 실제 스케줄링 전에 짧은 시간으로 타이머를 한 번 테스트하세요.

어떤 옵션을 선택하든, 타이머를 스크립트 옆 저장소에 기록하세요. 그러면 다음 사람이 작업이 어디에 있는지 알 수 있습니다.