Claude Code 세션 복구와 OTel 관측성 운영 설계

세션이 끊겨도 작업 맥락과 실행 이력을 이어가는 방식

Claude Code의 /resume 관련 안정화는 컨테이너가 턴 처리 중 재시작됐을 때 진행 중인 메시지가 사라지던 문제를 다룬다. 중단된 턴은 세션을 다시 열었을 때 재실행된다. 히스토리에 형식이 손상된 델타 첨부가 들어 있어 재개 세션이 매 턴 실패하거나 크래시하던 경우도 수정 대상이다.

여기에 메시지 단위 OpenTelemetry(OTel) 상관관계 속성이 더해졌다. 에이전트가 어떤 요청에서 도구를 호출했고, 그 도구가 어떤 하위 프로세스와 훅 실행으로 이어졌는지를 하나의 실행 흐름으로 연결할 수 있다. 이제 코딩 에이전트는 개인 작업 도구에만 머물지 않고 조직의 관측·감사 체계 안에서 관리할 수 있는 대상이 된다.

Windows와 Linux 셸 실행의 보안 동작도 이 변화와 맞물린다. Windows PowerShell 5.1의 권한 검사 우회는 차단됐고, 까다로운 리다이렉트나 10,000자 초과 명령에서 Bash 검사가 실패하면 실행을 허용하지 않는 fail-closed 방식이 적용된다. Windows에서는 CLAUDE_ENV_FILE과 SessionStart 훅 환경 파일을 적용하고, 권한 규칙은 드라이브 문자 경로의 루트를 고정하며 대소문자를 무시한다. Git for Windows가 없으면 PowerShell을 셸 도구로 사용한다.

트랜스크립트는 복구 데이터이자 민감 데이터다

세션 복구는 대화, 도구 호출, 실행 결과를 세션 단위 트랜스크립트로 영속화하는 데서 출발한다. 재개 시점에는 이 기록을 읽어 컨텍스트를 다시 구성한다. 진행 중인 턴이 중단되면 부분 상태를 남기지 않고 해당 턴을 재실행해 일관성을 지키는 구조다. 일부 히스토리 항목이 손상돼도 세션 전체가 실패하지 않도록 방어적으로 파싱해야 한다.

이 기록은 두 가지 성격을 동시에 가진다. 복구 관점에서는 작업 맥락을 되살리는 원본이지만, 소스코드·환경변수·자격증명 흔적이 섞일 수 있다는 점에서는 민감 데이터다. 따라서 트랜스크립트는 소스코드와 같은 기밀 등급으로 취급하고, 접근 권한을 최소권한으로 제한할 필요가 있다.

보존 기간도 목적에 따라 나누는 편이 낫다. 복구에 의미 있는 기간인 수일~수주는 원문 트랜스크립트를 보관하고, 감사 목적의 장기 보관은 마스킹된 요약본으로 분리할 수 있다. 만료 시 자동 삭제 정책을 적용해 무기한 축적을 막아야 한다.

세션 ID로 셸 로그와 텔레메트리를 연결한다

Bash 도구가 실행하는 모든 하위 프로세스에는 CLAUDE_CODE_SESSION_ID 환경변수가 주입된다. 이 값은 훅 입력 JSON의 session_id와 동일하며, 셸 로그와 훅 텔레메트리를 같은 세션 기준으로 상관 분석하는 데 쓰인다.

CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH는 텔레메트리에 포함되는 콘텐츠 길이의 상한을 제어한다. 저장 비용과 정보 노출 범위를 함께 조절하는 설정이다. 수집 대상에는 세션 수, 턴 수, 토큰 소비, 도구 호출 성공률, 권한 차단 건수, 재개 발생 빈도가 포함된다.

⤢✕

수집 경로는 에이전트에서 OTel Collector를 거쳐 메트릭과 로그 저장소로 이어지고, 대시보드와 SIEM이 이를 소비하는 형태다. 상관 키가 실제로 작동하려면 셸 로그, 훅 로그, 트레이스 전반에서 세션 ID의 필드명을 동일하게 유지해야 한다. 메트릭은 전수 수집하고 상세 트레이스 콘텐츠는 표본화하면 비용을 통제할 수 있다.

비용은 세션 수 × 평균 턴 수 × 이벤트당 페이로드 크기의 영향을 받는다. 콘텐츠 길이 상한은 이 저장 비용을 직접 좌우한다. 장기 보관 데이터는 저비용 객체 스토리지로 계층 이관하고, 조회 빈도가 낮은 구간은 압축 저장 대상으로 둘 수 있다. 수집 경로에는 비밀값 탐지 규칙을 배치해 자격증명 패턴을 마스킹한다.

복구 세션과 신규 세션의 운영상 차이

구분	세션 복구 활용	매번 신규 세션 시작
컨텍스트 재구축 비용	저장된 트랜스크립트 로드	파일 재탐색·재설명 반복
토큰 소비	히스토리 로드분 발생	재탐색 토큰이 누적 발생
작업 연속성	중단 지점에서 재개	진행 상태 유실
데이터 잔존	트랜스크립트 보관 필요	잔존 최소
보안 노출	저장 데이터 관리 부담	낮음

세션 복구는 히스토리를 불러오는 토큰 비용을 지불한다. 반대로 매번 신규 세션을 시작하면 파일을 다시 탐색하고 작업 상황을 설명하는 과정이 반복되므로, 장기 작업에서는 총 토큰이 더 커질 수 있다. 복구 방식을 선택하면 트랜스크립트 보관에 따른 데이터 관리 부담도 함께 받아들여야 한다.

OTel 기반 관측은 Collector, 시계열 DB, SIEM 같은 기존 관측 스택에 편입할 수 있어 이식성과 상관 분석에 유리하다. 벤더 전용 로깅은 초기 설정이 단순할 수 있지만, 도구를 바꿀 때 대시보드와 경보 자산도 함께 폐기된다.

상세 텔레메트리는 사고 조사 능력을 높이는 대신 소스코드와 자격증명 노출 위험을 키운다. 콘텐츠 길이 상한, 비밀값 마스킹, 보존 기간 제한을 함께 적용해 균형점을 정해야 한다.

재실행 안전성과 감사 추적을 운영 통제로 묶기

세션 복구는 에이전트 세션을 운영 대상 워크로드로 본다는 뜻이기도 하다. 가용성과 복구 목표를 정의할 근거가 생기지만, 컨테이너 재시작 뒤 턴을 재실행하는 방식은 멱등성(idempotency) 설계와 직결된다. 부작용이 있는 도구 호출은 재실행해도 안전한지 별도로 검증해야 한다.

감사 관점에서는 누가 어떤 세션에서 어떤 명령을 실행했고, 무엇이 차단됐는지 재구성할 수 있어야 한다. 세션 ID를 셸 로그·훅 텔레메트리·트레이스에 공통으로 넣는 구조는 이 감사 추적의 상관 키를 표준화한다. 권한 규칙 변경 이력과 차단 이벤트도 보안 감사 범위에 포함해야 한다.

플랫폼별 셸 처리 차이는 단순한 호환성 문제가 아니다. 권한 검사 우회가 보안 결함으로 이어질 수 있으므로, Windows와 Linux 환경에서 권한 검사 동작과 우회 가능성을 각각 검증하는 절차가 필요하다. 트랜스크립트에 개인정보나 기밀정보가 혼입될 수 있다는 점도 로그 보존, 접근통제, 파기 기준에 명시해야 한다.

운영 환경에서 예상되는 변화

에이전트 텔레메트리는 기존 APM·SIEM 파이프라인에 표준적으로 편입되고, 개발 도구 사용 자체가 보안 모니터링 대상으로 자리 잡을 전망이다. 세션 트랜스크립트에는 보존·마스킹 정책이 조직 표준으로 요구되며, 관련 설정을 강제하는 정책 관리 기능도 확산될 수 있다.

크로스플랫폼 권한 검사의 일관성은 도구 선정 과정의 보안 평가 항목으로 부상한다. 세션 복구가 수 시간 이상 실행되는 에이전트의 기본 전제가 되면, 재실행 멱등성은 도구와 플러그인 개발 관행에 포함된다.

/resume 안정화와 메시지 단위 OTel 상관관계 속성은 코딩 에이전트를 관측하고 감사할 수 있는 운영 대상으로 만든다. 세션 ID 기반 상관 분석, 콘텐츠 길이 상한, 트랜스크립트 보관 정책, 턴 재실행의 멱등성 검증을 함께 갖춰야 에이전트 활용 범위를 안전하게 넓힐 수 있다.