Cloudflare Workers CPU 프로파일링: Flamegraph로 메모리 누수 추적하기

Workers 온디맨드 프로파일링으로 무엇을 볼 수 있나요?

Cloudflare는 2026년 10월 9일 Workers와 Durable Objects의 운영 중 CPU·메모리 프로파일링을 발표했습니다. 대시보드에서 캡처를 요청하고 인터랙티브 Flamegraph로 분석하거나 프로파일 파일을 내려받을 수 있습니다. 근거: Cloudflare 공식 발표

Cloudflare가 소개한 내부 사례에서는 비활성화했다고 여겼던 Prometheus 코드 경로가 여전히 메모리를 할당하고 있었습니다. 팀은 프로파일로 해당 경로를 찾아 제거했습니다. 이 사례는 관측·계측 코드도 조사 대상이라는 점을 보여주며, 모든 메모리 문제의 원인이 같은 코드라는 뜻은 아닙니다.

CPU 프로파일과 Heap 프로파일, 스냅샷의 차이

운영 Heap 프로파일은 유지된 메모리의 스냅샷이 아니라 할당 샘플입니다. 근거: 운영 프로파일링 문서 큰 응답을 한 번 처리하면서 생긴 일시적 할당과, 전역 컬렉션에 매번 데이터를 추가해 누적되는 문제를 같은 현상으로 판단하면 수정 방향을 잘못 잡을 수 있습니다.

CPU 프로파일에서 가비지 컬렉션 비용이 커 보이면 할당 패턴을 조사할 이유가 생깁니다. 그러나 GC 비용만으로 누수를 확정할 수는 없습니다. Cloudflare는 운영 환경의 요청 특성을 로컬에서 재현해 CPU를 조사하도록 안내합니다. 근거: CPU 분석 문서

대시보드에서 CPU·Heap Flamegraph 캡처하기

1. Workers & Pages에서 Worker를 선택합니다.
2. Observability의 보기에서 Flamegraph를 선택합니다.
3. Profile type을 CPU 또는 Heap으로 지정합니다.
4. 캡처 시간을 지정하고 실행 중인 배포 버전을 확인합니다.
5. 대상 버전에 요청이 들어오는 상태에서 Capture profile을 실행합니다.

공식 문서의 캡처 시간은 1~50초, 기본 10초입니다. Durable Object는 namespace와 대상 instance를 선택해 같은 방식으로 캡처합니다. source map을 사용하려면 Wrangler 설정의 upload_source_maps를 true로 지정하고 배포해야 합니다. 근거: 캡처 준비·대시보드 절차

캡처 전에 문제를 유발하는 요청 경로와 입력 크기를 기록하세요. 첫 시도에는 일반적인 요청만 들어왔고 두 번째에는 큰 데이터 처리 요청이 들어왔다면 그래프 차이를 코드 개선 효과로 해석할 수 없습니다. 운영 계정에 임의로 과도한 부하를 보내기보다 허용된 재현 범위에서 요청을 준비하는 편이 좋습니다.

Flamegraph 읽기: 넓은 프레임과 Self·Total

프레임 폭은 CPU 시간 또는 할당량에 비례하며, 가로 위치는 시간 순서를 뜻하지 않습니다. Table의 Self는 해당 함수 자체 비용, Total은 하위 호출을 포함한 비용입니다. 근거: 결과 해석 문서

넓은 프레임부터 수정하기보다 그 비용이 서비스 기능에 필요한지 확인하세요. 예를 들어 정상적으로 큰 응답을 만드는 함수와 요청마다 중복 데이터를 만드는 함수는 개선 여지가 다릅니다. 한 캡처의 비율이 작아졌다는 이유로 절대 자원 사용량도 줄었다고 판단하지 말고 관련 지표를 함께 비교해야 합니다.

메모리 누수 확인: 로컬 스냅샷 비교 순서

Cloudflare 메모리 문서는 wrangler dev 실행 후 터미널에서 D를 눌러 DevTools를 열고 Memory 탭에서 요청을 보낸 뒤 Take snapshot을 선택하도록 안내합니다. 운영과 비슷한 요청·경로·데이터가 있어야 재현 가능성이 높아집니다. 근거: 메모리 스냅샷 절차

npx wrangler dev
# 터미널에서 D를 눌러 DevTools를 열고 Memory 탭을 선택

1. 기준 상태: 초기화가 끝난 뒤 기준 스냅샷을 저장하고 입력 데이터와 요청 조건을 기록합니다.
2. 반복 재현: 의심 경로를 일정한 조건으로 실행합니다. 요청 종료와 정리 동작을 기다린 뒤 추가 스냅샷을 찍습니다.
3. 증가 객체 조사: 객체 수와 크기가 계속 증가하는 유형을 찾아 어떤 참조가 객체를 붙잡는지 확인합니다.
4. 원인 수정: 사용이 끝난 객체의 참조 제거, 캐시 한도, 이벤트 리스너 정리 등 실제 소유 관계에 맞춰 수정합니다.
5. 같은 조건으로 재검증: 누적 증가가 완화되는지와 기능이 정상인지 함께 확인합니다.

Cloudflare의 설명 예시는 전역 문자열에 요청 시각을 계속 붙여 크기가 증가하는 코드입니다. 이런 패턴은 응답에서 짧은 문자열만 반환하더라도 내부 전역 상태가 계속 커질 수 있음을 보여줍니다. 근거: 공식 문자열 누적 사례

원인을 확인할 때에는 한 번 커진 뒤 일정 크기에서 멈추는 정상 캐시와 제한 없이 증가하는 상태를 구분하세요. 종료되지 않은 작업이나 진행 중인 요청 때문에 객체가 살아 있을 수도 있습니다. 로컬에서 재현되지 않았다는 결과만으로 운영 문제가 사라졌다고 판단하지 않습니다.

캡처 실패와 OOM을 조사할 때의 점검표

진단 기록에는 버전, 캡처 시간, 요청 경로, 입력 크기, 호출량, 의심 함수, 수정 내용, 재검증 결과를 남기세요. 프로파일은 전체 계정 트래픽을 대표하는 통계로 가정하지 말고 캡처한 실행 환경의 증거로 해석하는 것이 좋습니다.

학습용 재현 예시: 요청마다 커지는 전역 배열

다음 코드는 진단 원리를 설명하는 의도적인 문제 예시입니다. 로컬 실험용으로만 사용하고 운영에 배포하지 마세요. 요청이 들어올 때마다 전역 배열이 새 객체를 보관하므로 동일 실행 환경에서 참조가 누적될 수 있습니다. 이 프로젝트에서 실행하거나 메모리 증가량을 측정한 코드는 아닙니다.

// 학습용 문제 예시: 정리하지 않는 전역 상태
const history = [];
export default {
  async fetch() {
    history.push({ at: Date.now(), payload: new Array(1000).fill("sample") });
    return new Response(String(history.length));
  },
};

같은 로컬 실행 환경에서 반복 요청 전후 스냅샷을 비교하고, 배열과 그 안의 객체가 history 참조로 유지되는지 확인합니다. 요청 간 격리 실행 환경이 달라지면 결과가 달라질 수 있으므로 반환 길이도 함께 기록하세요. 응답 숫자는 프로그램 상태를 확인하는 단서이며 메모리 사용량 측정값은 아닙니다.

업무상 이력을 보관할 필요가 없다면 전역 보관을 제거하는 것이 우선입니다. 최근 이력을 반드시 유지해야 하는 경우에는 최대 항목 수와 항목 크기를 정하고 저장 기간도 검토하세요. 항목 개수 제한만으로 큰 입력까지 안전하게 처리할 수 있는 것은 아닙니다.

캡처 버전 / 프로파일 종류 / 캡처 시간:
요청 경로 / 입력 크기 / 호출량 / 동시성:
할당이 많은 함수 / 유지된 객체 / 참조 주체:
수정 내용 / 동일 조건 재검증 결과:
CPU·메모리·오류·기능 확인 결과:

자주 묻는 질문

CPU Flamegraph만으로 메모리 누수를 찾을 수 있나요?

관련 실행 비용을 단서로 얻을 수 있지만 메모리가 계속 유지되는 원인을 확정하려면 Heap 분석과 스냅샷·참조 확인이 필요합니다.

Heap에서 가장 큰 함수가 누수 원인인가요?

할당을 많이 했다는 뜻으로 읽어야 합니다. 작업이 끝난 뒤 해제되는 객체인지, 계속 보관되는 객체인지 확인한 다음 판단하세요.

OOM은 모두 누수인가요?

아닙니다. 누수 외에도 큰 입력이나 한꺼번에 수행하는 작업이 메모리 사용을 높일 수 있습니다. 지속적인 증가와 일시적인 사용량 상승을 나눠 조사하세요.

관련 Cloudflare 운영 안내

• Cloudflare Radar로 인터넷 장애와 트래픽 확인하기
• Deno Cloudflare 합류와 Deploy 종료 일정