aaronontheweb/dotnet-skills
Overview
This skill provides pragmatic guidance for implementing OpenTelemetry instrumentation in .NET projects. It covers trace (Activity/Span) and metric design, naming conventions, error handling, performance guardians, and telemetry API surface considerations. The guidance is focused on safe, low-overhead instrumentation that integrates with OpenTelemetry semantic conventions.
How this skill works
The skill inspects common .NET telemetry patterns and prescribes concrete rules: how to create and name ActivitySources, when to start Activities, how to set attributes and events, and how to design Meter-based metrics. It emphasizes cheap fast-path checks (e.g., ActivitySource.HasListeners, activity.IsAllDataRequested), null-safety, and low-cardinality metric dimensions. It also outlines error recording, status semantics, and API ergonomics for telemetry surfaces.
When to use it
- Adding OpenTelemetry instrumentation to an existing .NET codebase
- Creating or reviewing ActivitySource and Meter definitions
- Designing public telemetry APIs for libraries or components
- Hardening telemetry for production performance and resiliency
- Defining metric dimensions and ensuring low cardinality
Best practices
- Guard all diagnostic code so it cannot throw or affect application logic; assume Activity can be null
- Check ActivitySource.HasListeners() and activity.IsAllDataRequested before doing allocations or expensive work
- Name ActivitySources and Activities with stable, compile-time identifiers; use DisplayName for runtime specifics
- Follow OpenTelemetry semantic conventions and prefer standard attributes over custom ones; attributes must be non-null, non-empty
- Keep metric dimensions low-cardinality and predefined; make high-cardinality dimensions opt-in
- Measure durations with timestamp math (Stopwatch.GetTimestamp) and avoid per-operation allocations
Example use cases
- Instrument a library with a primary ActivitySource and a separate Detailed ActivitySource for opt-in traces
- Record order processing duration with a Histogram and low-cardinality dimensions (order_type, region, outcome)
- Implement safe exception recording: set ActivityStatusCode.Error, add otel.status_* tags, and add exception events
- Add counters for connection lifecycle using explicit methods like ConnectionOpened/ConnectionClosed
- Audit telemetry code for hidden allocations: string interpolation, LINQ, or disposable timing helpers
FAQ
No. Operation names must be stable and not contain runtime data; use DisplayName or tags for specifics.
How do I avoid metric cardinality explosion?
Only use low-cardinality, predefined dimensions. Make any high-cardinality label opt-in and avoid user or object IDs as metric labels.
25 skills
This skill helps configure Aspire AppHost to emit explicit environment variables for app settings, keeping code free of Aspire clients and service discovery.
This skill guides implementing OpenTelemetry instrumentation in .NET apps, covering tracing, metrics, naming, error handling, performance, and API design.
This skill helps you write modern high-performance C# code using records, value objects, pattern matching, and async design for robust APIs.
This skill helps you test Akka.NET actors using Akka.Hosting.TestKit patterns with DI, TestProbes, and in-memory persistence.
This skill centralizes observability, health checks, resilience, and service discovery for Aspire apps, wiring OpenTelemetry, health endpoints, and HttpClient
This skill helps you choose the right .NET concurrency abstraction, guiding async/await, channels, Akka.NET, and avoiding locks.
This skill helps .NET developers implement robust configuration binding, validation, and monitoring using Microsoft.Extensions.Options patterns for reliable
This skill helps .NET developers implement robust Akka.NET patterns for event streams, supervision, error handling, DI, and testable cluster abstractions.
This skill helps you write end-to-end integration tests for .NET Aspire apps using xUnit, real dependencies, and dynamic endpoint discovery.
This skill decompiles .NET assemblies with ILSpy to reveal implementation details, aiding understanding, debugging, and auditing library behavior.
This skill speeds up CI by caching Playwright browsers across Linux, macOS, and Windows, reducing download overhead and ensuring version-aligned caches.
This skill helps organize dependency injection registrations via extension methods, enabling cohesive grouping, reuse in production and tests, and cleaner
This skill helps you design stable public APIs and manage compatibility across versions by applying extend-only principles for .NET libraries.
This skill helps you test emails locally with Mailpit in .NET Aspire, capturing messages and validating content in integration tests.
This skill helps you deploy Akka.NET clusters with dynamic service discovery via Akka.Management, replacing static seeds and enabling auto-formation.
This skill enables snapshot testing of email templates with Verify to catch regressions in rendered HTML across MJML templates.
This skill helps diagnose and fix Linux .NET HTTPS dev certificate trust issues from generation to system CA integration.
This skill helps maintain AGENTS.md and CLAUDE.md indexes to route .NET skills and agents efficiently and automatically.
This skill helps you choose optimal .NET serialization formats, emphasizing schema-based options and AOT-ready System.Text.Json across APIs, messaging, and
This skill helps you author robust Playwright tests for Blazor apps by guiding stable selectors, navigation, and authentication patterns.
This skill analyzes code CRAP scores and coverage to highlight high-risk, untested code paths and guide refactoring priorities.
This skill helps you write integration tests using TestContainers for .NET with xUnit against real infrastructure in Docker.
This skill helps you apply EF Core best practices for performance, migrations, and reliable no-tracking queries across projects.
This skill enables robust snapshot testing in .NET using Verify to catch unintended changes in APIs, responses, and serialized outputs via human-reviewed
This skill standardizes observability, health checks, and resilience across Aspire services by providing a shared ServiceDefaults project.
