정답부터 말하면, Cloudflare Workers automatic tracing은 먼저 Workers Observability에서 요청 흐름을 확인할 수 있는 상태를 만들고, 그다음 OpenTelemetry export 대상을 정해 외부 관찰 도구로 보내는 순서가 안전합니다. 처음부터 모든 로그를 외부로 보내기보다 개발·스테이징 Worker에서 trace가 제대로 찍히는지 확인하고, 샘플링·보존 기간·권한을 정한 뒤 운영 Worker에 넓히는 방식이 좋습니다.
요약: ① Workers Observability에서 trace 확인 ② 서비스·환경 이름 정리 ③ OpenTelemetry 수신 도구 선택 ④ 샘플링과 민감 정보 마스킹 점검 ⑤ 운영 반영 전 테스트 요청으로 trace id를 대조합니다. Cloudflare 화면, 플랜, 메뉴 이름, export 기능은 업데이트에 따라 달라질 수 있으니 실제 콘솔과 공식 문서를 함께 확인하세요.
1. 이 설정이 필요한 상황
Cloudflare Workers는 짧은 함수처럼 보이지만 실제 서비스에서는 라우팅, KV, R2, D1, Durable Objects, 외부 API 호출이 이어지는 작은 백엔드가 됩니다. 오류가 났을 때 단순 콘솔 로그만 보면 어느 구간에서 시간이 늘었는지, 어떤 요청이 재시도됐는지, 특정 배포 이후만 느려졌는지 파악하기 어렵습니다. automatic tracing은 이런 요청 흐름을 trace 단위로 묶어 보여주는 기능입니다.
특히 팀에서 이미 Grafana, Datadog, New Relic, Honeycomb 같은 관찰 도구를 쓰고 있다면 Cloudflare 대시보드만 따로 보는 것보다 OpenTelemetry 형식으로 흐름을 모으는 편이 운영에 편합니다. 이 글은 개발자가 바로 따라 할 수 있도록 준비 항목, 콘솔 확인 순서, export 전 체크할 내용을 한 번에 정리합니다.
2. 시작 전 준비물
- Cloudflare 계정과 대상 Workers 프로젝트 접근 권한
- 테스트 요청을 보낼 수 있는 개발 또는 스테이징 Worker
- trace를 받을 OpenTelemetry 호환 수신 도구 또는 기존 observability SaaS
- 서비스 이름, 환경 이름, 배포 버전을 구분하는 내부 규칙
- 로그와 trace에 남기면 안 되는 값에 대한 마스킹 기준
가장 먼저 해야 할 일은 “어디까지 볼 것인가”를 정하는 것입니다. 요청 URL, 응답 코드, 실행 시간, 외부 API 호출 시간은 운영에 유용하지만, 입력값 전체나 사용자 식별 정보가 그대로 남으면 관리 부담이 커집니다. 따라서 export보다 먼저 팀의 로그 작성 습관을 점검해야 합니다.
3. Cloudflare 콘솔에서 automatic tracing 확인하기
Cloudflare가 제공하는 Workers Observability 영역은 로그, 메트릭, 쿼리, trace 확인 흐름을 한곳에서 다루는 방향으로 발전하고 있습니다. 실제 메뉴 이름은 계정, 플랜, 베타 참여 상태에 따라 조금 다를 수 있으므로 “Workers”, “Observability”, “Logs”, “Traces”와 비슷한 항목을 기준으로 찾는 것이 좋습니다.
- Cloudflare dashboard에 로그인합니다.
- Workers & Pages 또는 Workers 메뉴에서 대상 Worker를 선택합니다.
- Observability, Logs, Metrics, Traces 관련 탭을 확인합니다.
- 테스트 URL을 호출한 뒤 최근 요청이 표시되는지 봅니다.
- trace id, 실행 시간, 오류 상태, 호출 경로가 보이는지 확인합니다.
이 단계에서 trace가 보이지 않는다면 export 설정으로 넘어가지 않는 편이 좋습니다. 기본 관찰 화면에서 요청이 보이지 않는 상태로 외부 도구를 붙이면 원인이 Cloudflare 설정인지, 수신 도구 설정인지, 네트워크 문제인지 분리하기 어려워집니다.
4. OpenTelemetry export 설계 순서
OpenTelemetry export는 “Cloudflare에서 나온 trace를 어디로, 어떤 이름으로, 어느 정도 양으로 보낼 것인가”를 정하는 작업입니다. 실제 연결 방식은 공식 기능 상태와 대상 도구가 받는 endpoint 형식에 따라 달라질 수 있습니다. 따라서 아래 순서를 문서화하고 팀 안에서 같은 이름을 쓰는 것이 중요합니다.
| 항목 | 권장 결정 | 이유 |
|---|---|---|
| service.name | worker-api, image-proxy처럼 역할 중심 | 여러 Worker를 한 화면에서 구분하기 쉽습니다. |
| deployment.environment | dev, staging, prod | 테스트 trace와 운영 trace를 분리합니다. |
| version | 배포 해시 또는 릴리스 이름 | 배포 이후 지연 증가를 찾기 쉽습니다. |
| sampling | 초기에는 낮게 시작 후 조정 | 비용과 저장량을 예측하기 쉽습니다. |
| retention | 장애 분석 기간 기준 | 오래 보관할수록 비용과 관리 부담이 늘어납니다. |
수신 도구가 여러 개라면 처음부터 전부 연결하지 말고 한 도구에 먼저 보내는 방식이 안전합니다. trace가 정상 수신되고 필드 이름이 원하는 형태로 들어오는지 확인한 뒤 알림, 대시보드, 장기 보관 구성을 추가하면 됩니다.
5. 실무 체크리스트
아래 체크리스트를 모두 통과하면 운영 Worker에 적용할 준비가 된 상태로 볼 수 있습니다.
- 개발 Worker에서 테스트 요청 trace가 Cloudflare 화면에 표시된다.
- trace id를 기준으로 동일 요청을 외부 도구에서도 찾을 수 있다.
- service.name, environment, version 값이 팀 규칙과 맞다.
- 요청 본문, 쿠키, 토큰, 개인 식별 값이 trace에 그대로 남지 않는다.
- 샘플링 비율과 보존 기간이 예상 트래픽 기준으로 감당 가능하다.
- 장애 시 확인할 대시보드 링크와 담당자가 문서화되어 있다.
체크리스트에서 하나라도 애매하면 운영 반영을 늦추는 것이 좋습니다. 관찰 도구는 문제가 생긴 뒤 켜는 것보다 평소에 조용히 쌓이도록 만드는 것이 핵심이지만, 너무 많은 데이터를 무작정 남기면 오히려 중요한 신호를 찾기 어려워집니다.
6. 오류가 보이지 않을 때 점검 순서
trace 설정에서 자주 막히는 지점은 요청이 실제로 Worker에 도달하지 않았거나, 필터가 너무 좁거나, export 대상 endpoint가 다른 형식을 요구하는 경우입니다. 먼저 Cloudflare 화면에서 최근 요청이 보이는지 확인하고, 그다음 외부 도구 수신 상태를 봅니다.
- 테스트 URL이 올바른 Worker route를 타는지 확인합니다.
- 최근 시간 범위와 환경 필터가 맞는지 확인합니다.
- 성공 요청과 오류 요청을 각각 보내 표시 차이를 봅니다.
- OpenTelemetry endpoint 주소, 인증 헤더, 프로토콜 형식을 다시 확인합니다.
- 수신 도구에서 service.name 필터를 너무 좁게 걸지 않았는지 봅니다.
여기서 중요한 것은 “Cloudflare 내부 화면에는 보이는데 외부 도구에는 안 보이는지”, “둘 다 안 보이는지”를 나누는 것입니다. 전자는 export 또는 수신 설정 문제에 가깝고, 후자는 Worker route, 관찰 기능 활성화, 시간 필터 문제일 가능성이 큽니다.
7. 비용과 데이터량을 줄이는 운영 팁
관찰 데이터는 편리하지만 무한히 저장할 수 있는 자원이 아닙니다. 요청이 많은 Worker라면 모든 요청을 항상 자세히 남기는 방식보다 샘플링, 오류 중심 필터, 특정 경로 집중 관찰을 섞는 방식이 현실적입니다. 예를 들어 결제나 회원 처리 같은 민감 업무 대신, 이 글의 범위에서는 이미지 프록시, API 게이트웨이, 정적 데이터 변환처럼 IT 운영 관찰 목적에 맞는 Worker부터 시작하는 것이 좋습니다.
또한 팀이 보는 핵심 지표를 미리 정하세요. 평균 실행 시간, p95 지연, 오류 비율, 외부 API 호출 시간, 특정 배포 이후 변화 정도만 잘 잡아도 대부분의 초기 장애 대응에는 충분합니다. 모든 필드를 대시보드에 올리면 보기에는 화려하지만 실제 의사결정 속도는 느려질 수 있습니다.
8. 팀 문서에 남길 항목
한 번 설정한 trace는 다음 담당자가 이해할 수 있어야 합니다. 운영 문서에는 기능을 켠 날짜, 대상 Worker, service.name 규칙, export 대상, 샘플링 기준, 보존 기간, 장애 시 확인할 대시보드 링크를 남깁니다. 또한 Cloudflare의 베타 기능이나 콘솔 메뉴는 바뀔 수 있으므로 “최종 확인일”을 함께 적어두면 다음 업데이트 때 혼동이 줄어듭니다.
문서에는 설정 화면 캡처를 붙일 수 있지만, 토큰이나 endpoint의 비밀 값은 가려야 합니다. 팀용 문서에는 비밀 값 자체보다 “어디의 어떤 secret을 참조한다” 정도로 적는 편이 안전합니다.
9. 운영 반영 전 마지막 확인
운영 Worker에 반영하기 전에는 짧은 테스트 창을 정하고, 반영 직후 정상 요청과 오류 요청을 각각 만들어 trace가 남는지 확인합니다. 배포 후 몇 분 동안 대시보드를 보며 오류 비율이 갑자기 늘지 않는지, 외부 도구 수신량이 예상보다 과하게 증가하지 않는지 확인하세요. 문제가 있으면 export를 잠시 끄거나 샘플링을 낮춘 뒤 원인을 분리합니다.
자동 tracing은 장애를 자동으로 없애는 기능이 아니라, 문제를 더 빨리 찾기 위한 관찰 기반입니다. 따라서 알림 기준과 담당자 흐름까지 같이 정해야 실제 운영 효과가 납니다.
10. FAQ
Q1. automatic tracing을 켜면 기존 console.log가 필요 없나요?
아닙니다. trace는 요청 흐름과 지연 구간을 보기 좋게 묶어주고, 로그는 특정 분기에서 남긴 설명을 보여줍니다. 둘을 함께 쓰되 로그에는 민감한 값을 남기지 않는 것이 좋습니다.
Q2. OpenTelemetry export는 꼭 처음부터 연결해야 하나요?
처음에는 Cloudflare 화면에서 trace가 정상 표시되는지 확인하는 것이 우선입니다. 외부 도구는 팀이 이미 쓰는 관찰 체계가 있거나 여러 서비스의 흐름을 한곳에 모아야 할 때 연결하면 됩니다.
Q3. 운영 요청을 모두 trace로 남겨도 되나요?
트래픽, 비용, 보존 기간, 내부 기준에 따라 다릅니다. 처음에는 낮은 샘플링으로 시작하고, 오류나 특정 경로 중심으로 조정하는 편이 안전합니다.
Q4. Cloudflare 콘솔 메뉴가 글과 다르면 어떻게 하나요?
Cloudflare의 화면, 기능 이름, 플랜 제공 범위는 업데이트될 수 있습니다. 실제 dashboard와 공식 Cloudflare 블로그·문서를 우선 확인하고, 글의 순서는 점검 프레임으로 활용하세요.
Q5. 어떤 Worker부터 적용하는 것이 좋나요?
외부 API를 호출하거나, 지연 문제가 사용자 경험에 바로 영향을 주거나, 배포가 잦은 Worker부터 적용하는 것이 좋습니다. 단순 정적 응답 Worker보다 병목을 찾을 여지가 큰 서비스가 우선입니다.
마무리
Cloudflare Workers automatic tracing과 OpenTelemetry export는 서버리스 운영을 감으로 처리하지 않게 해주는 기본 장치입니다. 핵심은 기능을 켜는 것보다 이름 규칙, 샘플링, 보존 기간, 민감 정보 제외, 팀 문서화를 함께 정하는 데 있습니다. 먼저 개발 Worker에서 trace를 확인하고, 외부 도구 수신을 검증한 뒤 운영 Worker로 넓히면 불필요한 시행착오를 줄일 수 있습니다.
