ErrStack.Extensions 1.0.1

ErrStack SDK for .NET

ErrStack is a powerful error tracking and performance monitoring platform for C# applications. This SDK allows you to easily integrate ErrStack into your ASP.NET Core applications with minimal configuration.

🚀 Features

• ✅ Automatic Error Tracking - Global exception handler captures all errors
• ✅ Performance Monitoring - Track method/endpoint execution times
• ✅ Fire & Forget - Non-blocking, async tracking (zero performance impact)
• ✅ Attribute-Based - Decorate controllers/actions for selective tracking
• ✅ Middleware Support - Automatic tracking for all endpoints
• ✅ Sensitive Data Masking - Automatically mask passwords, tokens, credit cards
• ✅ Sampling Support - Control tracking rate (e.g., track 10% of requests)
• ✅ Flexible Configuration - Manual or automatic tracking modes
• ✅ Stack Trace Analysis - Detailed error information with inner exceptions
• ✅ .NET 8+ Support - Built for modern .NET applications

📦 Installation

Core Package (Required)

dotnet add package ErrStack.Client

ASP.NET Core Integration (Recommended)

dotnet add package ErrStack.AspNetCore

Extensions (Optional)

dotnet add package ErrStack.Extensions

⚡ Quick Start

1. Get Your API Key

1. Sign up at errstack.com
2. Create a project
3. Copy your API key (e.g., sk_856b2960dcbd45acb8a7b41c176afbb5)

2. Configure in Program.cs

using ErrStack.AspNetCore;
using ErrStack.Client;

var builder = WebApplication.CreateBuilder(args);

// Add ErrStack with your API key
builder.Services.AddErrstack(options =>
{
    options.ApiKey = "YOUR_API_KEY_HERE";
    options.ApiUrl = "https://v1.errstack.com";
    options.Environment = builder.Environment.EnvironmentName;
});

builder.Services.AddControllers();

var app = builder.Build();

// Add ErrStack middleware
app.UseErrstackErrorHandling();      // Automatic error tracking
app.UseErrstackExecutionTracking();  // Automatic execution tracking

app.MapControllers();
app.Run();

3. That's It! 🎉

Your application is now tracking errors and performance automatically.

📖 Usage Examples

Example 1: Minimal Configuration (Core Only)

// Minimal setup - just the API key
builder.Services.AddErrstackCore("YOUR_API_KEY_HERE");

// Manual tracking in your code
public class ProductService
{
    private readonly IErrstackClient _errstack;

    public ProductService(IErrstackClient errstack)
    {
        _errstack = errstack;
    }

    public async Task<Product> GetProduct(int id)
    {
        try
        {
            // Your logic here
            return await _repository.GetById(id);
        }
        catch (Exception ex)
        {
            // Manual error logging
            await _errstack.LogErrorAsync(ex);
            throw;
        }
    }
}

Example 2: Attribute-Based Tracking (Selective)

using ErrStack.AspNetCore.Attributes;
using ErrStack.Client;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class ProductController : ControllerBase
{
    // Track execution time for this endpoint
    [HttpGet]
    [ErrstackTrackExecution]
    public async Task<IActionResult> GetAll()
    {
        var products = await _productService.GetAll();
        return Ok(products);
    }

    // Track execution AND capture request/response payloads
    [HttpPost]
    [ErrstackTrackExecution(TrackPayload = true)]
    public async Task<IActionResult> Create([FromBody] Product product)
    {
        var result = await _productService.Create(product);
        return CreatedAtAction(nameof(GetById), new { id = result.Id }, result);
    }

    // Automatic error capture
    [HttpDelete("{id}")]
    [ErrstackCaptureErrors]
    public async Task<IActionResult> Delete(int id)
    {
        await _productService.Delete(id);
        return NoContent();
    }

    // Exclude endpoint from tracking
    [HttpGet("health")]
    [ErrstackIgnore]
    public IActionResult Health()
    {
        return Ok(new { status = "healthy" });
    }
}

Example 3: Manual Execution Tracking with using

public class OrderService
{
    private readonly IErrstackClient _errstack;

    public async Task<Order> ProcessOrder(int orderId)
    {
        // Automatically tracks execution time
        using var tracker = _errstack.TrackExecution();

        // Add optional metadata
        tracker.WithHttpMethod("POST")
                .WithIpAddress(context.Connection.RemoteIpAddress?.ToString());

        // Your business logic
        var order = await _orderRepository.GetById(orderId);
        await _paymentService.Process(order);

        return order;

        // Execution time is automatically sent when disposed
    }
}

Example 4: Middleware-Based (Full Automation)

var builder = WebApplication.CreateBuilder(args);

// Enable automatic tracking for ALL endpoints
builder.Services.AddErrstack(options =>
{
    options.ApiKey = "YOUR_API_KEY_HERE";
    options.EnableAutoErrorTracking = true;
    options.EnableAutoExecutionTracking = true;  // Track ALL endpoints
    options.IgnoreEndpoints = new[] { "/health", "/metrics", "/swagger" };
});

builder.Services.AddControllers();

var app = builder.Build();

// Add middleware - tracks EVERYTHING automatically
app.UseErrstackTracking();

app.MapControllers();
app.Run();

// Now ALL your endpoints are tracked - no code changes needed!

Example 5: Advanced Configuration

builder.Services.AddErrstack(options =>
{
    options.ApiKey = "YOUR_API_KEY_HERE";
    options.ApiUrl = "https://v1.errstack.com";
    options.Environment = "Production";

    // Performance settings
    options.EnableAutoErrorTracking = true;
    options.EnableAutoExecutionTracking = false;  // Use attributes instead
    options.TimeoutSeconds = 5;

    // Sampling - track only 10% of requests (reduces load)
    options.SamplingRate = 0.1;

    // Ignore specific endpoints
    options.IgnoreEndpoints = new[]
    {
        "/health",
        "/metrics",
        "/swagger",
        "/api/internal"
    };

    // Security
    options.MaskSensitiveData = true;  // Auto-mask passwords, tokens, etc.
});

Example 6: Custom Code Location

public class BackgroundService
{
    private readonly IErrstackClient _errstack;

    public async Task ProcessJobAsync()
    {
        try
        {
            // Background job logic
            await ProcessData();
        }
        catch (Exception ex)
        {
            // Log error with custom location
            await _errstack.LogErrorAsync(ex, new CodeLocation
            {
                Namespace = "MyApp.BackgroundServices",
                ClassName = "DataProcessingService",
                MethodName = "ProcessJobAsync",
                Endpoint = "/jobs/process-data"
            });

            throw;
        }
    }
}

🎯 Configuration Options

ErrstackOptions Properties

🏷️ Attributes

[ErrstackTrackExecution]

Automatically tracks execution time for a controller or action.

[ErrstackTrackExecution(TrackPayload = true)]
public async Task<IActionResult> MyAction() { }

Properties:

• TrackPayload (bool) - Capture request and response payloads

[ErrstackCaptureErrors]

Automatically captures and logs errors for a controller or action.

[ErrstackCaptureErrors]
public async Task<IActionResult> MyAction() { }

[ErrstackIgnore]

Excludes a controller or action from ErrStack tracking.

[ErrstackIgnore]
public IActionResult Health() { }

🔧 Middleware

UseErrstackErrorHandling()

Adds global error handling middleware. Captures all unhandled exceptions.

app.UseErrstackErrorHandling();

UseErrstackExecutionTracking()

Adds execution tracking middleware. Tracks all endpoint executions.

app.UseErrstackExecutionTracking();

UseErrstackTracking()

Adds both error handling and execution tracking middleware.

app.UseErrstackTracking();

📊 What Gets Tracked?

Error Tracking

• ✅ Exception type and message
• ✅ Stack trace
• ✅ Inner exceptions
• ✅ Code location (namespace, class, method)
• ✅ Endpoint/route
• ✅ Timestamp

Execution Tracking

• ✅ Execution time (milliseconds)
• ✅ Code location (namespace, class, method)
• ✅ Endpoint/route
• ✅ HTTP method (GET, POST, etc.)
• ✅ IP address
• ✅ User agent
• ✅ Request payload (optional)
• ✅ Response payload (optional)
• ✅ Timestamp

🔒 Security & Privacy

Automatic Sensitive Data Masking

ErrStack automatically masks sensitive data in:

• Error messages
• Stack traces
• Request/response payloads

Masked patterns:

• password
• token
• api_key / api-key
• secret
• Credit card numbers (e.g., 4111-1111-1111-1111)

Example:

// Before masking:
{ "username": "john", "password": "secret123" }

// After masking:
{ "username": "john", "password": "***MASKED***" }

⚡ Performance Impact

ErrStack is designed for zero performance impact on your application:

• ✅ Fire & Forget - All tracking is async and non-blocking
• ✅ Background Processing - Data is sent in background threads
• ✅ Sampling Support - Reduce load by tracking a percentage of requests
• ✅ Circuit Breaker - Silent failures if ErrStack API is down
• ✅ Configurable Timeout - Prevent slow API calls from blocking

Your application never waits for ErrStack!

🎨 Use Cases

Startup Projects

// Minimal - manual tracking only
builder.Services.AddErrstackCore("YOUR_API_KEY");

Small to Medium Projects

// Attribute-based selective tracking
builder.Services.AddErrstack("YOUR_API_KEY");
app.UseErrstackErrorHandling();

Enterprise Projects

// Full automation with sampling and advanced config
builder.Services.AddErrstack(options =>
{
    options.ApiKey = "YOUR_API_KEY";
    options.EnableAutoErrorTracking = true;
    options.EnableAutoExecutionTracking = true;
    options.SamplingRate = 0.1;  // 10% sampling
    options.IgnoreEndpoints = new[] { "/health", "/metrics" };
});
app.UseErrstackTracking();

🛠️ Packages

🌐 Supported Frameworks

• ✅ .NET 8.0+
• ✅ .NET 9.0+
• ✅ ASP.NET Core 8.0+
• ✅ ASP.NET Core 9.0+

📚 Documentation

• Official Documentation
• API Reference
• Examples

🐛 Troubleshooting

Not tracking errors?

1. Verify your API key is correct
2. Check that middleware is added in the correct order
3. Ensure EnableAutoErrorTracking is true
4. Check application logs for ErrStack errors

Not tracking executions?

1. Check that UseErrstackExecutionTracking() is called
2. Verify EnableAutoExecutionTracking is true OR use [ErrstackTrackExecution] attribute
3. Check if endpoint is in IgnoreEndpoints list

Performance issues?

1. Reduce SamplingRate (e.g., 0.1 for 10%)
2. Disable TrackPayload to avoid capturing large payloads
3. Add frequently-called endpoints to IgnoreEndpoints

🤝 Contributing

We welcome contributions! Please see our Contributing Guide.

📄 License

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

🔗 Links

• Website
• GitHub
• NuGet
• Support
• Twitter

💬 Support

Need help? We're here for you!

• 📧 Email: support@errstack.com
• 💬 Discord: Join our community
• 📖 Docs: docs.errstack.com
• 🐛 Issues: GitHub Issues

Built with ❤️ by the ErrStack team