Claude 에이전트 관측성: 여러 세션의 상태 확인부터 안전한 재개까지

Claude 에이전트 관측성은 Agent View로 백그라운드 세션의 상태를 살피고, OpenTelemetry로 실행 경로와 사용량을 확인하는 데서 시작합니다. 여러 작업을 이어가려면 여기에 대화 재개용 세션 ID와 파일이 저장된 작업 위치까지 함께 관리해야 해요.

가장 먼저 할 일은 추적할 대상을 구분하는 것입니다. 독립된 세션인지, 아니면 세션 안의 하위 작업이나 도구 호출인지부터 나눠 보세요. Agent View의 세션 목록, OpenTelemetry의 실행 구간, Managed Agents의 스레드는 보여주는 범위가 서로 다릅니다. 이 차이를 모르면 목록에 없는 작업을 종료된 것으로 오해하거나, 세션 상태만 보고 지연 원인을 짐작하게 되기 쉽습니다.

세션 목록과 실행 구간은 어떻게 다르게 보이나요

claude agents로 여는 Agent View는 프로젝트를 가로질러 백그라운드 세션을 모아 보여주고, --cwd로 범위를 좁힐 수 있습니다. 여기서 흔히 헷갈리는 부분이 있어요. 다른 터미널에서 돌고 있는 대화형 세션은 백그라운드로 전환하기 전까지 표시되지 않고, 하위 에이전트와 팀원도 별도 행으로 나열되지 않습니다. 그러니 화면의 행 수를 전체 에이전트 수로 읽으면 안 됩니다.

Managed Agents의 상위 이벤트 스트림에는 하위 작업의 요약과 주요 대기 이벤트만 올라옵니다. 구체적인 도구 호출과 진행 과정은 해당 스레드로 들어가서 확인해야 해요.

작업이 느리다면 저는 승인 대기부터 보라고 권합니다.

OpenTelemetry 트레이스는 API 호출, 도구 승인 대기, 실제 도구 실행을 나눠서 보여줍니다. 사람이 승인하지 않아 멈춘 구간을 먼저 걸러 내면 조사 범위가 확 좁아지거든요. 승인 대기가 짧았다면 그다음은 API 호출과 도구 실행 가운데 어느 쪽이 길어졌는지 비교하면 됩니다.

수집 연결과 세션 ID·작업 위치 기록

OpenTelemetry는 아래 세 단계면 최소한으로 붙일 수 있습니다.

1. CLAUDE_CODE_ENABLE_TELEMETRY=1로 수집 기능을 켭니다.
2. 데이터를 내보낼 exporter와 수집 주소를 지정합니다.
3. 수집 대상에 claude_code.session.count 메트릭 또는 claude_code.user_prompt 이벤트가 들어오는지 확인합니다.

기본 전송 간격은 메트릭 60초, 로그 5초입니다. 설정을 마쳤는데 화면에 변화가 없다면 고장보다 전송 지연을 먼저 의심해 보세요. 트레이스는 기본적으로 꺼져 있고 별도 베타 설정이 필요하니 공식 Monitoring 문서를 기준으로 적용하는 편이 안전해요. 프롬프트 내용과 도구 세부 정보도 기본적으로 가려지므로, 실행 흐름을 수집하는 것과 대화 원문을 수집하는 것은 별개로 생각해야 합니다.

다중 사용자 환경이라면 사용자·대화와 세션 ID를 연결해 저장해 두고, resume으로 원하는 세션을 직접 지정하는 방식을 권합니다. Agent SDK의 continue는 현재 디렉터리에서 가장 최근 세션을 고르기 때문에, 여러 대화가 섞여 있을 때 대상 선택을 맡기기엔 적절하지 않아요. fork는 기존 대화 이력을 복사해 새 세션을 만들고 원본 이력은 그대로 둡니다. 다만 코드 파일까지 분리해 주지는 않으니 이 점을 착각하지 마세요. 재개와 분기의 적용 범위는 세션 공식 문서에서 확인할 수 있습니다.

그래서 세션 ID 옆에는 실제 작업 디렉터리와 Git worktree 위치, 미완료 작업과 담당자를 함께 적어 두기를 제안합니다. 대화를 되살리는 일과 파일을 되살리는 일은 범위가 다르고, 재개한 뒤 누가 어느 파일을 고칠지도 이 기록이 있어야 판단할 수 있어요.

대기인지 완료인지, 어디까지 복구되는지

Managed Agents에서 idle이 보인다고 바로 완료로 판단하기는 어렵습니다. 사용자 응답을 기다리는 스레드도 idle일 수 있어서 stop_reason과 미처리 도구 요청을 같이 봐야 해요. 반대 경우도 있습니다. 다른 스레드가 실행 중이면 일부 작업이 응답을 기다리고 있어도 전체 세션은 running으로 표시될 수 있습니다.

사용량을 볼 때는 시간을 어떤 기준으로 집계했는지부터 확인하세요. usage.active_seconds는 여러 스레드가 동시에 실행된 시간을 중복 계산하지 않고, stats.active_seconds는 스레드별 활동 시간을 합산합니다. 두 값을 같은 기준의 실행 시간처럼 비교하면 병렬 작업의 사용량을 잘못 읽게 돼요.

파일 격리 여부는 백그라운드로 돌고 있는지와는 따로 따져야 합니다. Agent View에서 새로 배정한 작업은 일반적으로 파일을 수정하기 전에 독립 worktree로 옮겨 갑니다. 반면 기존 대화형 세션을 백그라운드로 옮기면 원래 작업 위치를 그대로 씁니다. Git 저장소가 아니거나 격리 설정을 끈 경우의 예외는 Agent View 공식 문서에서 확인하세요.

Agent Teams에서 같은 프로세스 안에 실행하던 팀원은 /resume이나 /rewind로 복원되지 않으니, 남은 작업과 담당자를 따로 확인해야 합니다.

이 내용의 기준일은 2026-10-20입니다. Agent Teams는 실험적 기능이고 OpenTelemetry 트레이스는 베타이며, Managed Agents 설명은 베타 헤더 managed-agents-2026-04-01이 표시된 문서 범위에 해당합니다.