64 lines
2.9 KiB
Markdown
64 lines
2.9 KiB
Markdown
# 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:
|
||
|
||
```text
|
||
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.
|