irontelemetry-dotnet/README.md

<p align="center">
  <a href="https://irontelemetry.com">
    <img src="https://irontelemetry.com/logo.png" alt="IronTelemetry" width="120" />
  </a>
</p>

<h1 align="center">IronTelemetry SDK for .NET</h1>

<p align="center">
  <strong>Error monitoring and crash reporting for .NET applications</strong>
</p>

<p align="center">
  <a href="https://www.nuget.org/packages/IronTelemetry.Client"><img src="https://img.shields.io/nuget/v/IronTelemetry.Client.svg" alt="NuGet"></a>
  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
</p>

<p align="center">
  <a href="https://irontelemetry.com">Website</a> •
  <a href="https://irontelemetry.com/docs">Documentation</a> •
  <a href="https://irontelemetry.com/docs/dotnet">.NET Guide</a> •
  <a href="https://git.marketally.com/ironservices">Git</a>
</p>

---

**IronTelemetry** helps you capture exceptions, track user journeys, and get actionable insights to fix issues faster. Built for developers who want simple, powerful error monitoring without the complexity.

## Installation

```bash
dotnet add package IronTelemetry.Client
```

## Quick Start

### Level 0: Basic Exception Capture

```csharp
using IronTelemetry.Client;

// Initialize with your DSN
IronTelemetry.Init("https://pk_live_xxx@irontelemetry.com");

// Capture exceptions
try
{
    DoSomething();
}
catch (Exception ex)
{
    IronTelemetry.CaptureException(ex);
    throw;
}

// Or use the extension method
catch (Exception ex)
{
    throw ex.Capture();
}
```

### Level 1: Journey Tracking

Track user journeys to understand the context of errors:

```csharp
using IronTelemetry.Client;

// Track a complete user journey
using (IronTelemetry.StartJourney("Checkout Flow"))
{
    IronTelemetry.SetUser(currentUser.Id, currentUser.Email);

    using (IronTelemetry.StartStep("Validate Cart", "business"))
    {
        ValidateCart();
    }

    using (IronTelemetry.StartStep("Process Payment", "business"))
    {
        ProcessPayment();
    }

    using (IronTelemetry.StartStep("Send Confirmation", "notification"))
    {
        SendConfirmationEmail();
    }
}
```

Any exceptions captured during the journey are automatically correlated.

## Configuration

```csharp
IronTelemetry.Init(new TelemetryOptions
{
    Dsn = "https://pk_live_xxx@irontelemetry.com",
    Environment = "production",
    AppVersion = "1.2.3",
    SampleRate = 1.0,  // 100% of events
    Debug = false,
    BeforeSend = ex => !ex.Message.Contains("expected error")
});
```

## Features

- **Automatic Exception Capture**: Capture and report exceptions with full stack traces
- **Journey Tracking**: Track user flows and correlate errors with context
- **Breadcrumbs**: Leave a trail of events leading up to an error
- **User Context**: Associate errors with specific users
- **Tags & Extras**: Add custom metadata to your events
- **Buffered Sending**: Events are batched and sent efficiently
- **Sample Rate**: Control the volume of events sent
- **Before Send Hook**: Filter events before sending

## Breadcrumbs

```csharp
// Add breadcrumbs to understand what happened before an error
IronTelemetry.AddBreadcrumb("User clicked checkout button", "ui");
IronTelemetry.AddBreadcrumb("Payment API called", "http");

// Or with full control
IronTelemetry.AddBreadcrumb(new Breadcrumb
{
    Category = "auth",
    Message = "User logged in",
    Level = BreadcrumbLevel.Info,
    Data = new Dictionary<string, object> { ["userId"] = "123" }
});
```

## Global Exception Handling

For console applications:

```csharp
IronTelemetry.Init("your-dsn");
TelemetryExtensions.UseUnhandledExceptionHandler();
```

## Helper Methods

```csharp
// Track a step with automatic error handling
TelemetryExtensions.TrackStep("Process Order", () =>
{
    ProcessOrder();
});

// Async version
await TelemetryExtensions.TrackStepAsync("Fetch Data", async () =>
{
    await FetchDataAsync();
});

// With return value
var result = TelemetryExtensions.TrackStep("Calculate Total", () =>
{
    return CalculateTotal();
});
```

## Flushing

```csharp
// Flush pending events before app shutdown
IronTelemetry.Flush();

// Or async
await IronTelemetry.FlushAsync();
```

## Documentation

For complete documentation, visit [irontelemetry.com/docs](https://irontelemetry.com/docs).

## Other SDKs

| Platform | Package |
|----------|---------|
| JavaScript/TypeScript | [@ironservices/telemetry](https://git.marketally.com/ironservices/irontelemetry-js) |
| Python | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-python) |
| Go | [irontelemetry-go](https://git.marketally.com/ironservices/irontelemetry-go) |
| Java | [irontelemetry-java](https://git.marketally.com/ironservices/irontelemetry-java) |
| Rust | [irontelemetry](https://git.marketally.com/ironservices/irontelemetry-rust) |

## Support

- **Documentation**: [irontelemetry.com/docs](https://irontelemetry.com/docs)
- **Email**: dev@ironservices.io
- **Issues**: [git.marketally.com/ironservices/irontelemetry-dotnet/issues](https://git.marketally.com/ironservices/irontelemetry-dotnet/issues)

## License

MIT License - see [LICENSE](LICENSE) for details.