바로 답하면, Cloudflare Workers Logs 쿼리 필터 대시보드 설정은 “실시간 확인”과 “저장 후 검색”을 분리해 설정하는 것이 핵심입니다. 배포 직후에는 Real-time logs로 새 요청이 들어오는지 빠르게 보고, 반복되는 오류 흐름은 Workers Logs에 저장된 데이터를 쿼리 필터로 좁혀 확인하는 방식이 실무에 맞습니다. 처음부터 모든 로그를 눈으로 훑기보다 서비스명, 환경, 요청 경로, 상태 코드, 예외 메시지 같은 기준을 정해 두면 장애 대응, 배포 검수, 월간 운영 리포트까지 같은 화면에서 이어갈 수 있습니다.
요약: Cloudflare Workers Logs는 Workers에서 나온 로그 데이터를 계정에 저장하고 대시보드에서 검색·필터링·분석하는 용도입니다. Real-time logs는 새 배포 직후의 즉시 피드백에 적합하지만 저장 용도는 아니므로, 운영용 기록 확인은 Workers Logs 중심으로 설계하는 편이 안전합니다. 메뉴명, 화면 위치, 보관 범위, 요금제별 제공 기능은 Cloudflare 업데이트와 계정 플랜에 따라 달라질 수 있으니 적용 전 공식 문서를 다시 확인하세요.
1. 먼저 결정할 것: 실시간 확인과 저장 로그의 역할 나누기
Cloudflare Workers를 운영할 때 흔한 실수는 대시보드에 보이는 로그 화면을 모두 같은 용도로 이해하는 것입니다. Real-time logs는 새 배포가 정상적으로 동작하는지, 요청이 실제로 도착하는지, 콘솔 메시지가 즉시 찍히는지 확인하기 좋습니다. 반면 Workers Logs는 나중에 다시 검색하고 필터를 적용해 흐름을 재구성하는 쪽에 가깝습니다. 따라서 운영 기준은 “방금 배포 확인은 Real-time logs, 반복 이슈 분석과 기록 보관은 Workers Logs”처럼 단순하게 잡는 것이 좋습니다.
이 구분을 해두면 팀 내부 설명도 쉬워집니다. 배포 담당자는 실시간 화면에서 새 요청을 확인하고, 운영 담당자는 저장된 로그에서 특정 시간대와 경로를 좁혀 봅니다. 개발자는 예외 메시지를 남길 때 어떤 키 이름을 써야 검색이 쉬운지 맞출 수 있습니다. 작은 프로젝트라도 이 규칙을 문서화해 두면 담당자가 바뀌어도 같은 방식으로 확인할 수 있습니다.
2. Workers Logs를 켜기 전 준비 체크리스트
설정 전에 로그로 무엇을 보고 싶은지 먼저 적어야 합니다. 모든 콘솔 출력이 유용한 것은 아닙니다. 예를 들어 요청 ID, 환경 이름, API 경로, 처리 단계, 결과 상태, 외부 API 응답 시간처럼 나중에 필터링할 수 있는 값을 중심으로 남겨야 합니다. 반대로 개인 식별이 가능한 값, 비밀 키, 내부 토큰, 불필요하게 긴 본문은 로그에 남기지 않는 편이 좋습니다. 이 글은 운영 도구 설정 안내이며, 계정 권한·데이터 처리 기준은 조직 정책에 맞춰 별도로 점검해야 합니다.
- Worker 이름과 배포 환경을 구분할 명명 규칙을 정합니다.
- 검색 기준이 될 키 이름을 정합니다. 예:
route,status,requestId,stage. - 오류 메시지는 사람이 읽을 수 있게 짧고 일관되게 남깁니다.
- 로그에 남기면 안 되는 값 목록을 팀 문서에 둡니다.
- 대시보드를 볼 사람에게 Cloudflare 계정 권한이 충분한지 확인합니다.
3. 대시보드에서 처음 볼 필터 기준
처음부터 복잡한 쿼리를 만들 필요는 없습니다. 가장 먼저 볼 기준은 시간대, Worker 이름, 배포 환경, 상태 코드, 특정 문자열입니다. 배포 직후에는 최근 15분 또는 1시간처럼 좁은 시간 범위를 잡고, 정상 요청과 오류 요청을 따로 봅니다. 이어서 특정 API 경로를 필터링하면 같은 오류가 전체 서비스 문제인지 특정 기능 문제인지 빠르게 나눌 수 있습니다.
로그 메시지를 설계할 때는 “나중에 이 문구로 검색할 수 있는가”를 기준으로 삼으면 좋습니다. failed처럼 넓은 단어보다 checkout_api_timeout, webhook_signature_mismatch처럼 기능과 현상이 함께 들어간 문구가 더 유용합니다. 단, 고객 정보나 내부 비밀 값이 섞이지 않도록 코드 리뷰 단계에서 로그 문장을 따로 확인하는 습관이 필요합니다.
4. 실무용 필터 표: 무엇을 언제 보면 좋을까
| 확인 목적 | 추천 필터 기준 | 판단 포인트 | 다음 행동 |
|---|---|---|---|
| 새 배포 확인 | 최근 시간대, Worker 이름 | 요청이 들어오고 로그가 생성되는가 | Real-time logs와 저장 로그를 함께 비교 |
| 특정 경로 오류 확인 | route 또는 URL path | 한 기능만 실패하는가 | 해당 핸들러와 외부 호출 부분을 점검 |
| 응답 지연 흐름 보기 | stage, duration, upstream | 어느 단계에서 시간이 늘어나는가 | 캐시, 외부 API, 코드 분기 순서로 축소 |
| 반복 메시지 정리 | message 문자열 | 같은 문구가 여러 배포에서 반복되는가 | 로그 문구를 원인별로 더 세분화 |
| 운영 리포트 준비 | 날짜 범위, 환경, 상태 | 주요 오류와 빈도가 설명 가능한가 | 대시보드 캡처와 쿼리 조건을 함께 보관 |
5. 콘솔 로그를 검색 가능한 문장으로 바꾸는 방법
Workers Logs를 제대로 쓰려면 코드 안의 로그 문장도 정리해야 합니다. “에러 발생” 같은 문장은 사람이 보기에는 편하지만 필터링에는 약합니다. 대신 처리 단계와 결과를 함께 넣으면 좋습니다. 예를 들어 auth_step_started, auth_step_failed_invalid_header, cache_lookup_miss, upstream_request_timeout처럼 단계와 결과를 일정한 패턴으로 남기면 대시보드에서 문자열 검색이 쉬워집니다.
팀이 작다면 처음에는 표준 키 5개만 정해도 충분합니다. requestId는 한 요청의 흐름을 묶는 데 쓰고, route는 기능 단위를 구분하는 데 씁니다. stage는 처리 단계를 보여주고, status는 정상·실패·건너뜀 같은 결과를 담습니다. message는 사람이 읽을 설명으로 남깁니다. 이런 방식은 복잡한 관측 도구를 바로 도입하기 전, Cloudflare 대시보드만으로도 운영 흐름을 정리하게 해줍니다.
6. Real-time logs와 Workers Logs를 함께 쓰는 배포 검수 순서
배포 직후에는 저장된 로그가 쌓이기를 기다리기보다 Real-time logs로 즉시 흐름을 보는 편이 빠릅니다. 새 버전 배포 후 테스트 요청을 보내고, 실시간 화면에서 요청 도착 여부와 콘솔 메시지를 확인합니다. 그 다음 Workers Logs에서 같은 시간대와 Worker 이름으로 검색해 저장된 데이터에서도 같은 흐름이 확인되는지 봅니다. 이 두 단계가 모두 맞아야 “실시간 확인도 되고, 나중에 재검색도 가능하다”고 말할 수 있습니다.
Cloudflare 공식 설명에서도 Real-time logs는 즉각적인 피드백에 유용하지만 Workers Logs 저장을 대체하는 용도는 아니라고 구분합니다. 이 차이를 문서에 써두면 팀원이 실시간 화면만 보고 기록 확인까지 끝났다고 착각하는 일을 줄일 수 있습니다. 특히 외부 알림이나 리포트로 이어질 예정이라면 저장 로그 쪽에서 다시 검색 가능한 조건을 꼭 남겨야 합니다.
7. 권한과 화면 변경 가능성 고지
Cloudflare 대시보드 메뉴명, 로그 보관 범위, 제공 쿼리 기능, 플랜별 사용 가능 항목은 시간이 지나면서 바뀔 수 있습니다. 또한 계정 권한에 따라 같은 팀 안에서도 보이는 메뉴가 다를 수 있습니다. 따라서 이 글의 순서는 “운영 설계 체크리스트”로 보고, 실제 클릭 경로와 요금·보관 정책은 적용 당일 Cloudflare 공식 문서와 계정 화면에서 다시 확인하는 것이 좋습니다.
요금이나 기능 제한을 확인할 때는 로그를 많이 남기는 Worker부터 따로 봐야 합니다. 요청량이 큰 Worker는 저장 로그량도 빠르게 늘 수 있습니다. 처음에는 핵심 서비스 하나만 기준으로 삼아 필터 조건과 로그 문장을 검증하고, 이후 다른 Worker로 확장하면 시행착오를 줄일 수 있습니다.
8. 팀 공유용 운영 체크리스트
- 배포 전: 이번 배포에서 확인할 Worker 이름과 테스트 경로를 정합니다.
- 배포 직후: Real-time logs에서 테스트 요청이 보이는지 확인합니다.
- 저장 확인: Workers Logs에서 같은 시간대, 같은 Worker 이름으로 검색합니다.
- 필터 축소: 오류 문자열, route, status, requestId 순서로 좁힙니다.
- 기록 보관: 사용한 쿼리 조건, 확인 시간, 배포 버전을 릴리스 노트에 남깁니다.
- 후속 개선: 검색이 어려웠던 로그 문장은 다음 배포에서 키 이름을 정리합니다.
9. 자주 막히는 지점과 해결 방향
첫 번째로 많은 문제는 로그가 너무 적거나 너무 많다는 점입니다. 너무 적으면 원인을 좁힐 수 없고, 너무 많으면 중요한 메시지가 묻힙니다. 핵심 처리 단계마다 한 줄씩 남기되, 반복 루프 안에서 같은 메시지가 과도하게 찍히지 않도록 조절해야 합니다. 두 번째는 실시간 로그만 보고 끝내는 문제입니다. 배포 직후 확인과 운영 기록 확인은 다른 작업이므로 두 화면을 나눠 봐야 합니다.
세 번째는 필터 기준이 코드마다 다른 문제입니다. 어떤 Worker는 path라고 쓰고, 다른 Worker는 route라고 쓰면 팀 전체 검색이 어려워집니다. 처음에는 완벽한 관측 체계를 만들기보다 공통 키 이름부터 맞추는 것이 효율적입니다. 네 번째는 권한 문제입니다. 대시보드를 확인할 담당자가 계정에 접근할 수 없다면 배포 당일에 확인이 지연됩니다. 배포 체크리스트에는 접근 권한 확인도 함께 넣어야 합니다.
10. 마무리: 작은 쿼리 규칙부터 시작하기
Cloudflare Workers Logs 쿼리 필터 대시보드 설정은 거창한 운영 체계를 한 번에 만드는 일이 아닙니다. 지금 운영 중인 Worker 하나를 골라 “배포 확인용 실시간 화면”과 “저장 후 검색용 로그 화면”을 나누는 것부터 시작하면 됩니다. 그리고 로그 문장을 검색 가능한 패턴으로 바꾸고, 팀이 반복해서 쓰는 필터 조건을 문서화하면 다음 배포부터 확인 시간이 줄어듭니다.
핵심은 도구의 이름보다 운영 질문입니다. “어느 Worker에서, 어느 시간대에, 어떤 경로가, 어떤 단계에서, 어떤 결과를 냈는가”를 빠르게 답할 수 있으면 대시보드 설정은 충분히 제 역할을 합니다. 이후 요청량이 늘거나 여러 팀이 함께 운영하게 되면 더 전문적인 관측 도구와 알림 체계를 붙이면 됩니다.
FAQ
Q1. Real-time logs만 켜면 Workers Logs는 필요 없나요?
아닙니다. Real-time logs는 새 배포 직후의 즉시 확인에 유용하고, Workers Logs는 저장된 로그를 나중에 검색·필터링하는 데 적합합니다. 운영 기록을 다시 확인해야 한다면 Workers Logs 중심으로 설계하는 편이 좋습니다.
Q2. 어떤 로그 문장을 남겨야 검색이 쉬운가요?
기능명과 처리 단계를 함께 넣은 짧은 문장이 좋습니다. 예를 들어 webhook_signature_mismatch처럼 경로와 상황이 드러나는 문구가 error 같은 넓은 단어보다 찾기 쉽습니다.
Q3. Cloudflare 플랜에 따라 화면이나 기능이 다를 수 있나요?
그럴 수 있습니다. 대시보드 메뉴, 보관 범위, 쿼리 기능, 요금 관련 조건은 계정 상태와 Cloudflare 업데이트에 따라 달라질 수 있으므로 실제 적용 전 공식 문서와 계정 화면을 다시 확인해야 합니다.
Q4. 로그에 요청 본문을 그대로 남겨도 되나요?
권장하지 않습니다. 업무 운영에 필요한 최소 정보만 남기고, 비밀 값이나 개인 식별 가능성이 있는 데이터는 제외하는 것이 안전합니다. 검색에 필요한 키와 상태 중심으로 설계하세요.
Q5. 처음 설정할 때 가장 먼저 볼 쿼리 조건은 무엇인가요?
최근 시간대, Worker 이름, route, status, message 문자열 순서가 무난합니다. 처음에는 넓게 보고, 같은 문제가 반복되면 특정 경로나 메시지로 좁히면 됩니다.
