> 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-pt/scenes-sdk7/depuracao/scene-insights.md).

# Scene Insights

Pesquise logs persistentes do Multiplayer Server, acompanhe logs em tempo real e inspecione métricas de desempenho da scene.

O Scene Insights ajuda a investigar uma [cena](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/rede/authoritative-servers.md) em produção. Pesquise registos históricos do servidor, acompanhe novas mensagens em tempo real e obtenha métricas de CPU, memória e outras a partir do terminal ou de um assistente de IA.

**Os registos e as métricas são guardados durante 7 dias**, incluindo reinícios do servidor e novas implementações da cena. Isto abrange a execução no servidor; use [Debug in Production](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/depuracao/debug-in-prod.md) para problemas do lado do cliente e de renderização.

## Atualizar o projeto

Execute estes comandos a partir do projeto da cena para instalar a versão mais recente do `auth-server` SDK e do runtime:

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

Se o projeto também listar `@dcl/sdk-commands` diretamente em `package.json`, atualize-o também para `@auth-server` . Confirme que o CLI instalado inclui `login`, `logs`, `tail`, `metrics`, e `executions`:

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

Para depuração assistida por IA, instale ou atualize também as [SDK Skills](https://docs.decentraland.org/creator/content-creator-pt/scenes-sdk7/primeiros-passos/vibe-coding.md):

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

Pode pedir ao seu assistente de IA para fazer a configuração:

> Atualiza esta cena para a versão mais recente do SDK e do runtime auth-server e atualiza as Decentraland SDK Skills. Ajuda-me a iniciar sessão no Scene Insights e, em seguida, a investigar os erros do servidor e a utilização de CPU e memória nas últimas duas horas.

A leitura da telemetria de uma cena já implementada não requer uma nova implementação. As alterações de permissões requerem.

## Quem pode ler os dados?

Inicie sessão com uma wallet que cumpra uma destas condições:

* Está incluída no array de nível raiz `logsPermissions` da cena implementada.
* É proprietária do World.
* É colaboradora da implementação do World, com uma autorização que abrange todo o World ou todos os parcels implementados da cena.
* Na Genesis City, é proprietária do **parcel base**da cena ou tem permissão delegada para gerir LAND nesse parcel: `operator`, `updateOperator`, `updateManager`, ou `approvedForAll`.

Os proprietários e gestores elegíveis não precisam de uma entrada em `logsPermissions` nem de uma nova implementação da cena. Para conceder explicitamente acesso a outra wallet, adicione-a a `scene.json` e voltar a publicar:

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

Na Genesis City, a permissão é verificada com base na parcela base da Scene publicada, mesmo que consulte outra parcela dentro da Scene. A propriedade ou os direitos de gestão de outra parcela, por si só, não concedem acesso à Scene.

As mesmas permissões abrangem registos históricos, registos em tempo real, métricas e histórico de execução. O acesso segue as **permissões atuais**: qualquer pessoa atualmente autorizada pode ler todo o histórico retido durante até 7 dias sob a mesma chave de Scene, incluindo registos escritos quando outra pessoa publicou a Scene. Isto inclui novos proprietários, operadores, arrendatários elegíveis e carteiras recentemente adicionadas a `logsPermissions`. Tenha esse histórico em conta antes de conceder acesso.

As alterações de permissões não são imediatas. Por predefinição, as caches de permissões duram 60 segundos e os fluxos em tempo real abertos voltam a verificar o acesso a cada 5 minutos. Conte com cerca de 6 minutos para que um fluxo aberto detete a revogação. Estes são tempos predefinidos, não um prazo rigoroso: a configuração e os períodos de tolerância limitados durante falhas temporárias de capacidade podem prolongar o atraso. Iniciar sessão não concede permissão para ler outras Scenes.

## Iniciar sessão

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

Aprove o início de sessão no browser com uma carteira normal ou uma carteira de smart contract. Isto cria uma sessão do Insights limitada à leitura de registos, métricas e execuções. Tem uma duração máxima de **12 horas**, limitada pela data de expiração da sessão principal. Os comandos seguintes reutilizam-na sem exigir outra aprovação.

Verifique o endereço com sessão iniciada e a data de expiração com:

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

Quando a sessão expirar, execute `login` novamente. Se um assistente de IA estiver a investigar por si, aprove pessoalmente o início de sessão da carteira. Não partilhe com ele chaves privadas nem o ficheiro de sessão em cache.

### Mantenha o ficheiro de sessão privado

{% hint style="warning" %}
**Nunca submeta, publique ou partilhe o ficheiro da sessão de início de sessão.** Por predefinição, é guardado em `~/.dcl/scene-insights-session.json`. Contém uma chave privada de assinatura temporária e a delegação só de leitura da sua carteira. Qualquer pessoa com uma cópia pode usar essas credenciais para ler registos, métricas e o histórico de execução das Scenes a que a sua carteira tem acesso, até a sessão expirar. Não o envie a colegas, assistentes de IA, chats de suporte ou relatórios públicos de problemas, nem o inclua em arquivos do projeto.
{% endhint %}

O SDK protege-o automaticamente:

* Por predefinição, guarda o ficheiro na sua pasta pessoal, fora do projeto da Scene. Se definir `DCL_SCENE_INSIGHTS_SESSION_DIR`, utiliza a pasta `.dcl` desse diretório.
* Adiciona `*` à pasta de sessão `.gitignore` e recusa-se a guardar ou utilizar um ficheiro de sessão que já esteja a ser controlado pelo Git.
* Escreve o ficheiro de sessão com permissões apenas para o proprietário (`0600`) e cria a respetiva pasta com permissões `0700` em sistemas que as suportam.
* O coletor padrão de ficheiros de publicação do SDK exclui ficheiros e diretórios com nomes iniciados por ponto, incluindo `.dcl`, independentemente de `.dclignore`.

Tenha estas verificações em conta:

* Reveja os ficheiros preparados para submissão antes de fazer o commit. Não force a adição do ficheiro de sessão; `.gitignore` não protege ficheiros já controlados pelo Git.
* Se personalizar a localização da sessão, mantenha-a fora do projeto da Scene sempre que possível. Nunca copie nem mude o nome da sessão para a pasta de assets da Scene ou para outra pasta que possa ser publicada.
* Se utilizar scripts personalizados de publicação, cópia de segurança ou criação de ZIP, exclua explicitamente o ficheiro de sessão e as credenciais `.dcl` ; essas ferramentas podem não aplicar as exclusões do SDK.
* Quando necessário, partilhe apenas o resultado de estado seguro de `npx sdk-commands scene-insights session --json` , nunca o próprio ficheiro de sessão. Os colegas devem iniciar sessão com as suas próprias carteiras autorizadas.

`npx sdk-commands scene-insights logout` elimina a sessão guardada localmente. Não **revoga** cópias que já tenham sido partilhadas: essas credenciais podem continuar a ser utilizadas até expirarem. Se o ficheiro tiver sido exposto, remova-o dos artefactos partilhados e do histórico do Git, conforme aplicável; eliminar o ficheiro local ou iniciar sessão novamente não invalida a cópia exposta.

## Escolher uma Scene

A partir do projeto da Scene, os comandos inferem o World a partir de `scene.json`'s `worldConfiguration.name`, ou usam `scene.base` para Genesis City. Também pode escolher explicitamente:

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

# Uma Scene num World com várias Scenes
npx sdk-commands scene-insights logs --world myworld.dcl.eth --position 10,10

# Uma Scene de Genesis City: use = quando as coordenadas forem negativas
npx sdk-commands scene-insights logs --position=-125,-96
```

Por predefinição, os comandos usam produção (`.org`). Para uma Scene na rede de desenvolvimento, adicione `--target https://multiplayer-scenes-insights-service.decentraland.zone` ao início de sessão, às verificações de sessão e às consultas. Usar o mesmo target em todas estas operações também garante que as wallets de smart contract são validadas na rede correta.

## Pesquisar Logs e Executions

```bash
# Os 200 erros mais recentes das últimas 6 horas
npx sdk-commands scene-insights logs --from 6h --level error --limit 200

# Encontrar texto num intervalo de tempo UTC fixo
npx sdk-commands scene-insights logs --from 2026-11-01T14:00:00Z --to 2026-11-01T14:30:00Z --query "player joined"

# Listar as execuções do Server do último dia
npx sdk-commands scene-insights executions --from 1d

# Logs de uma execução: substitua EXECUTION_ID por um ID obtido em executions
npx sdk-commands scene-insights logs --execution EXECUTION_ID --from 1d
```

`logs` mostra por predefinição a última hora e as 100 linhas correspondentes mais recentes, por ordem cronológica. A CLI aceita `--limit` entre 1 e 10 000 e obtém várias páginas da API, conforme necessário. `--level` define uma gravidade mínima (`warn` inclui erros); `--query` pesquisa texto literal sem distinguir maiúsculas de minúsculas em ASCII. Use `--source scene,engine,stderr` para selecionar as origens dos logs, ou indique um subconjunto destas origens.

`executionId` identifica uma execução do Server; `entityId` identifica a versão implementada da Scene. Uma nova execução pode indicar uma paragem e um arranque após um período de inatividade, uma atualização ou uma falha. Verifique os logs em torno do momento antes de concluir que ocorreu uma falha.

Adicione `--json` para saída legível por máquina. A CLI devolve os registos históricos num único documento JSON; o campo `more: true` indica que existem mais correspondências além do limite devolvido. Reduza o intervalo ou aumente o limite. Os clientes da API direta recebem até 1.000 linhas por página e usam um cursor para a paginação.

## Acompanhar registos em tempo real

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

Prima **Ctrl+C** para parar. Para uma captura com duração limitada, incluindo quando pedir a um assistente de IA que investigue:

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

Este comando reproduz as 20 linhas mais recentes e, em seguida, acompanha as novas durante 30 segundos. A saída JSON contém uma entrada de registo por linha. A CLI volta a ligar-se e retoma o acompanhamento enquanto este está em execução. Normalmente, os registos chegam alguns segundos depois de a cena os escrever.

`tail` permite filtrar por nível e texto. Para intervalos históricos ou filtros por execução/origem, use `logs`.

Se usar `npm run server-logs`, confirme que o `package.json` do seu projeto contém:

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

As compilações completas do projeto com o SDK atualizado criam ou migram o script predefinido gerado pelo SDK. Os scripts personalizados são preservados; as pré-visualizações com `--skip-build` e as compilações de ficheiro único não o atualizam. Pode editar o script diretamente, sem voltar a compilar, apenas para inspecionar os registos.

## Inspecionar métricas de desempenho

Primeiro, liste as métricas que têm dados e, em seguida, consulte uma série:

```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` define o tamanho do intervalo, em segundos. As métricas disponíveis dependem da versão do engine e da atividade da cena. A descoberta de métricas e `executions` usam as últimas 24 horas por predefinição. Use `--execution EXECUTION_ID` numa série de métricas para isolar uma execução.

| Métrica                                                 | O que indica                                                                                                                                             |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cpu.percent`                                           | Utilização da CPU da thread de execução, expressa como percentagem de um núcleo; valores persistentes próximos de 100% sugerem que a thread está ocupada |
| `cpu.run_ms`                                            | Tempo de CPU gasto em `onStart`/`onUpdate`, não a latência de relógio                                                                                    |
| `mem.heap_used`, `mem.heap_limit`, `mem.external_bytes` | Utilização do heap de JavaScript, limite máximo do heap e memória externa do V8                                                                          |
| `logs.lines`, `logs.bytes`                              | Saída da consola antes dos limites de frequência; útil para detetar registos excessivos                                                                  |
| `fetch.failed`, `storage.failed`                        | Erros ao enviar solicitações de chamadas HTTP ou de armazenamento de saída; correlacione-os com os registos de erros                                     |
| `fetch.status_4xx`, `fetch.status_5xx`                  | Respostas de erro HTTP; estas não são contabilizadas como `fetch.failed`                                                                                 |
| `logs.dropped`                                          | Linhas descartadas pelo limite de registos por ciclo do motor                                                                                            |
| `comms.msgs_out`, `comms.bytes_out`                     | Mensagens e bytes enviados aos jogadores                                                                                                                 |

As métricas de CPU não medem o servidor inteiro, e as métricas de memória não correspondem à memória total do processo nem ao limite do contentor. Compare a mesma execução, janela temporal e carga de trabalho antes de diagnosticar uma fuga de memória ou um problema de desempenho.

Os indicadores devolvem `avg` e `max` por intervalo. As somas devolvem `sum` e uma `rate`por segundo. Um ponto `null` significa que não há amostra armazenada, e não que a utilização é zero; cenas inativas, atrasos e falhas de recolha podem causar lacunas.

## Retenção e limites

| Limite                                     | Predefinição                                                                                 |
| ------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Retenção de registos e métricas            | 7 dias                                                                                       |
| Intervalo máximo da consulta               | 7 dias                                                                                       |
| Resultados de registos por consulta da CLI | 100 por predefinição; até 10 000 com paginação                                               |
| Série de métricas                          | Até 1 500 intervalos; aumente `--step` para períodos mais longos                             |
| Registo contínuo da cena                   | 50 linhas/segundo e 64 KiB/segundo                                                           |
| Margem para picos de registo               | 500 linhas e 512 KiB                                                                         |
| Quota diária de registos da cena           | Limite flexível de 500 000 linhas ou 128 MiB por processo do servidor; repõe-se às 00:00 UTC |

Os contadores da quota diária são mantidos na memória. O reinício de um processo do servidor ou a transferência de uma cena para outra réplica também repõe os respetivos contadores; por isso, a quota diária é um limite aproximado quando ocorrem estas alterações.

Os limites de taxa e as quotas diárias descartam os registos excedentes; as linhas descartadas não podem ser recuperadas posteriormente. As mensagens de aviso do motor indicam os descartes e as reposições das quotas. Ao atingir a quota diária, a persistência de registos adicionais é interrompida até à reposição; a cena continua em execução. Reduza o registo repetido a cada fotograma para que as mensagens úteis caibam no limite.

O motor também tem um limite de registos separado por ciclo (1 000 linhas por predefinição); as linhas excedentes são descartadas antes da exportação e contabilizadas em `logs.dropped`.

As mensagens grandes podem ser truncadas (a API usa 8 192 caracteres por mensagem por predefinição). A recolha é feita segundo o melhor esforço: indisponibilidades, falhas de exportação e limites de taxa podem causar lacunas. Só estão disponíveis os dados de telemetria recolhidos; instalar a nova CLI não permite recuperar dados mais antigos ou descartados. Resultados vazios, por si só, não provam que uma cena esteja a funcionar corretamente.


---

# 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-pt/scenes-sdk7/depuracao/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.
