> 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-zh/chang-jing-sdk7/tiao-shi/scene-insights.md).

# Scene Insights

搜索持久化的多人服务器日志，跟踪实时日志，并检查场景性能指标。

Scene Insights 可帮助你调查已部署的 [多人游戏服务器](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/lian-wang/authoritative-servers.md) 场景。搜索历史服务器日志、实时查看新消息，并通过终端或 AI 助手获取 CPU、内存及其他指标。

**日志和指标会保留 7 天**，即使服务器重启或场景重新部署也会保留。这涵盖服务器端执行；客户端和渲染问题请使用 [在生产环境中调试](https://docs.decentraland.org/creator/content-creator-zh/chang-jing-sdk7/tiao-shi/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-zh/chang-jing-sdk7/ru-men/vibe-coding.md):

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

你可以让 AI 助手帮你完成设置：

> 将此场景更新到最新的 auth-server SDK 和运行时，并更新 Decentraland SDK Skills。帮我登录 Scene Insights，然后调查过去两小时内的服务器错误以及 CPU 和内存使用情况。

读取已部署场景的遥测数据无需重新部署。更改权限则需要重新部署。

## 谁可以读取这些数据？

使用满足以下任一条件的钱包登录：

* 它出现在已部署场景根目录的 `logsPermissions` 数组中。
* 它拥有该 World。
* 它是 World 部署的协作者，且获授的权限涵盖整个 World 或该场景已部署的所有地块。
* 对于 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 会自动保护该文件：

* 默认情况下，SDK 会将文件保存在主目录下，位于场景项目之外。如果设置了 `DCL_SCENE_INSIGHTS_SESSION_DIR`，则会改为使用该目录下的 `.dcl` 文件夹。
* SDK 会将 `*` 添加到会话文件夹的 `.gitignore` 中，并拒绝保存或使用已被 Git 跟踪的会话文件。
* SDK 会以仅所有者可访问的权限（`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.json`的 `worldConfiguration.name`推断 World；如果没有，则使用 `scene.base` 作为 Genesis City。你也可以显式指定：

```bash
# 一个 World
npx sdk-commands scene-insights logs --world myworld.dcl.eth

# 多场景 World 中的一个场景
npx sdk-commands scene-insights logs --world myworld.dcl.eth --position 10,10

# Genesis City 场景：坐标为负数时使用 =
npx sdk-commands scene-insights logs --position=-125,-96
```

命令默认使用生产环境（`.org`）。对于开发网络上的场景，请添加 `--target https://multiplayer-scenes-insights-service.decentraland.zone` 以用于登录、会话检查和查询。始终使用相同的 target，还能确保在正确的网络上验证智能合约钱包。

## 搜索日志和执行记录

```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

# 某次运行的日志：将 EXECUTION_ID 替换为 executions 返回的 ID
npx sdk-commands scene-insights logs --execution EXECUTION_ID --from 1d
```

`logs` 默认查询最近一小时内匹配的最新 100 行，并按时间顺序显示。CLI 接受 `--limit` 的取值范围为 1 到 10,000，并会按需获取多个 API 分页。 `--level` 表示最低严重级别（`warn` 包括错误）； `--query` 使用 ASCII 不区分大小写的方式匹配字面文本。使用 `--source scene,engine,stderr` 选择日志来源，也可以传入这些来源的子集。

`executionId` 用于标识一次服务器运行； `entityId` 用于标识已部署的场景版本。新的执行记录可能表示空闲后停止并重新启动、版本发布或崩溃。在断定发生崩溃之前，请先检查前后相关日志。

添加 `--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`                                            | 在 `onStart`/`onUpdate`中耗用的 CPU 时间，不代表墙钟延迟       |
| `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`                                          | 引擎因每个 tick 的日志预算而丢弃的行数                          |
| `comms.msgs_out`, `comms.bytes_out`                     | 发送给玩家的消息数和字节数                                   |

CPU 指标并不衡量整个服务器，内存指标也不代表进程的总内存或容器限制。在诊断内存泄漏或性能问题之前，请比较相同的执行、时间范围和工作负载。

仪表盘指标每个时间桶返回 `avg` 和 `max` 。求和指标返回 `sum` 以及每秒 `rate`。一个 `null` 数据点表示没有存储的样本，而不是用量为零；场景空闲、延迟和采集失败都可能导致数据缺失。

## 保留期限与限制

| 限制              | 默认值                                           |
| --------------- | --------------------------------------------- |
| 日志和指标保留期限       | 7 天                                           |
| 查询时间范围上限        | 7 天                                           |
| 每次 CLI 查询的日志结果数 | 默认 100 条；通过分页最多可达 10,000 条                    |
| 指标序列            | 最多 1,500 个时间桶；较长时间范围请增大 `--step` 的值           |
| 场景持续日志记录        | 每秒 50 行和 64 KiB                               |
| 日志突发额度          | 500 行和 512 KiB                                |
| 场景每日日志配额        | 软上限为每个服务器进程 500,000 行或 128 MiB；于 UTC 00:00 重置 |

每日配额计数器保存在内存中。服务器进程重启，或场景迁移到另一个副本时，计数器也会重置，因此发生此类变更时，每日配额只是近似上限。

速率限制和每日配额会丢弃超出的日志；被丢弃的行之后无法找回。引擎警告消息会报告丢弃情况和配额重置。达到每日配额后，在重置之前将停止持久化更多日志；场景仍会继续运行。请减少重复的逐帧日志记录，以便有用的消息能控制在预算内。

引擎还设有单独的每 tick 日志预算（默认 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-zh/chang-jing-sdk7/tiao-shi/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.
