- Sidemark introduces C# telemetry comments that turn simple annotations into full OpenTelemetry instrumentation at build time.
- These C# telemetry comments use three syntaxes — //?, //!, and //?! — to emit tags, events, spans, and error status.
- The package runs as an MSBuild task, using Roslyn to rewrite source files before compilation — your originals are never touched.
- A single NuGet package ships the rewriter, a Roslyn analyzer with six diagnostic codes, and runtime attributes — with zero transitive dependencies.
OpenTelemetry Is Winning — But It Comes at a Cost
C# telemetry comments might sound like a contradiction in terms. Comments don’t do anything, right? That’s been the rule since forever. But David Whitney, a developer who’s clearly spent too many late nights staring at cluttered instrumentation code, has built something that quietly breaks that rule — and the result is surprisingly compelling.
The context matters here. OpenTelemetry has become the de facto standard for distributed tracing and observability across the industry. Whether you’re running microservices on Kubernetes or a modest web API on Azure, OTel is almost certainly in your stack or on your roadmap. That’s genuinely good progress — a unified, vendor-neutral telemetry standard is exactly what the ecosystem needed.
But instrumentation has a dirty secret. The auto-instrumentation that ships with most OTel SDKs — the stuff that automatically traces HTTP calls, database queries, and framework internals — only gets you so far. It tells you that a request happened. It doesn’t tell you why the checkout failed, or which customer ID was involved, or what the cart total was when the exception fired. That business context has to come from custom instrumentation you write yourself, by hand, in your application code.
And that’s where things get ugly fast.
The Boilerplate Tax Nobody Talks About
If you’ve instrumented a real production codebase with OpenTelemetry, you’ve felt this. A method that processes an order starts clean. Then you add Activity.Current?.SetTag(“orderId”, orderId). Then another tag for the total. Then an AddEvent before the external API call. Then a SetStatus in the catch block. Before long, the method is twice as long as it needs to be, and half of what you’re reading when you review it has nothing to do with what the code actually does.
Whitney puts it plainly in his writeup: the bookkeeping of telemetry starts to drown out the intent of the code. During code review, you’re constantly doing a mental parse to separate the business logic from the observability scaffolding around it. Neither deserves to lose that fight — but right now, they’re always competing.
This isn’t a new problem. Logging frameworks have wrestled with similar noise for years. Structured logging helped. Aspect-oriented approaches helped a bit more. But nothing has cleanly solved the specific tension between readable application logic and the instrumentation that rides alongside it. C# telemetry comments represent a genuinely new angle on this old problem.
What Sidemark Actually Does With C# Telemetry Comments
Sidemark’s answer is to turn comments into a write surface for instrumentation. C# telemetry comments work through three distinct syntaxes: //? for tags and spans, //! for events, and //?! for exception recording. Drop //? next to a local variable and it becomes a SetTag call in the compiled output. Put //! before an awaited external call and it emits an AddEvent. Annotate a method signature with //? and the entire method body gets wrapped in a span. Put //? on a catch block and it records error status automatically.
The resulting source reads like clean, lightly annotated application code. The compiled output is identical to what you’d have written by hand — every Activity call, every tag, every event. You just didn’t have to write it.
Whitney draws an interesting parallel to Wallaby.js, the JavaScript testing tool that projects runtime values inline next to the code that produced them. Wallaby uses comments as a read surface — a way to see values without adding console logs. Sidemark flips that: C# telemetry comments as a write surface, a way to declare observability intent without adding noise to the logic itself.
The framing is smart. C# telemetry comments occupy the place where programmers have always explained things that the code can’t express on its own — intent, context, caveats. In a world where a lot of that understanding now happens while staring at production traces, using C# telemetry comments to bridge the gap between what code does and what you need to observe about it feels like a natural evolution rather than a hack.
Build-Time Rewriting — No Runtime Magic, No Surprises
The implementation is where Sidemark earns some real engineering credibility. There’s no runtime reflection, no IL weaving at execution time, no aspect-oriented proxy nonsense. Sidemark runs as an MSBuild task that fires just before CoreCompile. It uses Roslyn to parse each source file’s syntax tree, rewrites the annotated nodes into their equivalent Activity calls, and writes the rewritten copies into the obj/ directory. The C# compiler only ever sees the rewritten files. Your source files on disk are never modified.
This is exactly the right architectural choice. It means the compiled IL is identical to hand-written instrumentation — no performance overhead, no indirection, no surprises in a debugger. It also means the approach works with any tooling that understands standard .NET output, because nothing about the output is non-standard.
There’s also a neat escape hatch. Because C# telemetry comments are syntactically valid comments, disabling Sidemark — either with [assembly: DisableSidemark] or a project property — means they pass straight through to the compiler as plain comments. Your code doesn’t break. The annotations just stop being active. That’s a useful property for teams who want to try this incrementally without betting their entire build pipeline on a new tool.
What Ships in the Package
The NuGet package — dotnet add package Sidemark — is deliberately minimal. It ships three things: runtime attributes for configuration and opt-out, a Roslyn analyzer that catches misused C# telemetry comments (diagnostic codes SDM001 through SDM006, wired in automatically), and the MSBuild rewriter itself. Crucially, it uses the Roslyn instance that already ships with your .NET SDK rather than bundling its own copy, so there are no transitive NuGet dependencies added to your application.
Requirements are sensible: .NET SDK 8.0.200 or newer to build, with support for any target framework compatible with netstandard2.0 — which covers modern .NET, .NET Framework 4.6.1+, Mono, and Unity. Setup is a single assembly attribute pointing at a configuration class that exposes your ActivitySource. After that, your C# telemetry comments take effect on the next build.
The Heresy of Load-Bearing Comments
Whitney acknowledges the obvious objection himself: making comments load-bearing is heresy. Comments have a long and distinguished history of lying. They go stale. They describe what the code used to do, or what someone intended it to do, or what someone thought it did at 11pm on a Friday. Trusting C# telemetry comments to carry correctness-critical intent is a genuine philosophical leap.
The counter-argument is that this particular use case is different. These C# telemetry comments aren’t describing intent that the code might silently contradict — they’re declarative annotations that either produce correct instrumentation or get caught by the Roslyn analyzer before your CI pipeline turns green. The tooling closes the feedback loop that normally lets comments rot. If a //? is attached to something that can’t be turned into a valid tag, you get a compiler diagnostic, not a silent mismatch between documentation and reality.
That’s a meaningfully different contract from the “please keep this comment updated” honor system that makes comment-rot such a persistent problem.
Where This Fits in the Broader Observability Conversation
The observability tooling market is enormous and getting more crowded. Datadog, Honeycomb, Grafana, and a dozen others are all competing on how easily their platforms surface meaningful signals. But almost all of that competition assumes the instrumentation data is already rich and contextual — and that assumption is frequently wrong in practice.
The gap between auto-instrumented traces and genuinely useful traces is filled by exactly the kind of custom instrumentation Sidemark is designed to make easier. C# telemetry comments lower the friction of adding business context to spans in a way that is directly additive to the value teams actually get from their observability platforms. A 30-line OpenTelemetry block condensed to 5 lines of annotated code isn’t just aesthetically cleaner — it’s the difference between a team that instruments thoroughly and a team that instruments reluctantly.
Sidemark is early. It’s one developer’s answer to a real problem, not a vendor-backed platform play. But the instinct is right, the implementation is solid, and the constraints it imposes are minimal. For .NET teams spending meaningful time untangling telemetry noise from application logic in code review, it’s worth an afternoon to find out whether C# telemetry comments make the code actually read lighter afterwards.
Source: https://dev.to/david_whitney/sidemark-active-telemetry-comments-for-c-1bai
