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.

Clasificación y retención

@ErrorTipo = 1 representa un error técnico o funcional que requiere atención. Debe conservarse en el log técnico principal con el diagnóstico y ReplaySql.
@ErrorTipo = 2 representa una advertencia o resultado controlado, por ejemplo un código postal inexistente. No debe escribirse en el log técnico principal.
Las advertencias controladas se registran en archivos diarios log/controlled/controlled-AAAA-MM-DD.log.
Los archivos controlados conservan exactamente tres días calendario: el actual y los dos anteriores. Los más antiguos se eliminan automáticamente al escribir el siguiente evento.
El log controlado es compacto: fecha, origen, procedimiento, URL, mensaje amigable y tipo de excepción. No incluye stack trace completo, parámetros ni ReplaySql.
Un throw deliberadamente controlado debe usar ControlledApplicationException; el clasificador no debe convertir excepciones técnicas genéricas en eventos controlados.
Si @ErrorTipo es 0 pero @Return es falso, tratarlo como incumplimiento del contrato y enviarlo al log principal.

Alcance

Registrar parámetros detallados y ReplaySql únicamente para @ErrorTipo = 1 o fallas técnicas; las advertencias controladas usan el registro compacto sin parámetros.
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.

4.1 KiB Raw Permalink Blame History Unescape Escape