TraceUp

TraceUp es un sistema independiente de logging de errores que reemplaza Sentry. Envía errores a tu API personalizada con fallback a archivos locales. Incluye manejo asíncrono y configuración flexible.

Características

• ✅ Sistema independiente sin dependencias externas
• ✅ API personalizada para logging de errores
• ✅ Fallback a archivos locales cuando falla el API
• ✅ 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
• ✅ Niveles de log personalizados
• ✅ Log estructurado en JSON

Instalación

Desde NuGet Lilab

dotnet add package TraceUp --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\TraceUp.1.0.0.nupkg -k lilab66#

Configuración en el proyecto

1. Agregar el paquete al proyecto:

<PackageReference Include="TraceUp" Version="1.0.0" />

Uso

Configuración básica

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

using TraceUp;

// En el Startup.cs o Program.cs
var config = new TraceUpConfiguration
{
    EnableCustomApi = true,
    CustomApiUrl = "http://localhost:3001/api/events/your-project-hash",
    Environment = "Production",
    ApplicationName = "MiAplicacion",
    ApplicationVersion = "1.0.0",
    LogToConsole = true,
    EnableLocalFileLog = true,
    LocalLogPath = "./logs"
};

TraceUp.Initialize(config);

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

{
  "TraceUp": {
    "EnableCustomApi": true,
    "CustomApiUrl": "http://localhost:3001/api/events/your-project-hash",
    "ApiTimeout": 3,
    "Environment": "Production",
    "ApplicationName": "MiAplicacion",
    "ApplicationVersion": "1.0.0",
    "LogToConsole": true,
    "EnableLocalFileLog": true,
    "LocalLogPath": "./logs",
    "Debug": false
  }
}

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

Registro de errores

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

Registro de mensajes

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

// Mensaje de advertencia
TraceUp.LogMessage("Memoria baja detectada", TraceUpLevel.Warning);

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

// Mensaje fatal
TraceUp.LogMessage("Sistema crítico no disponible", TraceUpLevel.Fatal);

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
TraceUp.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

TraceUp envía los errores al API en el siguiente formato JSON:

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

Archivos de log locales

Cuando falla el API, TraceUp guarda los errores en archivos JSON locales:

• Ubicación: ./logs/traceup-YYYY-MM-DD.log (configurable)
• Formato: Una línea JSON por error
• Rotación: Un archivo por día

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()
   {
       TraceUp.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
• Revisa los archivos de log locales en LocalLogPath

No se crean archivos de log locales

• Verifica que EnableLocalFileLog esté en true
• Confirma que la ruta LocalLogPath sea escribible
• Revisa los permisos del directorio

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.