CatchMonitor.SDK 1.0.0

CatchMonitor .NET SDK

Official .NET SDK for CatchMonitor - Comprehensive error monitoring and performance tracking for .NET applications.

Features

• 🚨 Error Tracking - Capture exceptions, messages, and custom events
• 📊 Performance Monitoring - Track transactions, spans, and metrics
• 🍞 Breadcrumbs - Add context to your error tracking
• 👤 User Context - Associate errors with users
• 📎 Attachments - Include files and screenshots with errors
• 🔄 Session Replay - Record user sessions for debugging
• 🤖 AI Analysis - Get AI-powered insights on your errors
• 📈 Analytics - Track application usage and trends
• 🔔 Alerts - Set up notifications for critical issues
• 🔒 Security - Monitor security events and threats

Installation

Install the package via NuGet:

dotnet add package CatchMonitor.SDK

Or via Package Manager:

Install-Package CatchMonitor.SDK

Quick Start

1. Initialize the SDK

using CatchMonitor.SDK;

// Initialize with your configuration
CatchMonitor.Init(new CatchMonitorOptions
{
    ApiBaseUrl = "https://your-api.catchmonitor.com", // Your API URL
    TenantKey = "your-tenant-key",
    ApiKey = "your-api-key",
    ApplicationId = Guid.Parse("your-application-id"),
    TenantId = Guid.Parse("your-tenant-id"),
    Environment = "Production", // or "Development", "Staging"
    Release = "1.0.0"
});

2. Capture Errors

try
{
    // Your application code
    throw new InvalidOperationException("Something went wrong!");
}
catch (Exception ex)
{
    // Capture the exception
    await CatchMonitor.CaptureExceptionAsync(ex);
}

3. Add Context

// Set user information
CatchMonitor.SetUser("user123", "john.doe", "john@example.com");

// Add breadcrumbs for context
CatchMonitor.AddBreadcrumb("User clicked button", "ui", "info");
CatchMonitor.AddBreadcrumb("API call started", "http", "info");

// Set custom tags
CatchMonitor.SetTag("feature", "checkout");
CatchMonitor.SetTag("version", "2.1.0");

4. Performance Monitoring

// Track transactions
using var transaction = CatchMonitor.StartTransaction("checkout-process", "ecommerce");
try
{
    // Your business logic
    await ProcessPayment();
    transaction.SetStatus("ok");
}
catch (Exception ex)
{
    transaction.SetStatus("error");
    await CatchMonitor.CaptureExceptionAsync(ex);
}

// Track metrics
await CatchMonitor.TrackMetricAsync("response_time", 150.5, "milliseconds");
await CatchMonitor.TrackApiCallAsync("POST", "/api/orders", 200, 120.0);

Configuration Options

The CatchMonitorOptions class provides extensive configuration:

var options = new CatchMonitorOptions
{
    // Required
    ApiBaseUrl = "https://your-api.catchmonitor.com",
    TenantKey = "your-tenant-key",
    ApiKey = "your-api-key",
    ApplicationId = Guid.Parse("your-application-id"),
    TenantId = Guid.Parse("your-tenant-id"),
    Environment = "Production",
    
    // Optional
    Release = "1.0.0",
    UserId = "current-user-id",
    SessionId = "session-123",
    MaxBreadcrumbs = 100,
    TracesSampleRate = 1.0,
    SessionReplayEnabled = true,
    SessionReplaySampleRate = 0.1,
    MaxSessionReplayEvents = 1000,
    SessionReplayDuration = 300,
    DomSnapshots = false,
    MaxDomSnapshots = 10,
    
    // Callbacks
    BeforeSend = (data) => {
        // Modify data before sending
        return data;
    },
    BeforeBreadcrumb = (breadcrumb) => {
        // Modify breadcrumb before adding
        return breadcrumb;
    }
};

Configuration

You can configure the SDK using various methods:

// Method 1: Direct configuration
CatchMonitor.Init(new CatchMonitorOptions
{
    ApiBaseUrl = "https://api.catchmonitor.com",
    TenantKey = "your-tenant-key",
    ApiKey = "your-api-key",
    ApplicationId = Guid.Parse("your-application-id"),
    TenantId = Guid.Parse("your-tenant-id"),
    Environment = "Production"
});

// Method 2: Use environment variables
var apiUrl = Environment.GetEnvironmentVariable("CATCHMONITOR_API_URL") 
    ?? "https://api.catchmonitor.com";

CatchMonitor.Init(new CatchMonitorOptions
{
    ApiBaseUrl = apiUrl,
    TenantKey = Environment.GetEnvironmentVariable("CATCHMONITOR_TENANT_KEY"),
    ApiKey = Environment.GetEnvironmentVariable("CATCHMONITOR_API_KEY"),
    ApplicationId = Guid.Parse(Environment.GetEnvironmentVariable("CATCHMONITOR_APPLICATION_ID")),
    TenantId = Guid.Parse(Environment.GetEnvironmentVariable("CATCHMONITOR_TENANT_ID")),
    Environment = "Production"
});

// Method 3: Configuration-based
var configuration = new ConfigurationBuilder()
    .AddJsonFile("appsettings.json")
    .Build();

CatchMonitor.Init(new CatchMonitorOptions
{
    ApiBaseUrl = configuration["CatchMonitor:ApiUrl"],
    TenantKey = configuration["CatchMonitor:TenantKey"],
    ApiKey = configuration["CatchMonitor:ApiKey"],
    ApplicationId = Guid.Parse(configuration["CatchMonitor:ApplicationId"]),
    TenantId = Guid.Parse(configuration["CatchMonitor:TenantId"]),
    Environment = configuration["CatchMonitor:Environment"]
});

Advanced Usage

Custom Error Events

var errorEvent = new ErrorEventCreateRequest
{
    Message = "Custom business logic error",
    ExceptionType = "BusinessException",
    StackTrace = "Custom stack trace",
    Environment = "Production",
    ContextData = JsonSerializer.Serialize(new { orderId = 12345, userId = "user123" })
};

await CatchMonitor.SendErrorEventAsync(errorEvent);

Performance Spans

using var span = CatchMonitor.StartSpan("database-query", "SELECT * FROM users");
try
{
    await database.QueryAsync("SELECT * FROM users");
    span.SetStatus("ok");
}
catch (Exception ex)
{
    span.SetStatus("error");
    span.SetData("error", ex.Message);
}

Session Replay

var sessionReplay = new SessionReplayCreateRequest
{
    SessionId = "session-123",
    UserId = "user-456",
    Events = JsonSerializer.Serialize(replayEvents),
    Url = "https://example.com/checkout",
    UserAgent = "Mozilla/5.0...",
    Viewport = "1920x1080"
};

await CatchMonitor.SendSessionReplayAsync(sessionReplay);

AI Analysis

var aiAnalysis = new AIAnalysisCreateRequest
{
    ErrorEventId = errorEventId,
    AnalysisType = "root-cause",
    CustomPrompt = "Analyze this error and suggest fixes",
    ContextData = JsonSerializer.Serialize(context)
};

await CatchMonitor.SendAIAnalysisAsync(aiAnalysis);

Integration Examples

ASP.NET Core

// Program.cs
var builder = WebApplication.CreateBuilder(args);

// Add CatchMonitor
CatchMonitor.Init(new CatchMonitorOptions
{
    ApiBaseUrl = builder.Configuration["CatchMonitor:ApiUrl"],
    TenantKey = builder.Configuration["CatchMonitor:TenantKey"],
    ApiKey = builder.Configuration["CatchMonitor:ApiKey"],
    ApplicationId = Guid.Parse(builder.Configuration["CatchMonitor:ApplicationId"]),
    TenantId = Guid.Parse(builder.Configuration["CatchMonitor:TenantId"]),
    Environment = builder.Environment.EnvironmentName
});

// Global exception handler
app.UseExceptionHandler(errorApp =>
{
    errorApp.Run(async context =>
    {
        var exception = context.Features.Get<IExceptionHandlerFeature>()?.Error;
        if (exception != null)
        {
            await CatchMonitor.CaptureExceptionAsync(exception);
        }
    });
});

Console Applications

class Program
{
    static async Task Main(string[] args)
    {
        // Initialize CatchMonitor
        CatchMonitor.Init(new CatchMonitorOptions
        {
            ApiBaseUrl = "https://api.catchmonitor.com",
            TenantKey = "your-tenant-key",
            ApiKey = "your-api-key",
            ApplicationId = Guid.Parse("your-app-id"),
            TenantId = Guid.Parse("your-tenant-id"),
            Environment = "Production"
        });

        try
        {
            // Your application logic
            await RunApplication();
        }
        catch (Exception ex)
        {
            await CatchMonitor.CaptureExceptionAsync(ex);
        }
        finally
        {
            await CatchMonitor.CloseAsync();
        }
    }
}

Publishing the SDK

Build and Package

# Build the SDK
dotnet build CatchMonitor.SDK/CatchMonitor.SDK.csproj --configuration Release

# Create NuGet package
dotnet pack CatchMonitor.SDK/CatchMonitor.SDK.csproj --configuration Release --output ./packages

Publish to NuGet

# Publish to NuGet.org
dotnet nuget push ./packages/CatchMonitor.SDK.1.0.0.nupkg --api-key YOUR_API_KEY --source https://api.nuget.org/v3/index.json

# Publish to private feed
dotnet nuget push ./packages/CatchMonitor.SDK.1.0.0.nupkg --api-key YOUR_API_KEY --source https://your-private-feed.com/v3/index.json

Version Management

Update the version in CatchMonitor.SDK.csproj:

<Version>1.0.1</Version> 
<Version>1.1.0</Version> 
<Version>2.0.0</Version> 

Best Practices

1. Initialize Early: Initialize CatchMonitor as early as possible in your application lifecycle
2. Use Environment Variables: Store sensitive configuration in environment variables
3. Handle Failures Gracefully: The SDK is designed to fail silently to not impact your application
4. Use Transactions: Wrap important operations in transactions for better performance monitoring
5. Add Context: Use breadcrumbs and tags to provide context for debugging
6. Sample Rates: Use appropriate sample rates for high-volume applications

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Community Forum
• 📧 Support Email

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please read our Contributing Guide for details on our code of conduct and the process for submitting pull requests.