How purview-dev/purview-telemetry-sourcegenerator works
Based on our analysis of the file tree and the README, this project is an open‐source .NET source generator that automatically creates telemetry code (using ActivitySource, ILogger, and Metrics) from annotated interface definitions. This tool is meant to speed up telemetry instrument generation by analyzing methods decorated with specific attributes (such as [Activity], [Log], etc.) and then auto-generating the necessary implementation logic. It also integrates with dependency injection systems to simplify registration in client applications, and there’s a sample application within the repository that demonstrates its use.
Main Components
• Telemetry Source Generator Core – The component responsible for scanning user code for telemetry interface definitions and generating source code. This is the heart of the project.
• Attribute/Annotation Analyzers – Parts of the generator that recognize attributes like [ActivitySource], [Logger], and [Meter]. These analyzers parse the user-provided interfaces to know which telemetry implementations to generate.
• Generated Output Modules – Separate generated logic for different telemetry targets:
– Activity Generation (using System.Diagnostics.ActivitySource)
– Logging Generation (using Microsoft.Extensions.Logging.ILogger)
– Metrics Generation (using System.Diagnostics.Metrics)
• Build and Integration System – This includes the build scripts (Makefile, .build directories, etc.), configuration files, and the integration logic that ties the source generator into the overall .NET build process (using Directory.Build.props and other build-related files).
• Sample Application and Unit Tests – The SampleApp within the samples directory demonstrates the generated telemetry code in a running application, while the UnitTests validate the correctness of the generated functionality.
Relationships and Interactions
• The source generator component integrates with the .NET compilation process (via Roslyn), meaning when a developer writes an interface annotated for telemetry, the generator is invoked during build.
• The attribute/annotation analyzers identify which parts of the code need telemetry integration, and then they trigger the generation of code that implements logging, metrics, and activity instrumentation.
• The generated code is then made available to client applications through dependency injection helpers, allowing the application (like the SampleApp) to use the telemetry functionalities seamlessly.
• Unit tests are set up to validate the output from the source generator, ensuring that the auto-generated telemetry code behaves as expected.
Architectural Patterns and Design Principles
• Convention over configuration: The generator takes method definitions and attributes as a single source of truth, reducing manual boilerplate.
• Separation of concerns: Different telemetry targets (activities, logging, metrics) are generated independently but share a unified interface contract.
• Extensibility through attributes: The use of attributes lets developers easily switch or extend telemetry behavior without altering the core generator code.
• Build system integration: The use of standardized build scripts and configuration files (Makefile, Directory.Build.props, etc.) indicates that the project is designed for consistent, reproducible builds and cross-project compatibility.
Relevant Technologies, Frameworks, and Libraries
• .NET Framework and .NET 8+: As indicated by the supported frameworks.
• Microsoft.Extensions.Logging: For generating and integrating logging functionality.
• System.Diagnostics (ActivitySource and Metrics): For telemetry and performance monitoring.
• Roslyn Compiler Platform: The source generator leverages Roslyn to integrate into the compilation process.
• NuGet package management: The README shows references to how this generator is distributed via NuGet.
• Clear and descriptive labels on each component (e.g., “Telemetry Source Generator Core”, “Attribute Analyzer”, “Activity Generator”, “Logging Generator”, “Metrics Generator”, “Sample Application”, “Unit Tests”).
– From user-defined telemetry interfaces (with attributes) into the source generator.
– From the source generator to the generated code modules.
– From generated code to client applications (using dependency injection).
– From build configuration files to the generator invocation process.
– For example, squares for core generator components, circles for ancillary modules (like tests), and hexagons for configuration/build integrations.
• Relevant technologies (like .NET, Roslyn, Microsoft.Extensions.Logging, etc.) alongside their associated components.