Observator 0.1.0-preview3

Observator: Zero-Effort .NET Observability

Observator is an AOT-compatible source generator that automatically instruments .NET assemblies with OpenTelemetry tracing, logging, and metrics capabilities. It uses compile-time code generation and interceptors to provide zero-configuration, high-performance observability instrumentation that works seamlessly with modern .NET applications, including those using Native AOT compilation.

Features

• AOT-First Design: Full compatibility with Native AOT compilation by eliminating runtime reflection.
• Zero Dependencies: Only references System.Diagnostics.DiagnosticSource, which is built into .NET.
• Zero Configuration: Works out-of-the-box with sensible defaults.
• Attribute-Driven Instrumentation: Enable selective instrumentation by decorating methods, classes, or interfaces with a simple [ObservatorTrace] attribute.
• Cross-Assembly Compatibility: Supports instrumentation across project boundaries within a solution.
• High Performance: Generates optimized code that adds minimal overhead to instrumented methods.
• Standards Compliant: Generates code compatible with OpenTelemetry standards and .NET diagnostic conventions.

Getting Started

Installation

Add the Observator NuGet package to your project:

dotnet add package Observator

Usage

1. Add the [ObservatorTrace] attribute to any method, class, or interface you want to instrument. For classes and interfaces, all public instance methods will be traced.

   • Note: You cannot use [ObservatorTrace] on both a class and its methods at the same time. If both are present, a compile-time error will be emitted.

   using Observator;
   
   namespace MyAwesomeApp;
   
   // Class-level usage (all methods instrumented)
   [ObservatorTrace]
   public class MyService
   {
       public virtual string Greet(string name)
       {
           return $"Hello, {name}!";
       }
   }
   
   // Method-level usage (only this method instrumented)
   public class MyOtherService
   {
       [ObservatorTrace]
       public string OnlyThisIsTraced() => "Traced!";
   }
   
   // Error: Do not combine class-level and method-level attributes
   [ObservatorTrace]
   public class InvalidService
   {
       [ObservatorTrace] // This will cause a compile-time error
       public void Conflict() { }
   }
   

2. Configure your OpenTelemetry pipeline to listen to the ActivitySource created by Observator.

   using OpenTelemetry;
   using OpenTelemetry.Trace;
   using Observator.Generated.MyAwesomeApp; // Import the generated namespace
   
   public class Program
   {
       public static void Main(string[] args)
       {
           using var tracerProvider = Sdk.CreateTracerProviderBuilder()
               .AddSource(ObservatorInfrastructure.ActivitySourceName)
               .AddConsoleExporter() // Or your preferred exporter
               .Build();
   
           var myService = new MyAwesomeApp.MyService();
           myService.Greet("World");
       }
   }
   

Building from Source

To build the project from source, you will need the .NET 9 SDK.

1. Clone the repository:

   git clone https://github.com/psimsa/observator.git
   

2. Navigate to the project directory:

   cd observator
   

3. Build the solution:

   dotnet build
   

License

This project is licensed under the MIT License. See the LICENSE file for details.