Xakpc.NetDiag.Client 1.1.3

Xakpc.NetDiag.Client

Official .NET client for the NetDiag API - network diagnostics as a service. Run distributed health checks (DNS, TLS, HTTP, Ping) from multiple geographic regions worldwide.

Install

dotnet add package Xakpc.NetDiag.Client

Quickstart

using Xakpc.NetDiag.Client;

// Create client (anonymous - limited requests/min)
var client = new NetDiagClient();

// Run diagnostics
var result = await client.CheckAsync("example.com");

Console.WriteLine($"Status: {result.Status}");
Console.WriteLine($"Quorum: {result.Quorum.Required}/{result.Quorum.Total} (met: {result.Quorum.Met})");
Console.WriteLine($"Duration: {result.DurationMs}ms");

// Check for cross-region observations
foreach (var obs in result.Observations)
{
    Console.WriteLine($"  [{obs.Severity}] {obs.Code}: {obs.Message}");
}

// Inspect per-region results
foreach (var region in result.Regions)
{
    Console.WriteLine($"  {region.Region}: {region.Status}");
    if (region.Ping != null)
        Console.WriteLine($"    Ping: {region.Ping.AvgRttMs}ms ({region.Ping.Received}/{region.Ping.Sent} packets)");
    if (region.Dns != null)
        Console.WriteLine($"    DNS: {region.Dns.QueryTimeMs}ms");
    if (region.Tls != null)
        Console.WriteLine($"    TLS: {region.Tls.DaysUntilExpiry} days until expiry");
    if (region.Http != null)
        Console.WriteLine($"    HTTP: {region.Http.StatusCode} in {region.Http.TotalTimeMs}ms");
}

With API Key

// Authenticated client
var client = new NetDiagClient("your-api-key");

// Or with full options
var client = new NetDiagClient(new NetDiagClientOptions
{
    ApiKey = "your-api-key",
    Timeout = TimeSpan.FromSeconds(60)
});

Dependency Injection

// In Program.cs or Startup.cs
builder.Services.AddNetDiagClient(options =>
{
    options.ApiKey = builder.Configuration["NetDiag:ApiKey"];
});

// Inject INetDiagClient in your services
public class HealthCheckService(INetDiagClient netDiag)
{
    public async Task<bool> IsServiceHealthy(string host)
    {
        return await netDiag.IsHealthyAsync(host);
    }
}

Advanced Usage

// Check specific regions with custom parameters
var result = await client.CheckAsync(new ChecksRequest
{
    Host = "api.example.com",
    Regions = "us-west,eu-central",
    Port = 8443,
    PingCount = 10
});

// Quick health check
bool healthy = await client.IsHealthyAsync("example.com");

// Get status only
Status status = await client.GetStatusAsync("example.com");

// URLs are automatically normalized to hostnames
await client.CheckAsync("https://example.com/api/v1"); // checks "example.com"

Prometheus Output

// Get metrics in Prometheus text format
string metrics = await client.CheckPrometheusAsync("example.com");

// With custom parameters
string metrics = await client.CheckPrometheusAsync(new ChecksRequest
{
    Host = "api.example.com",
    Regions = "us-west,eu-central"
});

// Returns Prometheus text format:
// netdiag_check_success{host="example.com",region="us-west"} 1
// netdiag_ping_rtt_ms{host="example.com",region="us-west"} 15.2
// netdiag_http_time_ms{host="example.com",region="us-west"} 120.0
// netdiag_dns_query_ms{host="example.com",region="us-west"} 12.0
// ...

Response Types

ChecksResponse

Observation Codes

Documentation

Full documentation: https://netdiag.dev/docs/dotnet