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

Property	Type	Description
Host	string	Target hostname
Status	Status	Overall health status
Quorum	QuorumInfo	Quorum details (required, total, met)
DurationMs	int	Total check duration
Observations	Observation[]	Cross-region analysis findings
Regions	LocationResult[]	Per-region results

Observation Codes

Code	Severity	Description
DNS_ANSWERS_MISMATCH	warning	DNS differs across regions
CERT_EXPIRING_SOON	warning	Certificate expires < 30 days
CERT_WEAK_PROTOCOL	warning	TLS 1.0 or 1.1 detected
REGIONAL_FAILURE	error	Probe failed in some regions

Documentation

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