Heroku 로깅 실무: Logplex, heroku logs, 외부 전송
Heroku 로그 tail과 필터링, Cedar Logplex 보존 제한 및 Fir OTLP의 차이를 설명합니다. 전송 프레이밍, 재시도, 앱 식별과 DataKit 변환 조건도 살펴봅니다.
라우터 로그 필터가 비어 있다고 라우터가 로그를 만들지 않은 것은 아닙니다. Heroku Cedar의 heroku[router]에서 source는 heroku이고 router는 구성 요소 필드입니다. 이 구분은 장애 중 tail을 볼 때도, 외부 로그 플랫폼으로 필드를 옮길 때도 중요합니다.
Cedar는 일반적으로 Logplex로 애플리케이션, 라우터, 플랫폼 로그 스트림을 모읍니다. 전송과 짧은 이력 버퍼를 위한 것이지 장기 저장소는 아닙니다. Fir는 OpenTelemetry/OTLP를 사용하며 Logplex나 같은 로그 이력을 제공하지 않습니다. Private Space Logging을 켠 Shield Space도 예외입니다. 이 글은 Cedar의 Logplex와 Log Drain을 중심으로 세대 차이 때문에 달라지는 절차를 구분합니다.
로그와 명령은 공식 문서를 바탕으로 만든 예시입니다. 실제 Heroku 앱을 조회하거나 drain을 설정하지 않았습니다. Heroku Logging(영어) · Heroku Telemetry(영어)
먼저 알아둘 내용
- Logplex는 전송 계층이며 장기 저장소가 아닙니다. 해당 Cedar 앱은 최근 1,500줄까지만 보관하고, 로그는 1주가 지나면 만료됩니다. 먼저 도달한 제한이 적용되며 1,500줄이 대략 일주일 분량이라는 뜻은 아닙니다.
- source와 dyno를 구분합니다. 앱 출력은 보통
app, Cedar 플랫폼 구성 요소는herokusource입니다.router는 dyno/구성 요소 필드입니다. 빌드 로그는 해당 빌드 기록에서 보므로 런타임 스트림이 모든 로그를 담지는 않습니다. - 조사는
heroku logs --tail에서 시작합니다. Cedar는 source/dyno 필터와--num이력을 지원합니다. Fir에는 이력이 없으며heroku logs가 기본적으로 실시간 tail을 엽니다. - 수신 형식을 맞춥니다. Cedar HTTPS/syslog drain과 Fir OTLP telemetry drain은 프로토콜이 다릅니다. 프레이밍, 필드, 실패 처리와 누락을 확인해야 합니다.
1. Logplex의 바깥 형식 읽기
Cedar에서는 수집 대상 stdout/stderr, 라우터 요청, 플랫폼 이벤트를 Logplex에 모읍니다. 다음 합성 예시는 CLI 표시 형식이며 HTTPS drain의 원본 요청 본문은 아닙니다.
2026-08-25T14:55:22.123+00:00 heroku[router]: at=info method=GET path="/api/orders" host=example.com request_id=7f3a status=200 ...
2026-08-25T14:55:22.456+00:00 app[web.1]: INFO 주문 생성 완료 {"order_id":1024}
2026-08-25T14:55:30.000+00:00 heroku[web.1]: Restarting
타임스탬프 뒤가 source[dyno]이고 그 다음이 메시지입니다. 두 번째 줄은 일반 문자열 뒤에 JSON을 덧붙였으므로 전체 줄이 JSON 객체인 것은 아닙니다. 여러 노드에서 들어오기 때문에 수신 순서가 이벤트 시간순이라는 보장도 없습니다.
Logplex 이력에는 1,500줄과 1주라는 두 제한이 있습니다. 로그가 많으면 오래된 줄은 빠르게 밀려납니다. 장기 검색에 의존하려면 logging add-on이나 Log Drain의 저장 대상을 미리 구성해야 합니다. Fir의 OTLP 경로에 같은 이력 버퍼가 있다고 가정하면 안 됩니다.
2. heroku logs로 tail과 필터 사용하기
아래는 읽기 권한이 있는 Cedar 앱 my-app의 예시입니다. 실제 앱 이름으로 바꿉니다.
heroku logs --app my-app --tail # 새 로그 추적
heroku logs --app my-app --num 500 # 버퍼에 남은 최근 500줄까지 조회
heroku logs --app my-app --source heroku --dyno router # 라우터 구성 요소 선택
heroku logs --app my-app --source app # app source 선택
heroku logs --app my-app --dyno web.1 # 특정 dyno 선택
heroku logs --app my-app --source app --dyno worker.1 --tail
요청 상태와 라우팅 시간은 --source heroku --dyno router, 앱 기록은 --source app으로 확인합니다. 플랫폼의 비정상 종료 정보와 해당 환경의 R14 같은 런타임 이벤트는 heroku source를 봅니다. Cedar 기본 조회량은 100줄이고 --num은 최대 1,500줄이며, 이미 제거된 기록을 되살릴 수는 없습니다. tail도 아카이브가 아니고 1시간 동안 유휴 상태면 종료됩니다.
Fir는 기본 tail이며 heroku logs --app my-fir-app --process-type web으로 프로세스 유형을 고를 수 있습니다. 내부 source에는 heroku-router 같은 heroku- 접두사가 붙습니다. Cedar의 web.1 이름, source 값, 이력 조회 동작을 그대로 적용해서는 안 됩니다. CLI 필터링(영어)
3. 로그를 활용하기 위한 다섯 가지 습관
- stdout/stderr에 기록합니다. 파일 로그는 플랫폼 스트림에 자동으로 포함되지 않으므로 프레임워크 설정이나 명시적인 전달이 필요합니다. 파일에 쓰는 즉시 사라지는 것은 아니지만 dyno의 임시 파일 시스템을 장기 저장소로 삼을 수는 없습니다.
- 구조화와 파싱을 함께 설정합니다. JSON이나 logfmt는 수신기가 해석할 때 유용합니다. Heroku 바깥 형식과 앱 메시지를 따로 처리하며 모든 필드가 자동 추출된다고 가정하지 않습니다.
- 문맥을 남깁니다. 적절한 사용자 식별자,
request_id, 업무 이벤트를 기록하고 최소 수집과 마스킹을 적용합니다. HTTP 요청 ID가 곧 APM의trace_id는 아닙니다. - 수준과 구성 요소 오류를 구분합니다. INFO는 알맞은 업무 이벤트에, ERROR는 실패에 사용합니다. 라우터 H12와 런타임 R14는 서로 다른 조건이며 한 건만으로 근본 원인을 확정할 수 없습니다.
- 인증 정보를 남기지 않습니다. 암호, 바로 사용할 수 있는 인증 정보, 전체 카드 번호를 피하고 사용자 데이터는 적용 정책에 따라 처리합니다. 수신기 설정에서 drain 식별 값과 앱 인증 정보를 구분하고, 사용할 수 있는 인증 정보를 로그 본문에 섞지 않습니다.
4. Log Drain으로 외부 전송하기
drain을 추가하면 Cedar 앱 설정이 바뀝니다. 호환 수신기를 준비하고 예시 URL과 앱 이름을 바꿉니다. 이 글을 위해 아래 명령을 실행하지는 않았습니다.
# Cedar HTTPS drain 설정 예시
heroku drains:add https://logs.example.com/heroku --app my-app
heroku drains --app my-app # 설정된 drain 조회
Cedar는 HTTPS와 TCP syslog drain을 지원하며 syslog에는 TLS를 사용할 수 있습니다. syslog는 octet counting으로 프레임을 나눕니다. HTTPS는 application/logplex-1 POST 본문으로 배치를 보내고 내부 메시지도 바이트 길이로 구분합니다. JSON 배열이 아니고 줄바꿈만으로 나누는 방식도 안전하지 않습니다. Heroku HTTPS 형식은 표준 syslog 구조 일부도 생략하므로 임의의 RFC 5424 파서가 곧바로 호환된다고 볼 수 없습니다.
Logplex-Msg-Count를 확인하고 재시도 배치를 식별할 Logplex-Frame-Id를 보존합니다. Logplex-Drain-Token은 설정된 앱 식별 정보에 매핑합니다. 비2xx 응답이나 네트워크 실패는 재시도와 중복을 만들 수 있습니다. 공식 응답 규칙에 따라 본문 없이 Content-Length: 0으로 응답하고, 수신·영속 저장·인덱싱 중 어느 시점에 수신 확인을 할지 정해야 합니다. Logplex는 최선형 전달이며 유한한 버퍼가 넘치면 기록을 버릴 수 있습니다.
Fir는 heroku telemetry로 관리하는 telemetry drain을 통해 OTLP를 내보냅니다. 같은 Logplex HTTPS 설정에서 URL만 바꾼 경로가 아닙니다. Heroku Log Drains(영어)
수신 형식을 실제로 확인하기
허가된 테스트 앱으로 배치 수, 파싱한 프레임 수, 실제 저장한 이벤트 수를 비교합니다. 앱 식별, dyno, Heroku source, 이벤트 시간을 보존합니다. 공유 수신기에서는 drain token과 앱의 설정상 매핑을 관리할 수 있지만 drain을 삭제하고 다시 만들면 token이 바뀝니다. source가 app이라는 사실만으로 앱을 구분할 수는 없습니다. 이벤트 시간과 수신 시간도 나누어 순서와 지연을 조사합니다.
Guance의 DataKit Log Streaming(영어)은 HTTP 로그 수신 엔드포인트를 제공하지만 Heroku Logplex drain을 기본 지원하는 수신기로 문서화되어 있지는 않습니다. 호환 프로그램에서 배치를 풀고 문서가 지원하는 입력 형식과 필드로 변환해야 합니다. 예를 들어 heroku_app, heroku_source, dyno로 문맥을 유지할 수 있지만 자동 생성되는 내장 필드는 아닙니다. DataKit의 source는 로그 수집 원본/measurement이므로 Heroku source와 구분합니다.
그 다음 이벤트 시간 파싱, 영속화와 재시도 경계, 중복 제거, 버퍼 초과 알림을 검증합니다. HTTP 엔드포인트의 존재가 안정적인 종단 간 인덱싱을 입증하지는 않습니다. Fir OTLP도 양쪽의 신호, 전송 방식, 엔드포인트 지원을 따로 확인해야 하며 Logplex 어댑터만으로 검증할 수 없습니다.
자주 묻는 질문
Heroku 로그는 얼마나 보관되나요?
Logplex를 사용하는 Cedar는 최근 1,500줄까지만 보관하고 1주 뒤에 만료되며 먼저 도달한 제한이 적용됩니다. 어제 기록이 남아 있을 수도, 이미 밀려났을 수도 있습니다. Fir에는 이력이 없고 Private Space Logging을 켠 Shield Space도 같은 CLI 이력을 제공하지 않습니다. 과거 조사에 쓰려면 미리 외부 수집과 저장을 설정해야 합니다. 다른 복사본 없이 제거된 로그를 나중에 다시 수집할 수는 없습니다.
H12와 R14는 무엇인가요?
Cedar 예시에서 H12는 라우터 요청 시간 초과이며, 보통 초기 30초 안에 응답 데이터가 없을 때 발생합니다. 모든 스트리밍 응답을 30초 안에 끝내야 한다는 뜻은 아닙니다. 첫 바이트 이후에는 연속 갱신되는 유휴 시간 제한이 적용됩니다. 라우터가 오류를 반환해도 앱은 계속 처리할 수 있습니다. Fir에서는 현재 세대에 해당하는 라우팅과 오류 코드 문서를 확인하고, Cedar 규칙 전체를 그대로 적용하지 않습니다.
R14는 메모리 할당량 초과이며 해당 Cedar Common Runtime에서 swap 사용과 관련됩니다. Private Spaces는 swap을 사용하지 않아 R14를 내보내지 않습니다. 현재 Fir도 R14를 내보내지 않으므로 기록이 없다고 메모리가 정상이라는 증거는 아닙니다. 오류 코드(영어) · 요청 시간 초과(영어)
여러 앱의 로그를 한곳에 모을 수 있나요?
호환 drain을 공유 수신기로 보내고 앱별 식별과 drain/리소스 ID를 유지한 뒤 앱 기준으로 조회 결과를 확인할 수 있습니다. Cedar와 Fir는 프로토콜이 다르므로 알맞은 수신·변환 경로가 필요합니다. 같은 URL로 보낸다는 이유만으로 통합된 것은 아닙니다.
drain이 전달하지 못하면 어떻게 되나요?
Logplex에는 제한된 버퍼와 재시도 동작이 있지만 전달을 보장하는 영속 큐는 아닙니다. 수신기가 계속 뒤처지면 버퍼가 넘쳐 기록을 버릴 수 있고 L10 같은 경고가 나타날 수 있습니다. 수신기 영속화, 재시도, 중복 처리를 확인하며 무손실이나 정확히 한 번 전달을 약속하지 않습니다. Cedar L 계열 코드가 Fir에서도 나오는 것으로 가정하면 안 됩니다.
함께 읽기
문서 확인일: 2026년 11월 5일.
