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

# Scene Insights

Buscar logs persistentes del Multiplayer Server, seguir logs en vivo e inspeccionar las métricas de rendimiento de la escena.

Scene Insights te ayuda a investigar una [Multiplayer Server](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/networking/authoritative-servers.md) scene implementada. Busca registros históricos del servidor, sigue los mensajes nuevos en tiempo real y consulta métricas de CPU, memoria y otras desde tu terminal o asistente de IA.

**Los registros y las métricas se conservan durante 7 días**, incluso después de reiniciar el servidor o volver a implementar la scene. Esto cubre la ejecución del lado del servidor; para problemas del lado del cliente y de renderizado, usa [Debug in Production](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/depuracion/debug-in-prod.md) .

## Actualiza tu proyecto

Ejecuta estos comandos desde el proyecto de tu scene para instalar la versión más reciente del `auth-server` SDK y el runtime:

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

Si tu proyecto también incluye `@dcl/sdk-commands` directamente en `package.json`, actualízalo también a `@auth-server` . Comprueba que el CLI instalado incluya `login`, `logs`, `tail`, `metrics`, y `executions`:

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

Para depurar con ayuda de IA, instala o actualiza también [SDK Skills](https://docs.decentraland.org/creator/content-creator-es/scenes-sdk7/primeros-pasos/vibe-coding.md):

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

Puedes pedirle a tu asistente de IA que realice la configuración:

> Actualiza esta scene a la versión más reciente del SDK y el runtime auth-server, y actualiza Decentraland SDK Skills. Ayúdame a iniciar sesión en Scene Insights y luego investiga los errores del servidor y el uso de CPU y memoria de las últimas dos horas.

Consultar la telemetría de una scene que ya está implementada no requiere volver a implementarla. Los cambios de permisos sí.

## ¿Quién puede leer los datos?

Inicia sesión con una wallet que cumpla una de estas condiciones:

* Aparece en el array `logsPermissions` del nivel raíz de la scene implementada.
* Es propietaria del World.
* Es colaboradora de implementación del World y su autorización abarca todo el World o cada parcela implementada de la scene.
* En Genesis City, es propietaria de la **parcela base**de la scene, o tiene permisos delegados para administrar LAND en esa parcela: `operator`, `updateOperator`, `updateManager`, o `approvedForAll`.

Los propietarios y los administradores autorizados no necesitan una entrada en `logsPermissions` ni volver a implementar la scene. Para conceder acceso explícitamente a otra wallet, añádela a `scene.json` y vuelve a desplegar:

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

En Genesis City, el permiso se comprueba en función de la parcela base de la escena desplegada, aunque consultes otra parcela dentro de la escena. Tener derechos de propiedad o gestión sobre otra parcela no otorga por sí solo acceso a la escena.

Los mismos permisos se aplican a los registros históricos, los registros en directo, las métricas y el historial de ejecuciones. El acceso se rige por los **permisos actuales**: cualquier persona autorizada en ese momento puede leer todo el historial conservado durante un máximo de 7 días bajo la misma clave de escena, incluidos los registros escritos mientras otra persona tenía desplegada la escena. Esto incluye a nuevos propietarios, operadores, arrendatarios que cumplan los requisitos y wallets que se hayan añadido recientemente a `logsPermissions`. Ten en cuenta ese historial antes de conceder acceso.

Los cambios de permisos no son inmediatos. De forma predeterminada, las cachés de permisos duran 60 segundos y los flujos en directo abiertos vuelven a comprobar el acceso cada 5 minutos. Calcula unos 6 minutos para que un flujo abierto detecte la revocación. Estos son los tiempos predeterminados, no un plazo estricto: la configuración y los períodos de gracia limitados durante fallos temporales de capacidad pueden prolongar la demora. Iniciar sesión no concede permiso para leer otras escenas.

## Iniciar sesión

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

Aprueba el inicio de sesión en tu navegador con una wallet normal o una wallet de contrato inteligente. Esto crea una sesión de Insights que solo permite leer registros, métricas y ejecuciones. Dura hasta **12 horas**, sin superar la fecha de expiración de la sesión principal. Los comandos posteriores reutilizan esa sesión sin necesidad de otra aprobación.

Comprueba la dirección con la sesión iniciada y su fecha de expiración con:

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

Cuando la sesión expire, ejecuta `login` de nuevo. Si un asistente de IA está investigando por ti, aprueba tú mismo el inicio de sesión de la wallet. No compartas con él las claves privadas ni el archivo de sesión almacenado en caché.

### Mantén la privacidad del archivo de sesión

{% hint style="warning" %}
**Nunca subas, despliegues ni compartas tu archivo de sesión de inicio de sesión.** De forma predeterminada, se guarda en `~/.dcl/scene-insights-session.json`. Contiene una clave de firma privada temporal y la delegación de solo lectura de tu wallet. Cualquier persona que tenga una copia puede usar esas credenciales para leer los registros, las métricas y el historial de ejecuciones de las escenas a las que tu wallet tenga acceso, hasta que expire la sesión. No lo envíes a compañeros de equipo, asistentes de IA, chats de soporte ni informes públicos de incidencias, ni lo incluyas en archivos del proyecto.
{% endhint %}

El SDK lo protege automáticamente:

* De forma predeterminada, guarda el archivo en tu directorio personal, fuera del proyecto de la escena. Si configuras `DCL_SCENE_INSIGHTS_SESSION_DIR`, usa en su lugar la carpeta `.dcl` de ese directorio.
* Añade `*` a `.gitignore` de la carpeta de sesión y se niega a guardar o usar un archivo de sesión que Git ya esté siguiendo.
* Escribe el archivo de sesión con permisos exclusivos para el propietario (`0600`) y crea su carpeta con permisos `0700` en los sistemas que los admiten.
* El recopilador estándar de archivos de despliegue del SDK excluye los archivos y directorios cuyo nombre comienza con un punto, incluido `.dcl`, independientemente de `.dclignore`.

Ten en cuenta estas comprobaciones:

* Revisa los archivos preparados antes de confirmar los cambios. No fuerces la inclusión del archivo de sesión; `.gitignore` no protege los archivos que Git ya está siguiendo.
* Si personalizas la ubicación de la sesión, procura mantenerla fuera del proyecto de la escena. Nunca copies ni cambies el nombre de la sesión para colocarla entre los recursos de la escena o en otra carpeta que pueda desplegarse.
* Si usas scripts personalizados de despliegue, copia de seguridad o ZIP, excluye explícitamente el archivo de sesión y las credenciales de `.dcl` ; es posible que esas herramientas no apliquen las exclusiones del SDK.
* Cuando sea necesario, comparte solo la salida de estado segura de `npx sdk-commands scene-insights session --json` , nunca el archivo de sesión. Los compañeros de equipo deben iniciar sesión con sus propias wallets autorizadas.

`npx sdk-commands scene-insights logout` elimina la sesión guardada localmente. No **revoca** las copias que ya se hayan compartido: esas credenciales pueden seguir siendo válidas hasta que caduquen. Si el archivo quedó expuesto, elimínalo de los artefactos compartidos y del historial de Git, según corresponda; borrar el archivo local o volver a iniciar sesión no invalida la copia expuesta.

## Elegir una Scene

A partir del proyecto de la Scene, los comandos infieren el World desde `scene.json`’s `worldConfiguration.name`, o usan `scene.base` para Genesis City. También puedes elegirlo explícitamente:

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

# Una Scene en un World con varias Scenes
npx sdk-commands scene-insights logs --world myworld.dcl.eth --position 10,10

# Una Scene de Genesis City: usa = cuando las coordenadas sean negativas
npx sdk-commands scene-insights logs --position=-125,-96
```

De forma predeterminada, los comandos usan producción (`.org`). Para una Scene en la red de desarrollo, añade `--target https://multiplayer-scenes-insights-service.decentraland.zone` al inicio de sesión, a las comprobaciones de sesión y a las consultas. Usar el mismo destino en todos los casos también garantiza que las wallets de Smart Contracts se validen en la red correcta.

## Buscar Logs y ejecuciones

```bash
# Los 200 errores más recientes de las últimas 6 horas
npx sdk-commands scene-insights logs --from 6h --level error --limit 200

# Buscar texto en un intervalo de tiempo fijo en UTC
npx sdk-commands scene-insights logs --from 2026-11-01T14:00:00Z --to 2026-11-01T14:30:00Z --query "player joined"

# Listar las ejecuciones del servidor del último día
npx sdk-commands scene-insights executions --from 1d

# Logs de una ejecución: sustituye EXECUTION_ID por un ID de executions
npx sdk-commands scene-insights logs --execution EXECUTION_ID --from 1d
```

`logs` usa por defecto la última hora y las 100 líneas coincidentes más recientes, mostradas en orden cronológico. La CLI acepta `--limit` entre 1 y 10 000 y obtiene varias páginas de la API según sea necesario. `--level` es un nivel mínimo de gravedad (`warn` incluye los errores); `--query` busca texto literal sin distinguir entre mayúsculas y minúsculas ASCII. Usa `--source scene,engine,stderr` para seleccionar los orígenes de los Logs, o indica un subconjunto de estas fuentes.

`executionId` identifica una ejecución del servidor; `entityId` identifica la versión implementada de la Scene. Una nueva ejecución puede deberse a una parada y un reinicio por inactividad, a un despliegue o a un fallo. Revisa los Logs circundantes antes de concluir que se produjo un fallo.

Añade `--json` para la salida legible por máquinas. La CLI devuelve los registros históricos como un único documento JSON; su `more: true` indica que hay más coincidencias además del límite devuelto. Reduce el intervalo o aumenta el límite. Los clientes de API directos reciben hasta 1.000 filas por página y usan un cursor para la paginación.

## Seguir registros en tiempo real

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

Pulsa **Ctrl+C** para detenerlo. Para capturar un intervalo limitado, también al pedirle a un asistente de IA que investigue:

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

Esto reproduce las 20 líneas más recientes y, después, sigue las nuevas durante 30 segundos. La salida JSON contiene una entrada de registro por línea. La CLI se vuelve a conectar y reanuda la captura mientras se ejecuta el seguimiento. Los registros suelen llegar unos segundos después de que la escena los escriba.

`tail` admite filtros por nivel y texto. Para consultar intervalos históricos o filtrar por ejecución/origen, usa `logs`.

Si usas `npm run server-logs`, comprueba que el `package.json` de tu proyecto contenga:

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

Las compilaciones completas del proyecto con el SDK actualizado crean o migran el script predeterminado generado por el SDK. Los scripts personalizados se conservan; las vistas previas con `--skip-build` y las compilaciones de un solo archivo no lo actualizan. Puedes editar el script directamente sin volver a compilar, solo para inspeccionar los registros.

## Inspeccionar las métricas de rendimiento

Primero, enumera las métricas que tienen datos y, luego, consulta una serie:

```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` establece el tamaño del intervalo en segundos. Las métricas disponibles dependen de la versión del motor y de la actividad de la escena. La búsqueda de métricas y `executions` usan las últimas 24 horas de forma predeterminada. Usa `--execution EXECUTION_ID` en una serie de métricas para aislar una ejecución.

| Métrica                                                 | Qué indica                                                                                                                                             |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `cpu.percent`                                           | Uso de CPU del subproceso de ejecución como porcentaje de un núcleo; los valores sostenidos cercanos al 100 % sugieren que ese subproceso está ocupado |
| `cpu.run_ms`                                            | Tiempo de CPU dedicado a `onStart`/`onUpdate`, no la latencia de tiempo real                                                                           |
| `mem.heap_used`, `mem.heap_limit`, `mem.external_bytes` | Uso del heap de JavaScript, límite máximo del heap y memoria externa de V8                                                                             |
| `logs.lines`, `logs.bytes`                              | Salida de la consola antes de los límites de frecuencia; útil para detectar un exceso de registros                                                     |
| `fetch.failed`, `storage.failed`                        | Errores al enviar solicitudes HTTP salientes o llamadas de almacenamiento; correlaciónalos con los registros de errores                                |
| `fetch.status_4xx`, `fetch.status_5xx`                  | Respuestas de error HTTP; no se cuentan como `fetch.failed`                                                                                            |
| `logs.dropped`                                          | Líneas descartadas por el presupuesto de registros por tick del Engine                                                                                 |
| `comms.msgs_out`, `comms.bytes_out`                     | Mensajes y bytes enviados a los jugadores                                                                                                              |

Las métricas de CPU no miden todo el Server, y las métricas de memoria no representan la memoria total del proceso ni el límite del contenedor. Compara la misma ejecución, el mismo intervalo de tiempo y la misma carga de trabajo antes de diagnosticar una fuga o un problema de rendimiento.

Los indicadores devuelven `avg` y `max` por intervalo. Las sumas devuelven `sum` y una `rate`por segundo. Un punto `null` indica que no hay ninguna muestra almacenada, no un uso de cero; las escenas inactivas, los retrasos y los fallos de recopilación pueden generar intervalos sin datos.

## Retención y límites

| Límite                                         | Predeterminado                                                                                    |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Retención de registros y métricas              | 7 días                                                                                            |
| Intervalo máximo de consulta                   | 7 días                                                                                            |
| Resultados de registros por consulta de la CLI | 100 de forma predeterminada; hasta 10 000 mediante paginación                                     |
| Series de métricas                             | Hasta 1500 intervalos; aumenta `--step` para intervalos más largos                                |
| Registro sostenido de la escena                | 50 líneas/segundo y 64 KiB/segundo                                                                |
| Límite de ráfaga de registros                  | 500 líneas y 512 KiB                                                                              |
| Cuota diaria de registros de la escena         | Límite flexible de 500 000 líneas o 128 MiB por proceso del Server; se restablece a las 00:00 UTC |

Los contadores de la cuota diaria se mantienen en memoria. El reinicio de un proceso del Server o el traslado de una escena a otra réplica también restablece sus contadores, por lo que la cuota diaria es un límite aproximado ante esos cambios.

Los límites de frecuencia y las cuotas diarias descartan los registros que exceden el límite; las líneas descartadas no se pueden recuperar más adelante. Los mensajes de advertencia del Engine informan de los descartes y los restablecimientos de cuotas. Al alcanzar la cuota diaria, se detiene el almacenamiento persistente de registros adicionales hasta el restablecimiento; la escena sigue funcionando. Reduce el registro repetido en cada fotograma para que los mensajes útiles quepan dentro del límite.

El Engine también tiene un presupuesto de registros independiente por tick (1000 líneas de forma predeterminada); las líneas que exceden el límite se descartan antes de la exportación y se contabilizan en `logs.dropped`.

Los mensajes largos pueden truncarse (la API limita de forma predeterminada cada mensaje a 8192 caracteres). La recopilación se realiza según las posibilidades: las interrupciones del servicio, los fallos de exportación y los límites de frecuencia pueden generar intervalos sin datos. Solo están disponibles los datos de telemetría recopilados; instalar la nueva CLI no permite recuperar datos anteriores ni descartados. La ausencia de resultados, por sí sola, no demuestra que una escena funcione correctamente.


---

# 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-es/scenes-sdk7/depuracion/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.
