# purview-dev/purview-telemetry-sourcegenerator architecture

> Architecture diagram of the GitHub repository purview-dev/purview-telemetry-sourcegenerator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/purview-dev/purview-telemetry-sourcegenerator
- Repository: https://github.com/purview-dev/purview-telemetry-sourcegenerator

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Node
    A["User Telemetry Interfaces(with attributes)"]:::external

    %% Source Generator and its components
    subgraph "Source Generator"
        B["Telemetry Source Generator Core"]:::core
        C["Attribute/Annotation Analyzers"]:::analyzer
        B --> C
        D["Generated Output Modules"]:::module
        B --> D
    end

    %% Generated Output Modules breakdown
    subgraph "Generated Output Modules"
        D1["Activity Generation Module"]:::module
        D2["Logging Generation Module"]:::module
        D3["Metrics Generation Module"]:::module
        D --> D1
        D --> D2
        D --> D3
    end

    %% Build System subgraph
    subgraph "Build and Integration System"
        E["Build Scripts (.build)"]:::build
        F["Build Config (src/.build-system)"]:::build
    end

    %% Client application integration
    G["Client Application Integration (via Dependency Injection)"]:::external
    H["Sample Application"]:::app
    I["Unit Tests"]:::test

    %% External Dependencies
    J["Roslyn Compiler Integration"]:::external
    K["NuGet Package Distribution"]:::external

    %% Relationships
    A -->|"triggers"| B
    E -->|"invokes"| B
    F -->|"configures"| B
    D1 -->|"exposed to"| G
    D2 -->|"exposed to"| G
    D3 -->|"exposed to"| G
    G -->|"demonstrated by"| H
    B -->|"integrates with"| J
    J -->|"used by"| B
    H -->|"validated by"| I
    K ---|"packages"| B

    %% Click Events
    click B "https://github.com/purview-dev/purview-telemetry-sourcegenerator/tree/main/src"
    click C "https://github.com/purview-dev/purview-telemetry-sourcegenerator/tree/main/src"
    click D1 "https://github.com/purview-dev/purview-telemetry-sourcegenerator/tree/main/src"
    click D2 "https://github.com/purview-dev/purview-telemetry-sourcegenerator/tree/main/src"
    click D3 "https://github.com/purview-dev/purview-telemetry-sourcegenerator/tree/main/src"
    click E "https://github.com/purview-dev/purview-telemetry-sourcegenerator/blob/main/.build"
    click F "https://github.com/purview-dev/purview-telemetry-sourcegenerator/blob/main/src/.build-system"
    click H "https://github.com/purview-dev/purview-telemetry-sourcegenerator/tree/main/samples/SampleApp"
    click I "https://github.com/purview-dev/purview-telemetry-sourcegenerator/blob/main/samples/SampleApp/SampleApp.UnitTests"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef analyzer fill:#ccf,stroke:#333,stroke-width:2px;
    classDef module fill:#cfc,stroke:#333,stroke-width:2px;
    classDef build fill:#fc9,stroke:#333,stroke-width:2px;
    classDef app fill:#cff,stroke:#333,stroke-width:2px;
    classDef test fill:#ffc,stroke:#333,stroke-width:2px;
    classDef external fill:#eee,stroke:#333,stroke-dasharray: 5 5;
```
