https://github.com/purview-dev/purview-telemetry-sourcegenerator
.NET Source Generator for interface-based telemetry building activities, activity events, logs and metrics.
https://github.com/purview-dev/purview-telemetry-sourcegenerator
activity distributed-tracing dotnet events logging metrics open-telemetry open-telemetry-csharp source-generator spans
Last synced: about 1 month ago
JSON representation
.NET Source Generator for interface-based telemetry building activities, activity events, logs and metrics.
- Host: GitHub
- URL: https://github.com/purview-dev/purview-telemetry-sourcegenerator
- Owner: purview-dev
- License: mit
- Created: 2024-03-04T18:31:56.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2024-04-13T20:44:14.000Z (about 1 year ago)
- Last Synced: 2024-04-14T10:58:28.807Z (about 1 year ago)
- Topics: activity, distributed-tracing, dotnet, events, logging, metrics, open-telemetry, open-telemetry-csharp, source-generator, spans
- Language: C#
- Homepage:
- Size: 1.66 MB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Purview Telemetry Source Generator
Generates [`ActivitySource`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.activitysource), [`ILogger`](https://learn.microsoft.com/en-us/dotnet/api/microsoft.extensions.logging.ilogger), and [`Metrics`](https://learn.microsoft.com/en-us/dotnet/api/system.diagnostics.metrics) based telemetry from methods you define on an interface.
[](https://github.com/purview-dev/purview-telemetry-sourcegenerator/actions/workflows/ci.yml)
This approach allows for:
- Faster iteration cycles - simply create the method on your interface and the implementation will be automatically generated
- Easy mocking/ substitution for testing - a full sample project, including tests can be found [here](https://github.com/purview-dev/purview-telemetry-sourcegenerator/tree/main/samples/SampleApp)
- Built-in dependency injection helper generation
Use the latest version available on [NuGet](https://www.nuget.org/packages/Purview.Telemetry.SourceGenerator/), which supports the following frameworks:
- .NET Framework 4.7.2, or higher
- .NET 8 or higher
Reference in your `Directory.Build.props` or `.csproj` file:
```xml
all
runtime; build; native; contentfiles; analyzers
```
For more information see the [wiki](https://github.com/purview-dev/purview-telemetry-sourcegenerator/wiki).
## Example Interface
This is called a **multi-target interface** because it generates more than one output type: **Activities, Logging, and Metrics**.
> [!TIP]
> When generating a single target, the generator will automatically infer the necessary attributes. More information about multi-targeting can be found in [here](https://github.com/purview-dev/purview-telemetry-sourcegenerator/wiki/Multi-Targeting).
```csharp
using Purview.Telemetry.Activities;
using Purview.Telemetry.Logging;
using Purview.Telemetry.Metrics;
///
/// Generates an implementation of the methods for each generation type (Activity, Logging, or Metrics)
/// and an extension method to enable easy registration with the IServiceCollection.
///
[ActivitySource]
[Logger]
[Meter]
interface IEntityStoreTelemetry
{
///
/// Creates and starts an Activity and adds the parameters as Tags and Baggage.
///
[Activity]
Activity? GettingEntityFromStore(int entityId, [Baggage]string serviceUrl);
///
/// Adds an ActivityEvent to the Activity with the parameters as Tags.
///
[Event]
void GetDuration(Activity? activity, int durationInMS);
///
/// Adds the parameters as Baggage to the Activity.
///
[Context]
void RetrievedEntity(Activity? activity, float totalValue, int lastUpdatedByUserId);
///
/// Generates a structured log message using an ILogger - defaults to Informational.
///
[Log]
void ProcessingEntity(int entityId, string updateState);
///
/// Generates a structured log message using an ILogger, specifically defined as Informational.
///
[Info]
void ProcessingAnotherEntity(int entityId, string updateState);
///
/// Adds 1 to a Counter with the entityId as a Tag.
///
[AutoCounter]
void RetrievingEntity(int entityId);
}
```
To see the code generated for the `IEntityStoreTelemetry` interface, see the [`Generated Output`](https://github.com/purview-dev/purview-telemetry-sourcegenerator/wiki/Generated-Output) page in the wiki.
## Example Project
The [.NET Aspire Sample](https://github.com/purview-dev/purview-telemetry-sourcegenerator/tree/main/samples/SampleApp) demos the Activities, Logs, and Metrics generation working together with the Aspire Dashboard.
Check the page in the the [wiki](https://github.com/purview-dev/purview-telemetry-sourcegenerator/wiki/Sample-Application) for information.
> [!TIP]
> This sample project has [`EmitCompilerGeneratedFiles`](https://learn.microsoft.com/en-us/dotnet/core/extensions/configuration-generator#enable-the-configuration-source-generator) set to `true`, so you can easily see the generated output.
## Notes on Logging Generation
There are two types of logging generation based on:
1. **Microsoft Logging Extension Packages** – Determined by the NuGet packages referenced in your project.
2. **Attribute-based Configuration** – Controlled using attributes in your code.
For more details, see the [Logging](https://github.com/purview-dev/purview-telemetry-sourcegenerator/wiki/Logging) page in the wiki.