docs: added sample project

Makefile

@@ -4,7 +4,7 @@ SOLUTION_FILE = $(ROOT_FOLDER)Purview.Telemetry.SourceGenerator.sln
 TEST_PROJECT = $(ROOT_FOLDER)Purview.Telemetry.SourceGenerator.sln
 CONFIGURATION = Release
 
-PACK_VERSION = 0.0.11-prerelease
+PACK_VERSION = 0.0.12-prerelease
 ARTIFACT_FOLDER = p:/sync-projects/.local-nuget/
 
 # Targets

README.md

@@ -15,9 +15,9 @@ The following examples all contain explicit definitions, by that I mean that we
 
 Each generation target ([activity](./docs/ACTIVITIES.md), [logging](./docs/LOGGING.md) and [metrics](./docs/METRICS.md)) documentation contains information on what can be inferred.
 
-> You can mix-and-match generation targets within a single interface but, however the inferring functionality is more limited. This is called [multi-targetting](./docs/MULTITARGETTING.md).
+> You can mix-and-match generation targets within a single interface, however the ability to infer is more limited. This is called [multi-targetting](./docs/MULTITARGETTING.md).
 
-> In .NET, Activities, Events and Metrics refer to additional properties captured at creation or recording time as **tags**. However, in Open Telemetry these are referred to as **attributes**. As this source generator makes extensive use of marker attributes to control source code generation we will use the term tags to mean this properties, and attributes as the .NET [Attribute](https://learn.microsoft.com/en-us/dotnet/api/system.attribute) type.
+> In .NET, Activities, Events and Metrics refer to additional properties captured at creation, recording or observing as **tags**. However, in Open Telemetry these are referred to as **attributes**. As this source generator makes extensive use of marker attributes to control source code generation we will use the term tags to mean these properties, and attributes as the .NET [Attribute](https://learn.microsoft.com/en-us/dotnet/api/system.attribute) type.
 
 ### Activities
 

samples/SampleApp/SampleApp.AppHost/Program.cs

@@ -0,0 +1,5 @@
+var builder = DistributedApplication.CreateBuilder(args);
+
+builder.AddProject<Projects.SampleApp_Host>("sampleapp-host");
+
+builder.Build().Run();

samples/SampleApp/SampleApp.AppHost/Properties/launchSettings.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:15289",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development",
+        "DOTNET_ENVIRONMENT": "Development",
+        "DOTNET_DASHBOARD_OTLP_ENDPOINT_URL": "http://localhost:16263"
+      }
+    }
+  }
+}

samples/SampleApp/SampleApp.AppHost/SampleApp.AppHost.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <IsAspireHost>true</IsAspireHost>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Aspire.Hosting" Version="8.0.0-preview.4.24156.9" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\SampleApp.Host\SampleApp.Host.csproj" />
+  </ItemGroup>
+
+</Project>

samples/SampleApp/SampleApp.AppHost/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

samples/SampleApp/SampleApp.AppHost/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning",
+      "Aspire.Hosting.Dcp": "Warning"
+    }
+  }
+}

samples/SampleApp/SampleApp.Host/Controllers/WeatherForecastController.cs

@@ -0,0 +1,17 @@
+using Microsoft.AspNetCore.Mvc;
+using SampleApp.Host.Interfaces.Services;
+
+namespace SampleApp.Host.Controllers;
+
+[ApiController]
+[Route("[controller]")]
+public class WeatherForecastController(IWeatherService service) : ControllerBase
+{
+	[HttpGet(Name = "GetWeatherForecast")]
+	public IEnumerable<WeatherForecast> Get() 
+		=> service.GetWeatherForecastsAsync(5);
+
+	[HttpGet("{requestCount}", Name = "GetWeatherForecastWithRequest")]
+	public IEnumerable<WeatherForecast> Get(int requestCount) 
+		=> service.GetWeatherForecastsAsync(requestCount);
+}

samples/SampleApp/SampleApp.Host/Interfaces/Services/IWeatherService.cs

@@ -0,0 +1,5 @@
+namespace SampleApp.Host.Interfaces.Services; 
+
+public interface IWeatherService {
+	IEnumerable<WeatherForecast> GetWeatherForecastsAsync(int requestCount, CancellationToken cancellationToken = default);
+}

samples/SampleApp/SampleApp.Host/Interfaces/Services/IWeatherServiceTelemetry.cs

@@ -0,0 +1,30 @@
+using System.Diagnostics;
+using Purview.Telemetry;
+using Purview.Telemetry.Activities;
+using Purview.Telemetry.Logging;
+using Purview.Telemetry.Metrics;
+
+namespace SampleApp.Host.Interfaces.Services;
+
+[ActivitySource]
+[Logger]
+[Meter]
+public interface IWeatherServiceTelemetry {
+	[Activity(ActivityKind.Client)]
+	Activity? GettingWeatherForecastFromUpstreamService(string someRandomInfo, int requestedCount, [Baggage]int validatedRequestedCount);
+
+	[Event]
+	void MinAndMaxReceived(Activity? activity, int minTempInC, int maxTempInC);
+
+	[Log(LogLevel.Warning)]
+	void ThatsTooCold(int minTempInC);
+
+	[Log]
+	void RequestedCountIsTooSmall(int requestCount, int validatedRequestedCount);
+
+	[Counter(AutoIncrement = true)]
+	void WeatherForecastRequested();
+
+	[Counter(AutoIncrement = true)]
+	void ItsTooCold([Tag]int tooColdCount);
+}

samples/SampleApp/SampleApp.Host/Program.cs

@@ -0,0 +1,39 @@
+using SampleApp.Host.Interfaces.Services;
+using SampleApp.Host.Services;
+
+namespace SampleApp.Host;
+
+public class Program {
+	public static void Main(string[] args) {
+		var builder = WebApplication.CreateBuilder(args);
+		builder.AddServiceDefaults();
+		builder.Services.AddMetrics();
+
+		// Add services to the container.
+		builder.Services.AddIWeatherServiceTelemetry();
+		builder.Services.AddTransient<IWeatherService, WeatherService>();
+
+		builder.Services.AddControllers();
+		// Learn more about configuring Swagger/OpenAPI at https://aka.ms/aspnetcore/swashbuckle
+		builder.Services.AddEndpointsApiExplorer();
+		builder.Services.AddSwaggerGen();
+
+		var app = builder.Build();
+
+		app.MapDefaultEndpoints();
+
+		// Configure the HTTP request pipeline.
+		if (app.Environment.IsDevelopment()) {
+			app.UseSwagger();
+			app.UseSwaggerUI();
+		}
+
+		app.UseHttpsRedirection();
+
+		app.UseAuthorization();
+
+		app.MapControllers();
+
+		app.Run();
+	}
+}

samples/SampleApp/SampleApp.Host/Properties/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using Purview.Telemetry.Activities;
+
+[assembly: ActivitySourceGeneration("sample-weather-app")]

samples/SampleApp/SampleApp.Host/Properties/launchSettings.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "http://json.schemastore.org/launchsettings.json",
+  "iisSettings": {
+    "windowsAuthentication": false,
+    "anonymousAuthentication": true,
+    "iisExpress": {
+      "applicationUrl": "http://localhost:58142",
+      "sslPort": 44302
+    }
+  },
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "applicationUrl": "http://localhost:5275",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "applicationUrl": "https://localhost:7015;http://localhost:5275",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "IIS Express": {
+      "commandName": "IISExpress",
+      "launchBrowser": true,
+      "launchUrl": "swagger",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

samples/SampleApp/SampleApp.Host/SampleApp.Host.csproj

@@ -0,0 +1,19 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+	<PropertyGroup>
+		<TargetFramework>net8.0</TargetFramework>
+		<Nullable>enable</Nullable>
+		<ImplicitUsings>enable</ImplicitUsings>
+		<EmitCompilerGeneratedFiles>true</EmitCompilerGeneratedFiles>
+	</PropertyGroup>
+
+	<ItemGroup>
+		<PackageReference Include="Purview.Telemetry.SourceGenerator" Version="0.0.12-prerelease" />
+		<PackageReference Include="Swashbuckle.AspNetCore" Version="6.5.0" />
+	</ItemGroup>
+
+	<ItemGroup>
+		<ProjectReference Include="..\SampleApp.ServiceDefaults\SampleApp.ServiceDefaults.csproj" />
+	</ItemGroup>
+
+</Project>

samples/SampleApp/SampleApp.Host/SampleApp.Host.http

@@ -0,0 +1,6 @@
+@SampleApp.Host_HostAddress = http://localhost:5275
+
+GET {{SampleApp.Host_HostAddress}}/weatherforecast/
+Accept: application/json
+
+###

samples/SampleApp/SampleApp.Host/Services/WeatherService.cs

@@ -0,0 +1,47 @@
+using SampleApp.Host.Interfaces.Services;
+
+namespace SampleApp.Host.Services;
+
+sealed class WeatherService(IWeatherServiceTelemetry telemetry) : IWeatherService {
+	const int _tooColdTempInC = -10;
+
+	static readonly string[] _summaries =
+	[
+		"Freezing", "Bracing", "Chilly", "Cool", "Mild", "Warm", "Balmy", "Hot", "Sweltering", "Scorching"
+	];
+
+	public IEnumerable<WeatherForecast> GetWeatherForecastsAsync(int requestCount, CancellationToken cancellationToken = default) {
+		var validatedRequestedCount = requestCount;
+		if (validatedRequestedCount < 5) {
+			validatedRequestedCount = 5;
+
+			telemetry.RequestedCountIsTooSmall(requestCount, validatedRequestedCount);
+		}
+
+		using var activity = telemetry.GettingWeatherForecastFromUpstreamService($"{Guid.NewGuid()}", requestCount, validatedRequestedCount);
+
+		telemetry.WeatherForecastRequested();
+
+		// This would usually be async of course...
+		cancellationToken.ThrowIfCancellationRequested();
+
+		var results = Enumerable.Range(1, validatedRequestedCount).Select(index => new WeatherForecast {
+			Date = DateOnly.FromDateTime(DateTime.UtcNow.AddDays(index)),
+			TemperatureC = Random.Shared.Next(-20, 55),
+			Summary = _summaries[Random.Shared.Next(_summaries.Length)]
+		}).ToArray();
+
+		var minTempInC = results.Min(m => m.TemperatureC);
+		telemetry.MinAndMaxReceived(activity, 
+			minTempInC, 
+			results.Max(wf => wf.TemperatureC)
+		);
+
+		if (minTempInC < _tooColdTempInC) {
+			telemetry.ThatsTooCold(minTempInC);
+			telemetry.ItsTooCold(results.Count(wf => wf.TemperatureC < _tooColdTempInC));
+		}
+
+		return results;
+	}
+}

samples/SampleApp/SampleApp.Host/WeatherForecast.cs

@@ -0,0 +1,9 @@
+namespace SampleApp.Host;
+
+readonly public record struct WeatherForecast(
+    DateOnly Date,
+    int TemperatureC,
+    string? Summary) {
+
+    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
+}

samples/SampleApp/SampleApp.Host/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

samples/SampleApp/SampleApp.Host/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}