Shared.K8.Common 1.0.3

Shared.K8.Common

A comprehensive .NET 9 library for configuring OpenTelemetry observability (logging, metrics, and tracing) in ASP.NET Core applications using standard OpenTelemetry environment variables.

Features

• Simple API: Just two extension methods - AddObservability() and UseObservability()
• Zero Configuration: Works out-of-the-box with sensible defaults
• Standard Compliant: Uses official OpenTelemetry environment variables
• Comprehensive Telemetry: Logging, metrics, and distributed tracing included
• Error Resilient: Gracefully falls back to console when OTLP endpoints are unavailable
• Production Ready: Built on OpenTelemetry 1.14.0 with .NET 9 support

Quick Start

using Shared.K8.Common.OpenTelemetry;

var builder = WebApplication.CreateBuilder(args);

// Add OpenTelemetry observability
builder.AddObservability();

var app = builder.Build();

// Configure observability middleware
app.UseObservability();

app.Run();

That's it! Your application now has comprehensive observability configured with:

• Structured logging with OpenTelemetry
• ASP.NET Core and HTTP client metrics and tracing
• Prometheus metrics endpoint at /metrics
• Automatic fallback to console when no OTLP endpoint is configured

Configuration

Configure the library using standard OpenTelemetry environment variables:

# Basic configuration
OTEL_SERVICE_NAME=my-web-api
OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317
OTEL_EXPORTER_OTLP_PROTOCOL=grpc

# With authentication
OTEL_SERVICE_NAME=my-web-api
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.company.com:4317
OTEL_EXPORTER_OTLP_HEADERS="authorization=Bearer token123"

What's Included

Automatic Instrumentation

• ASP.NET Core: HTTP request/response metrics and tracing
• HTTP Client: Outbound HTTP call metrics and tracing
• Prometheus: /metrics endpoint for scraping

Built-in Meters

• Microsoft.AspNetCore.Hosting - Request metrics
• Microsoft.AspNetCore.Server.Kestrel - Server metrics
• System.Net.Http - HTTP client metrics
• System.Net.NameResolution - DNS metrics
• Custom service meter (matches your service name)

Resource Attributes

• service.name - From environment or application name
• service.version - Set to "1.0.0"
• service.instance.id - Machine name
• deployment.environment - Environment name
• service.namespace - Set to "mockery"

Smart Fallbacks

• OTLP available: Exports to your configured endpoint
• OTLP unavailable: Falls back to console output
• No configuration: Uses console for development

Usage Examples

Docker Deployment

FROM mcr.microsoft.com/dotnet/aspnet:9.0
WORKDIR /app
COPY . .

ENV OTEL_SERVICE_NAME=my-web-api
ENV OTEL_EXPORTER_OTLP_ENDPOINT=http://jaeger:4317

ENTRYPOINT ["dotnet", "MyApp.dll"]

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-web-api
spec:
  template:
    spec:
      containers:
      - name: my-web-api
        image: my-web-api:latest
        env:
        - name: OTEL_SERVICE_NAME
          value: "my-web-api"
        - name: OTEL_EXPORTER_OTLP_ENDPOINT
          value: "http://otel-collector:4317"

With Custom Telemetry

using System.Diagnostics;
using System.Diagnostics.Metrics;

var builder = WebApplication.CreateBuilder(args);

// Create custom telemetry
using var activitySource = new ActivitySource("MyApp.Orders");
using var meter = new Meter("MyApp.BusinessMetrics");
var orderCounter = meter.CreateCounter<int>("orders_total");

builder.AddObservability();

var app = builder.Build();
app.UseObservability();

app.MapPost("/orders", (Order order) =>
{
    using var activity = activitySource.StartActivity("ProcessOrder");
    activity?.SetTag("order.id", order.Id);
    
    orderCounter.Add(1, new("status", "processed"));
    return Results.Ok();
});

app.Run();

Requirements

• .NET 9.0 or later
• ASP.NET Core applications

Links

• GitHub Repository
• Full Documentation