Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.
Acceso y uso de los registros de desarrolladores de Amazon Q
Amazon Q Developer genera registros detallados que pueden ayudarle a diagnosticar y resolver problemas. Esta guía le muestra cómo acceder a los registros de las distintas interfaces de Amazon Q y cómo configurar los niveles de registro para obtener la información que necesita para solucionar problemas.
Navegación rápida:
Descripción general del acceso a los registros
Existen dos formas principales de acceder a los registros de Amazon Q Developer, según cómo utilices el servicio:
-
Extensiones IDE: VS Code y JetBrains IDEs tienen un botón «Mostrar registros» para acceder a los registros específicos de Amazon Q
-
Interfaz de línea de comandos (Amazon Q CLI): los registros se almacenan localmente en directorios temporales con niveles de detalle configurables
importante
Los archivos de registro pueden contener información confidencial de sus conversaciones e interacciones con Amazon Q, incluidas rutas de archivos, fragmentos de código, resultados de comandos y nombres de cuentas IDs y recursos. Tenga cuidado al compartir archivos de registro con otras personas.
Registros de extensiones IDE
Acceso a los registros a través de la interfaz IDE
-
Abre el panel de chat de Amazon Q en tu IDE (VS Code o JetBrains)
-
Haga clic en el botón Mostrar registros en la esquina superior derecha del panel de chat
-
Reconozca la advertencia de sensibilidad que aparece
-
La ubicación del archivo de registro se abrirá en el administrador de archivos del sistema para su revisión
Analizando los registros de extensiones IDE
Al revisar los registros de extensiones del IDE, busque:
-
Mensajes de error: las líneas que contienen las palabras «ERROR» o «FATAL» indican problemas críticos
-
Problemas de autenticación: busque errores de autenticación o relacionados con las credenciales
-
Conectividad de red: tiempos de espera de conexión o errores relacionados con la red
-
Errores específicos de las funciones: problemas relacionados con las sugerencias de código, el chat u otras funciones específicas
Registros de la CLI de Amazon Q
La CLI de Amazon Q genera automáticamente registros completos para todas las operaciones, independientemente de la configuración de verbosidad. Los registros siempre se escriben en los archivos, mientras que los indicadores de verbosidad solo controlan lo que aparece en la salida del terminal.
Ubicaciones y archivos de registro de Amazon Q CLI
Los registros de la CLI de Amazon Q se almacenan automáticamente en las siguientes ubicaciones:
| Sistema operativo | Ubicación del registro |
|---|---|
| macOS | $TMPDIR/qlog/(normalmente/var/folders/.../qlog/) |
| Linux/WSL | $XDG_RUNTIME_DIR/qlog/ o $TMPDIR/qlog/ o /tmp/qlog/ |
| Windows | %TEMP%\qlog\ |
La CLI de Amazon Q crea automáticamente varios archivos de registro especializados:
chat.log- Los principales registros envoltorios de Amazon Q CLI incluyen:-
Operaciones de inicialización e inicio de Amazon Q CLI
Llamadas al SDK de AWS (Cognito Identity, flujos de autenticación)
Operaciones de red (conexiones HTTP/TLS, gestión de certificados)
Operaciones del sistema de bajo nivel (telemetría, conexiones por socket)
Resolución de puntos finales de servicios de AWS y agrupación de conexiones
Información de depuración detallada de los componentes de la infraestructura
qchat.log- Registros específicos de la aplicación de chat, que incluyen:-
Errores de la aplicación de chat y problemas de procesamiento de estados
Errores de conexión y administración del servidor MCP (Model Context Protocol)
Problemas de migración a nivel de aplicación
Interrupciones en la interacción del usuario y errores en el procesamiento del chat
Errores de lógica de aplicaciones de nivel superior
mcp.log- Registros del servidor Model Context Protocol (rellenados cuando se utilizan servidores MCP)translate.log- Registros de traducción de lenguaje natural a shell (se rellenan cuando se utiliza la función de traducción)
Diferencias clave entre los archivos de registro
Diferencias de alcance y detalle:
chat.log: Registro integral a nivel de sistema que cubre toda la infraestructura de Q CLIqchat.log: Registro centrado a nivel de aplicación específico para la funcionalidad de chat
Diferencias en el enfoque del contenido:
chat.log: componentes internos del SDK de AWS, protocolos de red, flujos de autenticación y operaciones del sistemaqchat.log: lógica de chat, ciclo de vida del servidor MCP, problemas con la experiencia del usuario, errores de aplicación
nota
Los archivos de registro se almacenan únicamente en su máquina local y no se envían a AWS ella. Todos los archivos de registro se crean automáticamente la primera vez que utiliza la CLI, incluso sin indicadores detallados.
Flujo de trabajo de solución de problemas de Amazon Q CLI
Siga este enfoque para recopilar información de diagnóstico de los registros.
-
Identifique el directorio de registro de su sistema:
En Linux/WSL:
echo $XDG_RUNTIME_DIR/qlog/En macOS:
echo $TMPDIR/qlog/En Windows:
echo %TEMP%\qlog\ -
Ejecute el comando Amazon Q CLI con la máxima verbosidad para ver el resultado detallado en su terminal:
q -vvv chat -
Reproduzca el problema que está experimentando
-
Cierre la CLI de Amazon Q y examine los archivos de registro correspondientes. Para la mayoría de los problemas, compruebe los dos archivos de registro principales:
En macOS/Linux:
less -r $XDG_RUNTIME_DIR/qlog/qchat.log less -r $XDG_RUNTIME_DIR/qlog/chat.logAlternativa en macOS:
less -r $TMPDIR/qlog/qchat.log less -r $TMPDIR/qlog/chat.logEn Windows:
type %TEMP%\qlog\qchat.log type %TEMP%\qlog\chat.log -
Para monitorear los registros en tiempo real durante la resolución de problemas, usa:
Supervise todos los archivos de registro simultáneamente:
tail -f $XDG_RUNTIME_DIR/qlog/*.logSupervise archivos específicos:
tail -f $XDG_RUNTIME_DIR/qlog/qchat.logtail -f $XDG_RUNTIME_DIR/qlog/chat.log
Análisis de los registros de Amazon Q CLI
Los registros de Amazon Q CLI utilizan niveles de registro estándar para clasificar la información por importancia:
- ERROR
Problemas críticos que impiden el funcionamiento normal: comience aquí para solucionar problemas
- WARN
Posibles problemas que no interrumpen la funcionalidad, pero que deben tenerse en cuenta
- INFO
Mensajes operativos generales sobre lo que está haciendo la aplicación
- DEBUG
Información técnica detallada útil para una investigación más profunda
Al examinar los registros de Amazon Q CLI, concéntrese en estas áreas clave de los distintos archivos de registro:
qchat.loganálisis: problemas a nivel de aplicación, que incluyen:-
ERROR chat_cli: :cli: :chat: errores en el procesamiento del chat y la administración del estado
ERROR chat_cli: :cli: :agent - Problemas de migración y relacionados con el agente
ERROR chat_cli: :telemetry - Fallos de validación y transmisión de la telemetría
chat.loganálisis: detalles operativos del tiempo de ejecución que incluyen:-
DEBUG q_cli: :cli - Ejecución e inicialización de comandos de Amazon Q CLI
DEBUG aws_sdk_* - Operaciones y llamadas de servicio del SDK de AWS
DEBUG rustls: :* - establecimiento de la conexión y gestión de certificados TLS/SSL
DEBUG hyper_*: administración de conexiones HTTP y operaciones de red
ERROR fig_telemetry: problemas de telemetría del sistema y de conexión de sockets
Consejos de análisis generales:
-
Marcas de tiempo: correlaciona las entradas del registro con el momento en que se produjeron los problemas
-
Patrones de error: busque errores repetidos o cascadas de errores
-
Solicitud IDs: realiza un seguimiento de las llamadas a la API específicas y sus resultados
-
Estados de conexión: supervise la conectividad de la red y el estado de autenticación
sugerencia
Utilice herramientas como grep editores de texto o editores de texto con función de búsqueda para filtrar los registros en busca de mensajes o patrones de error específicos. awk Por ejemplo: grep -i error $XDG_RUNTIME_DIR/qlog/*.log
Patrones y soluciones de registro comunes
Estos son algunos de los problemas más comunes que se pueden encontrar en los registros y sus soluciones habituales:
- Errores de conexión al servidor MCP
-
Patrón de registro (en qchat.log): «Hilo de escucha en segundo plano para el cliente [nombre del servidor]: RecvError (cerrado)» o «Se descartan todos los remitentes para la capa de transporte»
Solución: los procesos del servidor MCP han dejado de ejecutarse. Normalmente, este es el comportamiento esperado al salir de la CLI de Amazon Q o cuando los servidores se apagan normalmente.
- Interrupciones en el procesamiento del chat
-
Patrón de registro (en qchat.log): «Se ha producido un error al procesar el estado actual ERR=interrupted {tool_uses: None}»
Solución: esto ocurre cuando el usuario cancela las operaciones de chat (p. ej., Ctrl+C) y es el comportamiento esperado.
- Errores de validación de telemetría
-
Patrón de registro (en qchat.log): «No se pudo enviar el evento de telemetría cw err= ValidationError [ValidationException]: solicitud mal formada»
Solución: Por lo general, se trata de problemas de transmisión de telemetría no críticos que no afectan a las funciones principales.
- Advertencias de migración
-
Patrón de registro (en qchat.log): «La migración no se produjo por el siguiente motivo: se abortó la migración»
Solución: normalmente se trata de una advertencia no crítica relacionada con la migración de la configuración y, por lo general, se puede ignorar.
- Errores de autenticación
-
Patrón de registro (en chat.log): errores relacionados con la autenticación en las operaciones del SDK de AWS
Solución: ejecute q login para volver a autenticar o comprobar sus credenciales de AWS
- Problemas de conectividad de red
-
Patrón de registro (en chat.log): «Se ha agotado el tiempo de espera de la conexión», «No se puede acceder a la red» o se ha producido un error en las conexiones HTTP
Solución: compruebe la configuración de su conexión a Internet y del firewall
- Fallos de funcionamiento del SDK de AWS
-
Patrón de registro (en chat.log): errores en las operaciones de Cognito Identity o en la recuperación de credenciales
Solución: compruebe sus credenciales de AWS y la conectividad de red. Es posible que sea necesario volver a autenticarse
Obtener ayuda con el análisis de registros
Si necesita ayuda para analizar los registros o resolver problemas:
-
Cuando te pongas en contacto con el servicio de asistencia, incluye los extractos de registro pertinentes (eliminando la información confidencial)
-
Proporcione un contexto sobre cuándo se produce el problema y los pasos para reproducirlo
