> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/creator/content-creator-ko/sdk7/debugging/scene-insights.md).

# Scene Insights

지속적으로 저장되는 멀티플레이어 서버 로그를 검색하고, 실시간 로그를 추적하며, 씬 성능 지표를 확인하세요.

Scene Insights를 사용하면 배포된 [멀티플레이어 서버](https://docs.decentraland.org/creator/content-creator-ko/sdk7/networking/authoritative-servers.md) 씬을 조사할 수 있습니다. 과거 서버 로그를 검색하고, 새 메시지를 실시간으로 확인하며, 터미널이나 AI 어시스턴트에서 CPU, 메모리 및 기타 메트릭을 가져오세요.

**로그와 메트릭은 7일 동안 보관됩니다**. 서버 재시작과 씬 재배포 후에도 유지됩니다. 이 기능은 서버 측 실행을 다룹니다. 클라이언트 측 및 렌더링 문제에는 [프로덕션 환경에서 디버깅](https://docs.decentraland.org/creator/content-creator-ko/sdk7/debugging/debug-in-prod.md) 을 사용하세요.

## 프로젝트 업데이트

씬 프로젝트에서 다음 명령을 실행해 최신 `auth-server` SDK와 런타임을 설치하세요.

```bash
npm install @dcl/sdk@auth-server @dcl/js-runtime@auth-server
```

프로젝트의 `@dcl/sdk-commands` 도 `package.json`에 직접 명시되어 있다면, 이것도 `@auth-server` 로 업데이트하세요. 설치된 CLI에 다음 명령이 포함되어 있는지 확인하세요. `login`, `logs`, `tail`, `metrics`및 `executions`:

```bash
npx sdk-commands scene-insights --help
```

AI 지원 디버깅을 위해 [SDK Skills](https://docs.decentraland.org/creator/content-creator-ko/sdk7/getting-started/vibe-coding.md):

```bash
npx skills add decentraland/sdk-skills --all
```

도 설치하거나 업데이트하세요. AI 동반자에게 설정을 요청할 수 있습니다.

> 이 씬을 최신 auth-server SDK 및 런타임으로 업데이트하고 Decentraland SDK Skills도 업데이트해 줘. Scene Insights에 로그인할 수 있도록 도와준 다음, 지난 2시간 동안의 서버 오류와 CPU 및 메모리 사용량을 조사해 줘.

이미 배포된 씬의 텔레메트리를 읽는 데는 재배포가 필요하지 않습니다. 권한을 변경하는 경우에는 재배포해야 합니다.

## 누가 데이터를 읽을 수 있나요?

다음 조건 중 하나를 충족하는 지갑으로 로그인하세요.

* 배포된 씬의 최상위 수준 `logsPermissions` 배열에 포함되어 있습니다.
* 해당 지갑이 월드를 소유합니다.
* 해당 지갑은 월드 전체 또는 씬의 배포된 모든 필지를 아우르는 권한을 부여받은 월드 배포 협업자입니다.
* Genesis City의 경우, 해당 지갑은 씬의 **기본 필지**를 소유하거나, 해당 필지에 대한 LAND 관리 권한을 위임받았습니다. `operator`, `updateOperator`, `updateManager`또는 `approvedForAll`.

소유자와 권한이 있는 관리자는 `logsPermissions` 항목이나 씬 재배포가 필요하지 않습니다. 다른 지갑에 명시적으로 액세스 권한을 부여하려면 해당 지갑을 `scene.json` 그런 다음 다시 배포합니다:

```json
{
  "logsPermissions": ["0xYourWalletAddress"]
}
```

Genesis City에서는 씬 내의 다른 구획을 조회하더라도 배포된 씬의 기본 구획을 기준으로 권한을 확인합니다. 다른 구획의 소유권이나 관리 권한만으로는 해당 씬에 접근할 수 없습니다.

동일한 권한이 과거 로그, 실시간 로그, 메트릭, 실행 기록에 적용됩니다. 접근 권한은  **현재 권한**을 따릅니다. 현재 권한이 있는 사용자는 누구나 최대 7일간 보관된 동일한 씬 키의 모든 기록을 읽을 수 있습니다. 여기에는 다른 사람이 씬을 배포했을 때 작성된 로그도 포함됩니다. 새 소유자, 운영자, 자격을 갖춘 임차인, 그리고 새로 추가된 지갑도 포함됩니다. `logsPermissions`에 지갑을 추가할 때는 접근 권한을 부여하기 전에 해당 기록도 고려하세요.

권한 변경 사항은 즉시 적용되지 않습니다. 기본적으로 권한 캐시는 60초 동안 유지되고, 열려 있는 실시간 스트림은 5분마다 접근 권한을 다시 확인합니다. 열린 스트림에서 권한 철회를 확인하는 데 약 6분이 걸릴 수 있습니다. 이는 기본 시간이며 엄격한 기한은 아닙니다. 구성 설정 및 일시적인 용량 부족 상황에서 적용되는 제한된 유예 기간에 따라 지연이 더 길어질 수 있습니다. 로그인해도 다른 씬의 로그를 읽을 권한이 생기지는 않습니다.

## 로그인

```bash
npx sdk-commands scene-insights login
```

일반 지갑이나 스마트 계약 지갑을 사용해 브라우저에서 로그인을 승인합니다. 그러면 로그, 메트릭, 실행 기록을 읽는 데만 사용할 수 있는 Insights 세션이 생성됩니다. 세션은 최대  **12시간** 동안 유효하며, 상위 세션의 만료 시점을 넘지 않습니다. 이후 명령어에서는 추가 승인 없이 이 세션을 재사용합니다.

로그인된 주소와 만료 시점을 확인하려면 다음을 실행합니다:

```bash
npx sdk-commands scene-insights session --json
```

세션이 만료되면  `login` 을 다시 실행하세요. AI 어시스턴트가 대신 조사하는 경우에도 지갑 로그인을 직접 승인하세요. 개인 키나 캐시된 세션 파일을 공유하지 마세요.

### 세션 파일을 비공개로 유지하기

{% hint style="warning" %}
**로그인 세션 파일을 절대 커밋하거나 배포하거나 공유하지 마세요.** 기본적으로 파일은 다음 위치에 저장됩니다:  `~/.dcl/scene-insights-session.json`. 이 파일에는 임시 개인 서명 키와 지갑의 읽기 전용 위임 정보가 들어 있습니다. 파일을 복사한 사람은 누구나 세션이 만료될 때까지 해당 자격 증명을 사용해 지갑이 접근할 수 있는 씬의 로그, 메트릭, 실행 기록을 읽을 수 있습니다. 팀원, AI 어시스턴트, 지원 채팅, 공개 이슈 보고서에 보내거나 프로젝트 아카이브에 포함하지 마세요.
{% endhint %}

SDK가 파일을 자동으로 보호합니다:

* 기본적으로 파일을 홈 디렉터리의 씬 프로젝트 외부에 저장합니다.  `DCL_SCENE_INSIGHTS_SESSION_DIR`를 설정하면 해당 디렉터리의  `.dcl`  폴더를 대신 사용합니다.
* 세션 폴더의  `*`  `.gitignore` 에 해당 파일을 추가하며, Git에서 이미 추적 중인 세션 파일은 저장하거나 사용하지 않습니다.
* 세션 파일을 소유자만 접근할 수 있는 권한(`0600`)으로 작성하며, 지원되는 시스템에서는 폴더를  `0700`  권한으로 생성합니다.
* 표준 SDK 배포 파일 수집기는  `.dcl`을 비롯해 점으로 시작하는 파일과 디렉터리를 제외합니다. 이 동작은  `.dclignore`.

와는 별개로 적용됩니다. 다음 사항에 유의하세요:

* 커밋하기 전에 스테이징된 파일을 확인하세요. 세션 파일을 강제로 추가하지 마세요.  `.gitignore` 는 Git에서 이미 추적 중인 파일을 보호하지 않습니다.
* 세션 위치를 변경하는 경우 가능하면 씬 프로젝트 외부에 두세요. 세션 파일을 씬 에셋이나 배포 가능한 다른 폴더로 복사하거나 이름을 바꾸어 옮기지 마세요.
* 사용자 지정 배포, 백업 또는 ZIP 스크립트를 사용하는 경우 세션 파일과  `.dcl`  자격 증명을 명시적으로 제외하세요. 해당 도구는 SDK의 제외 설정을 적용하지 않을 수 있습니다.
* 필요한 경우  `npx sdk-commands scene-insights session --json` 의 안전한 상태 출력만 공유하고, 세션 파일 자체는 절대 공유하지 마세요. 팀원은 각자 권한이 있는 지갑으로 로그인해야 합니다.

`npx sdk-commands scene-insights logout` 로컬에 저장된 세션을 삭제합니다. 하지만 **이미 공유된 사본을** 폐기하지는 않습니다. 해당 자격 증명은 만료될 때까지 계속 사용할 수 있습니다. 파일이 노출된 경우, 해당되는 공유 아티팩트와 Git 기록에서 파일을 제거하세요. 로컬 파일을 삭제하거나 다시 로그인해도 노출된 사본은 무효화되지 않습니다.

## Scene 선택

명령은 Scene 프로젝트에서 World를 다음 값으로 추론합니다: `scene.json`의 `worldConfiguration.name`또는 Genesis City의 경우 `scene.base` 를 사용합니다. 직접 지정할 수도 있습니다:

```bash
# 하나의 World
npx sdk-commands scene-insights logs --world myworld.dcl.eth

# 여러 Scene이 있는 World의 Scene 하나
npx sdk-commands scene-insights logs --world myworld.dcl.eth --position 10,10

# Genesis City Scene: 좌표가 음수이면 =를 사용합니다
npx sdk-commands scene-insights logs --position=-125,-96
```

명령은 기본적으로 프로덕션(`.org`)을 대상으로 합니다. 개발 네트워크의 Scene을 대상으로 하려면 다음을 추가하세요: `--target https://multiplayer-scenes-insights-service.decentraland.zone` 로그인, 세션 확인 및 쿼리에 추가합니다. 전체 과정에서 같은 대상을 사용하면 스마트 계약 지갑이 올바른 네트워크에서 검증됩니다.

## 로그 및 실행 검색

```bash
# 최근 6시간 동안의 최신 오류 200개
npx sdk-commands scene-insights logs --from 6h --level error --limit 200

# 고정된 UTC 시간 범위에서 텍스트 검색
npx sdk-commands scene-insights logs --from 2026-11-01T14:00:00Z --to 2026-11-01T14:30:00Z --query "player joined"

# 지난 하루 동안의 서버 실행 목록
npx sdk-commands scene-insights executions --from 1d

# 실행 하나의 로그: executions에서 얻은 ID로 EXECUTION_ID를 바꾸세요
npx sdk-commands scene-insights logs --execution EXECUTION_ID --from 1d
```

`logs` 는 기본적으로 최근 1시간의 일치하는 로그 중 최신 100개를 시간순으로 표시합니다. CLI는 `--limit` 에 1\~10,000 사이의 값을 지정할 수 있으며, 필요에 따라 여러 API 페이지를 가져옵니다. `--level` 은 최소 심각도 수준을 지정합니다(`warn` 은 오류를 포함합니다). `--query` 는 ASCII 대소문자를 구분하지 않고 리터럴 텍스트를 검색합니다. 로그 출처를 선택하려면 `--source scene,engine,stderr` 를 사용하거나 이 출처 중 일부를 지정하세요.

`executionId` 는 서버 실행을 식별합니다. `entityId` 는 배포된 Scene 버전을 식별합니다. 새 실행은 유휴 상태에서 중지 후 다시 시작된 경우, 롤아웃 또는 비정상 종료를 의미할 수 있습니다. 비정상 종료라고 판단하기 전에 주변 로그를 확인하세요.

다음을 추가하세요: `--json` 기계 판독 가능한 출력을 위해 사용합니다. CLI는 과거 로그를 단일 JSON 문서로 반환하며, 이 문서의 `more: true` 필드는 반환된 한도를 초과하는 일치 항목이 더 있음을 의미합니다. 검색 범위를 좁히거나 한도를 높이세요. 직접 API 클라이언트는 페이지당 최대 1,000개의 행을 받고, 페이지네이션에는 커서를 사용합니다.

## 실시간 로그 따라가기

```bash
npx sdk-commands scene-insights tail
```

누르세요 **Ctrl+C** 를 눌러 중지합니다. AI 어시스턴트에게 조사를 요청하는 경우처럼 캡처 시간을 제한하려면 다음을 사용하세요.

```bash
npx sdk-commands scene-insights tail --for 30s --lines 20 --json
```

최신 20개 줄을 출력한 다음 30초 동안 새 로그를 따라갑니다. JSON 출력에는 한 줄당 하나의 로그 항목이 포함됩니다. 실행 중 로그를 따라가는 동안 CLI는 연결을 다시 설정하고 이어서 수집합니다. 로그는 보통 씬에서 기록된 후 몇 초 뒤에 도착합니다.

`tail` 은 수준 및 텍스트 필터를 지원합니다. 과거 시간 범위나 실행/소스 필터를 사용하려면 `logs`.

를 사용하세요.  `npm run server-logs`를 사용하는 경우 프로젝트의 `package.json` 에 다음이 포함되어 있는지 확인하세요.

```json
{
  "scripts": {
    "server-logs": "sdk-commands scene-insights tail"
  }
}
```

업데이트된 SDK로 프로젝트를 전체 빌드하면 SDK가 생성한 기본 스크립트가 생성되거나 마이그레이션됩니다. 사용자 지정 스크립트는 유지되며, `--skip-build` 를 사용하는 미리보기와 단일 파일 빌드는 이 스크립트를 업데이트하지 않습니다. 로그를 확인하기 위해 다시 빌드하지 않고 스크립트를 직접 편집할 수 있습니다.

## 성능 메트릭 확인

먼저 데이터가 있는 메트릭을 나열한 다음 시계열을 조회하세요.

```bash
npx sdk-commands scene-insights metrics --json
npx sdk-commands scene-insights metrics cpu.percent --from 2h --step 60 --json
npx sdk-commands scene-insights metrics mem.heap_used --from 2h --step 60 --json
```

`--step` 은 버킷 크기를 초 단위로 설정합니다. 사용 가능한 메트릭은 엔진 버전과 씬 활동에 따라 달라집니다. 메트릭 탐색과 `executions` 의 기본 조회 기간은 최근 24시간입니다. 메트릭 시계열에 `--execution EXECUTION_ID` 를 지정하면 특정 실행을 분리해 확인할 수 있습니다.

| 메트릭                                                     | 설명                                                                           |
| ------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `cpu.percent`                                           | 실행 스레드의 CPU 사용률을 코어 하나 대비 백분율로 표시합니다. 값이 지속적으로 100%에 가까우면 해당 스레드가 바쁘다는 뜻입니다. |
| `cpu.run_ms`                                            | CPU 시간이 사용된 위치: `onStart`/`onUpdate`이며, 벽시계 기준 지연 시간이 아닙니다.                  |
| `mem.heap_used`, `mem.heap_limit`, `mem.external_bytes` | JavaScript 힙 사용량, 힙 한도 및 V8 외부 메모리를 나타냅니다.                                   |
| `logs.lines`, `logs.bytes`                              | 속도 제한 적용 전의 콘솔 출력으로, 과도한 로그를 파악하는 데 유용합니다.                                   |
| `fetch.failed`, `storage.failed`                        | 아웃바운드 HTTP 또는 스토리지 호출의 요청 전송 오류입니다. 오류 로그와 함께 확인하세요.                         |
| `fetch.status_4xx`, `fetch.status_5xx`                  | HTTP 오류 응답입니다. 이는 다음 항목에 집계되지 않습니다. `fetch.failed`                           |
| `logs.dropped`                                          | 엔진의 틱당 로그 예산을 초과해 버려진 줄 수                                                    |
| `comms.msgs_out`, `comms.bytes_out`                     | 플레이어에게 전송된 메시지 및 바이트 수                                                       |

CPU 메트릭은 서버 전체를 측정하지 않으며, 메모리 메트릭도 프로세스의 전체 메모리나 컨테이너 한도를 나타내지 않습니다. 메모리 누수나 성능 문제를 진단하기 전에 동일한 실행, 시간 범위, 워크로드를 비교하세요.

게이지는 버킷별로 `avg` 및 `max` 를 반환합니다. 합계는 `sum` 과 초당 `rate`를 반환합니다.  `null`  포인트는 저장된 샘플이 없다는 뜻이지 사용량이 0이라는 뜻은 아닙니다. 유휴 장면, 지연, 수집 실패 모두 데이터 공백을 일으킬 수 있습니다.

## 보존 기간 및 한도

| 한도              | 기본값                                                       |
| --------------- | --------------------------------------------------------- |
| 로그 및 메트릭 보존 기간  | 7일                                                        |
| 최대 쿼리 시간 범위     | 7일                                                        |
| CLI 쿼리당 로그 결과 수 | 기본값 100개, 페이지네이션을 사용하면 최대 10,000개                         |
| 메트릭 시계열         | 최대 1,500개 버킷. 긴 시간 범위에는 `--step` 값을 늘리세요.                 |
| 지속적인 장면 로그 기록   | 초당 50줄 및 64KiB                                            |
| 로그 버스트 허용량      | 500줄 및 512KiB                                             |
| 일일 장면 로그 할당량    | 서버 프로세스당 500,000줄 또는 128MiB의 소프트 한도이며, 00:00 UTC에 초기화됩니다. |

일일 할당량 카운터는 메모리에 보관됩니다. 서버 프로세스를 재시작하거나 장면이 다른 복제본으로 이동해도 카운터가 초기화되므로, 일일 할당량은 이러한 변경 전반에 걸쳐 적용되는 대략적인 한도입니다.

속도 제한 및 일일 할당량을 초과한 로그는 삭제되며, 삭제된 줄은 나중에 가져올 수 없습니다. 엔진 경고 메시지에 삭제 및 할당량 초기화가 표시됩니다. 일일 할당량에 도달하면 초기화될 때까지 추가 로그 저장이 중단되지만 장면은 계속 실행됩니다. 반복되는 프레임별 로그를 줄여 중요한 메시지가 예산 내에 들어오도록 하세요.

엔진에는 별도의 틱당 로그 예산(기본값 1,000줄)도 있습니다. 초과한 줄은 내보내기 전에 버려지며 다음 항목에 집계됩니다. `logs.dropped`.

큰 메시지는 잘릴 수 있습니다(API의 메시지당 기본값은 8,192자). 데이터 수집은 최선의 노력으로 이루어지므로, 서비스 중단, 내보내기 실패, 속도 제한으로 데이터 공백이 생길 수 있습니다. 수집된 원격 측정 데이터만 사용할 수 있으며, 새 CLI를 설치해도 이전 데이터나 삭제된 데이터를 복구할 수 없습니다. 결과가 비어 있다는 사실만으로 장면이 정상이라고 단정할 수는 없습니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.decentraland.org/creator/content-creator-ko/sdk7/debugging/scene-insights.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
