Progreso Sentry Helper

Un helper robusto para el registro de errores con soporte para Sentry y API personalizada de errores. Incluye fallback automático, manejo asíncrono de errores y configuración flexible.

Características

• ✅ Soporte para Sentry.io
• ✅ Soporte para API personalizada de errores
• ✅ Fallback automático entre sistemas
• ✅ Manejo asíncrono para no bloquear la aplicación
• ✅ Configuración flexible vía código o appsettings.json
• ✅ Logging en consola opcional
• ✅ Mapeo automático de ambientes
• ✅ Serialización inteligente de datos de excepción

Instalación

Desde NuGet Lilab

dotnet add package Progreso.SentryHelper --version 1.0.0 --source http://nuget.lilab.pe/v3/index.json

Publicar nueva versión en Lilab

PowerShell:

.\publish-lilab.ps1 -Version "1.0.1"

Batch (CMD):

publish-lilab.bat 1.0.1

Manual:

# Empaquetar
dotnet pack ProgresoSentryHelper.csproj --configuration Release /p:PackageVersion=1.0.0

# Publicar
dotnet nuget push -s http://nuget.lilab.pe/v3/index.json .\bin\Release\Progreso.SentryHelper.1.0.0.nupkg -k lilab66#

Configuración en el proyecto

1. Agregar el paquete al proyecto:

<PackageReference Include="Progreso.SentryHelper" Version="1.0.0" />

Uso

Configuración básica

Opción 1: Configuración por código

using Progreso.SentryHelper;

// En el Startup.cs o Program.cs
var config = new SentryHelperConfiguration
{
    EnableSentry = true,
    SentryDsn = "https://your-sentry-dsn@sentry.io/project-id",
    EnableCustomApi = true,
    CustomApiUrl = "https://api.example.com/errors",
    Environment = "Production",
    ApplicationName = "MiAplicacion",
    ApplicationVersion = "1.0.0",
    LogToConsole = true,
    UseSentryAsFallback = true
};

SentryHelper.Initialize(config);

Opción 2: Configuración vía appsettings.json

{
  "SentryHelper": {
    "EnableSentry": true,
    "SentryDsn": "https://your-sentry-dsn@sentry.io/project-id",
    "EnableCustomApi": true,
    "CustomApiUrl": "https://api.example.com/errors",
    "ApiTimeout": 3,
    "Environment": "Production",
    "ApplicationName": "MiAplicacion",
    "ApplicationVersion": "1.0.0",
    "LogToConsole": true,
    "UseSentryAsFallback": true,
    "TracesSampleRate": 0.1
  }
}

// En Startup.cs
public void ConfigureServices(IServiceCollection services)
{
    // Usar extensión para configurar desde appsettings
    services.AddSentryHelper(Configuration);
    
    // O con configuración adicional
    services.AddSentryHelper(Configuration, config =>
    {
        config.Debug = true;
        config.UserId = GetCurrentUserId();
    });
}

Registro de errores

try
{
    // Tu código aquí
    DoSomething();
}
catch (Exception ex)
{
    // Registrar la excepción
    SentryHelper.LogException(ex);
    
    // O con datos adicionales
    var additionalData = new Dictionary<string, string>
    {
        ["UserId"] = currentUser.Id,
        ["Operation"] = "ProcessPayment",
        ["Amount"] = amount.ToString()
    };
    SentryHelper.LogException(ex, additionalData);
}

Registro de mensajes

// Mensaje informativo
SentryHelper.LogMessage("Proceso completado exitosamente");

// Mensaje de advertencia
SentryHelper.LogMessage("Memoria baja detectada", SentryLevel.Warning);

// Mensaje de error
SentryHelper.LogMessage("Fallo en la conexión a la base de datos", SentryLevel.Error);

Migración desde código existente

Si estás migrando desde el código Helper existente:

// Código anterior
Helper.logSentryIO(exception);

// Nuevo código
SentryHelper.LogException(exception);

Configuración avanzada

Ambientes

El helper mapea automáticamente los ambientes:

• Development, Debug, Local → DEVELOPMENT
• Test, Stage, Staging → STAGING
• Cualquier otro → PRODUCTION

Formato del API personalizado

El helper envía los errores al API personalizado en el siguiente formato:

{
  "type": "ERROR",
  "message": "Error message",
  "environment": "PRODUCTION",
  "userAgent": "MiApp/1.0.0",
  "url": "https://api.example.com",
  "userId": "user123",
  "stackTrace": "...",
  "metadata": {
    "exceptionType": "System.NullReferenceException",
    "source": "MyApp.Services",
    "innerException": "...",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "machineName": "SERVER01",
    "version": "1.0.0",
    "data": {},
    "additionalData": {}
  }
}

Opciones de configuración

Mejores prácticas

1. Inicialización temprana: Inicializa el helper lo antes posible en el ciclo de vida de la aplicación.

2. Manejo de recursos: Llama a SentryHelper.Dispose() al cerrar la aplicación:

   public void OnApplicationStopping()
   {
       SentryHelper.Dispose();
   }
   

3. Datos sensibles: No incluyas información sensible (contraseñas, tokens) en los datos adicionales.

4. Ambientes: Configura correctamente el ambiente para facilitar el filtrado en Sentry.

5. Versionado: Mantén actualizada la versión de la aplicación para mejor trazabilidad.

Solución de problemas

El API personalizado no recibe errores

• Verifica que EnableCustomApi esté en true
• Confirma que CustomApiUrl sea correcto
• Revisa los logs de consola si LogToConsole está habilitado
• Verifica el timeout configurado

Sentry no recibe eventos

• Verifica que EnableSentry esté en true
• Confirma que el DSN sea correcto
• Verifica la conectividad de red

Performance

• Si experimentas lentitud, reduce ApiTimeout
• Considera deshabilitar LogToConsole en producción
• Ajusta TracesSampleRate según necesidad

Licencia

MIT

Soporte

Para soporte, contacta al equipo de desarrollo de Progreso.