> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 샌드박스 로깅

> stream_logs()를 사용하여 샌드박스 메인 프로세스의 컨테이너 로그(stdout 및 stderr)를 스트리밍합니다.

이 예시에서는 `CWSANDBOX_API_KEY`에 설정된 CoreWeave API 액세스 토큰을 사용합니다. Forge API 키 인증 방법은 [시작하기](/ko/products/sandboxes/get-started)를 참조하세요. CKS 요구 사항은 [배치 모드](/ko/products/sandboxes/placement)를 참조하세요.

이 가이드에서는 샌드박스에서 컨테이너 로그를 캡처하여 메인 프로세스의 동작을 모니터링하고, 실패를 디버깅하거나, 샌드박스가 중단된 후 출력을 확인하는 방법을 설명합니다.

컨테이너 로그는 샌드박스의 **메인 프로세스**에서 발생하는 stdout 및 stderr입니다. `stream_logs()`로 스트리밍하세요. 이 메서드는 `Sandbox.run()`에 전달된 명령어의 출력을 캡처합니다. `exec()` 명령어의 출력은 포함되지 않습니다. 해당 출력에는 `Process.stdout` 또는 `Process.stderr`를 사용하세요.

`stream_logs()`는 로그 줄을 생성하는 `StreamReader`를 반환합니다. 동기 또는 비동기 방식으로 순회하세요.

<Note>
  명령어 없이 `Sandbox.run()`을 호출하면 샌드박스의 기본 명령어가 stdout 또는 stderr에 쓰지 않으므로 `stream_logs()`는 출력을 반환하지 않습니다. stdout 또는 stderr에 쓰는 명령어를 전달하세요.
</Note>

<h2 id="retrieve-recent-logs">
  최근 로그 조회
</h2>

`tail_lines`를 사용하여 전체 이력을 스트리밍하지 않고 가장 최근 로그 줄을 가져오세요. 실행 중인 샌드박스를 빠르게 확인할 때 유용합니다.

```python theme={"system"}
for line in sandbox.stream_logs(tail_lines=100):
    print(line, end="")
```

<h2 id="follow-mode">
  팔로우 모드
</h2>

`tail -f`처럼 로그를 지속적으로 스트리밍합니다. iterator는 새 데이터가 도착할 때까지 대기합니다.

```python theme={"system"}
for line in sandbox.stream_logs(follow=True):
    print(line, end="")
```

팔로우 모드에서 순회 중에 중지하려면 `Ctrl+C`를 누르세요.

<h2 id="filter-by-time">
  시간별 필터링
</h2>

`since_time`을 전달하면 특정 타임스탬프 이후의 로그만 가져옵니다. 이를 통해 출력을 배포 또는 인시던트 이후의 로그와 같은 관심 윈도우로 좁힐 수 있습니다.

```python theme={"system"}
from datetime import datetime, timezone

since = datetime(2026, 2, 20, 14, 0, 0, tzinfo=timezone.utc)
for line in sandbox.stream_logs(since_time=since):
    print(line, end="")
```

<h2 id="timestamps">
  타임스탬프
</h2>

`timestamps=True`로 설정하면 각 줄 앞에 서버의 ISO 8601 타임스탬프가 추가됩니다. 서버 측 타임스탬프는 샌드박스 이벤트를 다른 시스템과 연관 짓는 데 도움이 됩니다.

```python theme={"system"}
for line in sandbox.stream_logs(tail_lines=10, timestamps=True):
    print(line, end="")
# 출력: 2026-02-20T14:30:00Z 로그 한 줄
```

<h2 id="async-iteration">
  비동기 순회
</h2>

애플리케이션에서 `asyncio`를 사용하는 경우, 이벤트 루프가 차단되지 않도록 `async for`로 동일한 `StreamReader`를 순회하세요.

```python theme={"system"}
async for line in sandbox.stream_logs(follow=True):
    print(line, end="")
```

<h2 id="retrieve-logs-from-stopped-sandboxes">
  중단된 샌드박스에서 로그 가져오기
</h2>

샌드박스가 중단된 후에도 로그를 사용할 수 있으므로, 실패 원인을 조사하거나 완료된 작업의 출력을 검토할 수 있습니다. 완료, 실패 또는 종료된 샌드박스에서 과거 로그를 가져오세요:

```python theme={"system"}
sb = Sandbox.from_id("sbx-abc123").result()
for line in sb.stream_logs(tail_lines=50):
    print(line, end="")
```

중단된 샌드박스는 `follow=False`(기본값)만 지원합니다.

<h2 id="see-also">
  참고 자료
</h2>

* [명령어 실행](/ko/products/sandboxes/client/guides/execution): `exec()`로 명령어를 실행하고 출력을 스트리밍하는 방법
* [동기 vs 비동기](/ko/products/sandboxes/client/guides/sync-vs-async): 순회 패턴