opentelementry-dotnet-instrumentation_skill

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