Plataforma-de-desarrolladores/AGENTS_DATABASE_ERROR_LOGGING.md

Reglas obligatorias para registrar errores de base de datos

Estas reglas complementan AGENTS.md, AGENTS_STORED_PROCEDURES.md y AGENTS_DATA_READER_MAPPING.md.

Información requerida

Cuando falle una llamada a un procedimiento almacenado, el log técnico debe incluir:

• Nombre completo del procedimiento, incluyendo esquema.
• Nombre de cada parámetro.
• Valor recibido por cada parámetro de entrada.
• Tipo y valor disponible de los parámetros de salida.
• Mensaje y número de la excepción SQL.
• Un bloque ReplaySql que pueda copiarse en SQL Server para reproducir la llamada.

Formato mínimo:

StoredProcedure: dbo.PA_Modulo_Accion
Parametros:
@CveProyecto=-1
@CvePeriodo=0
@EsSimulador=0
ReplaySql:
DECLARE @ErrorMostrar varchar(max);
DECLARE @ErrorTipo int;
DECLARE @Return bit;
EXEC [dbo].[PA_Modulo_Accion]
    @CveProyecto = -1,
    @CvePeriodo = 0,
    @EsSimulador = 0,
    @ErrorMostrar = @ErrorMostrar OUTPUT,
    @ErrorTipo = @ErrorTipo OUTPUT,
    @Return = @Return OUTPUT;
SELECT @ErrorMostrar, @ErrorTipo, @Return;

Seguridad

• Nunca registrar valores de contraseñas, hashes, tokens, secretos, API keys ni cadenas de conexión.
• Sustituir esos valores con [REDACTADO] tanto en Parametros como en ReplaySql.
• El SQL reproducible con valores redactados requiere que el desarrollador proporcione manualmente un valor seguro de prueba.
• Escapar comillas simples y generar literales SQL válidos.
• Limitar textos extensos y marcar el valor como truncado.
• No mostrar ReplaySql, parámetros ni detalles técnicos al usuario final.
• Los datos técnicos sólo deben escribirse en el archivo log protegido de la aplicación.

Implementación

• Configurar todos los comandos mediante StoredProcedureCommand para que StoredProcedureDiagnostics capture el contexto.
• DbExecutor debe adjuntar el diagnóstico al log en SqlException, timeout, error de salida del PA y excepciones inesperadas.
• Limpiar el contexto de diagnóstico en finally para impedir que parámetros de una petición aparezcan en otra.
• Usar AsyncLocal para aislar correctamente solicitudes concurrentes y operaciones asíncronas.
• Capturar los parámetros OUTPUT después de cerrar el DataReader.
• No establecer SqlConnection.FireInfoMessageEventOnUserErrors = true; esa opción transforma errores SQL de severidad 11–16 en eventos informativos y puede ocultar la excepción real.
• Los mensajes RAISERROR de severidad 10 pueden registrarse mediante SqlConnection.InfoMessage sin activar esa opción.
• Si @Return, @ErrorTipo y @ErrorMostrar regresan sin valor, registrar que la versión instalada del PA no devolvió el contrato requerido.

Alcance

• Registrar parámetros detallados sólo cuando exista un error o advertencia que requiera diagnóstico.
• No registrar cada ejecución exitosa de manera predeterminada.
• No usar el log como auditoría de operaciones exitosas; la auditoría pertenece a su propio contrato o procedimiento.