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 Amazon Q Developer
Amazon Q Developer genera registros detallados que pueden ayudarle a diagnosticar y solucionar problemas. En esta guía le enseñamos cómo obtener acceso 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:
Información general del acceso a los registros
Hay dos formas principales de acceder a los registros de Amazon Q Developer, en función de cómo se utilice 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 (CLI de Amazon Q): 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 del IDE
Acceso a los registros a través de la interfaz del 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.
-
Confirme la advertencia de confidencialidad que aparece.
-
La ubicación del archivo de registro se abrirá en el administrador de archivos del sistema para su revisión.
Análisis de los registros de extensiones del IDE
Al revisar los registros de extensiones del IDE, busque:
-
Mensajes de error: las líneas que incluyen “ERROR” o “FATAL” indican problemas críticos.
-
Problemas de autenticación: busque errores de autenticación o relacionados con las credenciales.
-
Conectividad de la red: errores de tiempos de espera de conexión o relacionados con la red.
-
Errores específicos de las características: problemas relacionados con las sugerencias de código, el chat u otras características 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 del nivel de detalle. Los registros siempre se escriben en los archivos, mientras que los indicadores de nivel de detalle solo controlan lo que aparece en la salida del terminal.
Ubicaciones y archivos de registros de la CLI de Amazon Q
Los registros de la CLI de Amazon Q se almacenan automáticamente en las siguientes ubicaciones:
| Sistema operativo | Localización de registros |
|---|---|
| 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 registros especializados:
chat.log: registros principales del encapsulador de la CLI de Amazon Q, entre los que se incluyen:-
Operaciones de inicialización e inicio de la CLI de Amazon Q
Llamadas a AWS SDK (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 de socket)
Agrupación de conexiones y resolución de puntos de conexión de servicios de AWS
Información de depuración detallada para componentes de infraestructuras
qchat.log: registros específicos de la aplicación de chat, entre los que se incluyen:-
Errores de la aplicación de chat y problemas de procesamiento de estados
Errores de conexión y administración de servidores del Protocolo de contexto para modelos (MCP)
Problemas de migración de aplicaciones
Interrupciones en la interacción de los usuarios y errores en el procesamiento del chat
Errores de lógica de aplicaciones de nivel superior
mcp.log: registros de servidores del Protocolo de contexto para modelos (se rellenan al utilizar los servidores MCP)translate.log: registros de traducción de lenguaje natural a intérprete de comandos (se rellenan al utilizar la característica de traducción)
Diferencias clave entre los archivos de registros
Diferencias en los detalles y el alcance:
chat.log: registro integral del sistema que cubre toda la infraestructura de la CLI de Qqchat.log: registro centrado en las aplicaciones y específico de la funcionalidad de chat
Diferencias en el enfoque del contenido:
chat.log: componentes internos de AWS SDK, 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 ella AWS. Todos los archivos de registro se crean automáticamente la primera vez que se utiliza la CLI, incluso sin indicadores de detalles.
Flujo de solución de problemas de la CLI de Amazon Q
Siga este método para recopilar información de diagnóstico de los registros.
-
Identifique el directorio de registro del sistema:
En Linux/WSL:
echo $XDG_RUNTIME_DIR/qlog/En macOS:
echo $TMPDIR/qlog/En Windows:
echo %TEMP%\qlog\ -
Ejecute el comando de la CLI de Amazon Q con el máximo detalle para ver el resultado detallado en el terminal:
q -vvv chat -
Reproduzca el problema que está experimentando.
-
Salga de 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.logOpción alternativa 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 supervisar los registros en tiempo real durante la solución de problemas, utilice:
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 la CLI de Amazon Q
Los registros de la CLI de Amazon Q utilizan niveles de registro estándar para clasificar la información según la 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 y útil para una investigación más exhaustiva.
Al examinar los registros de la CLI de Amazon Q, céntrese en estas áreas clave de los distintos archivos de registro:
- Análisis
qchat.log: problemas en las aplicaciones, entre los que se incluyen: -
ERROR chat_cli::cli::chat: errores de administración de estados y procesamiento de chat
ERROR chat_cli::cli::agent: problemas de migración y relacionados con el agente
ERROR chat_cli::telemetry: errores de transmisión y validación de telemetría
- Análisis
chat.log: detalles operativos de tiempo de ejecución, entre los que se incluyen: -
DEBUG q_cli::cli: inicialización y ejecución del comando de la CLI de Amazon Q
DEBUG aws_sdk_*: llamadas de servicio y operaciones de AWS SDK
DEBUG rustls: :* - establecimiento de la TLS/SSL conexión y gestión de certificados
DEBUG hyper_*: operaciones de red y administración de la conexión HTTP
ERROR fig_telemetry: problemas de conexión del socket y telemetría del sistema
Consejos generales sobre análisis:
-
Marcas de tiempo: correlacionar entradas de registros con el momento en que se han producido los problemas.
-
Patrones de error: buscar 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: supervisar la conectividad de la red y el estado de autenticación
sugerencia
Utilice herramientas como grep, awk o editores de texto con la funcionalidad de búsqueda para filtrar registros para patrones o mensajes de error. Por ejemplo: grep -i error $XDG_RUNTIME_DIR/qlog/*.log
Soluciones y patrones de registros frecuentes
A continuación se indican algunos problemas frecuentes que puede encontrar en los registros y sus soluciones habituales:
- Errores de conexión del 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. Este suele ser el comportamiento previsto al salir de la CLI de Amazon Q o cuando los servidores se desactivan normalmente.
- Interrupciones del procesamiento del chat
-
Patrón de registro (en qchat.log): “An error occurred processing the current state err=Interrupted { tool_uses: None }”
Solución: esto ocurre cuando el usuario cancela las operaciones de chat (por ejemplo, Ctrl + C) y es el comportamiento previsto.
- 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 tratan 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): “Migration did not happen for the following reason: Aborting migration”
Solución: por lo general, se trata de una advertencia no crítica relacionada con la migración de la configuración y, normalmente, se puede ignorar.
- Errores de autenticación
-
Patrón de registro (en chat.log): errores relacionados con la autenticación en las operaciones de AWS SDK
Solución: ejecute q login para volver a autenticar o comprobar las credenciales de AWS.
- Problemas de conectividad de red
-
Patrón de registro (en chat.log): “Connection timeout”, “Network unreachable”, o errores en las conexiones HTTP
Solución: compruebe la conexión a Internet y la configuración del firewall.
- Errores de funcionamiento de AWS SDK
-
Patrón de registro (en chat.log): errores de recuperación de credenciales o de operaciones de Cognito Identity
Solución: compruebe las credenciales de AWS y la conectividad de red. Es posible que sea necesario volver a autenticarse.
Obtención de ayuda con el análisis de registros
Si necesita ayuda para analizar los registros o solucionar problemas:
-
Al ponerse en contacto con el servicio de asistencia, incluya los fragmentos de registro pertinentes (sin la información confidencial).
-
Proporcione un contexto sobre cuándo se produce el problema y los pasos para reproducirlo.
