swisslife-oss/thor-generator

An Event Tracing for Windows (ETW) EventSource generator built on .Net Core 2.0

Thor Generator

Thor Generator (ThorGen) is a generator for ETW (Event Tracing for Windows) event sources which helps avoid frequent mistakes and saves time.

Microsoft's Event Tracing for Windows is a powerful tracing framework that offers minimal overhead and structured payloads.

The problem with writing event sources is often that you have to work with unsafe code and that if you get anything wrong in your event source it won't write events at all. This behaviour is a feature of ETW, applications shall not be disrupted by faulty event sources, so your event source won't log but it also won't throw exceptions that crash your application.

The other problem with writing event sources is that one has to invest a lot of time into writing repetitive code "just" to have some "logging" in an application. It is not seldom that teams do not want to invest that time and opt for a simpler string based logging solution waiving all the benefits of ETW.

ThorGen wants to solve these problems by generating the necessary event source code and letting developers focus on designing their tracing events around their business logic. ThorGen makes ETW easy to use and fast to implement.

Event sources will be specified by writing interfaces that define the trace events and their payloads (no other DSL needed, no context switch). The event source generator will inspect those interfaces and generate the necessary event source code.

The event source templates can be amended to fit your needs and your aesthetic point of view concerning the generated code.

At the moment, we offer two built-in templates to generate event sources in c#.

Get Thor Generator

We provide a nuget package that will integrate ThorGen with your project rather than relying on an installation. This will make it easy for developers who want to clone, build and get going rather than installing prerequisites.

Install the Thor.Generator nuget package to the projects that contain event source interfaces.

Install-Package Thor.Generator

We have a walk through for both scenarious here.

How to get started

Open a project where you want to add your event sources and add an interface that declares the structure of the event source you want to create. Annotate your event source interface with a EventSourceDefinitionAttribute. You can either use the attribute located in our tracing core or create your own.

using System;
using System.Diagnostics.Tracing;
using ChilliCream.Tracing;

[EventSourceDefinition("MyEventSourceName")]
public interface IMyEventSource
{
    [Event(1)]
    void SayHello(string message);
}

If you are using the msbuild integration of ThorGen just compile your project; otherwise, open a terminal window and switch to your solution location and run the following command.

thorgen

Or run thorgen -r if you want ThorGen to search recursively for any solution.

For a more detailed help that shows all the scenarious visit our documentation.

Building the Repository

Instructions

Build status of master branch

Platform	Build	Tests	Code Coverage
Windows

Legal and Licensing

The Thor Generator (ThorGen) is licensed under the MIT license.

thor-generator's Issues

Support for large payloads.

The current generator will only accept value types and string as payloads to be compliant with etw. There are cases were customers still want to generate an event source with custom objects for which they handle the payload serialisation in an nonevent method.

The template info file should define which types are accepted by a template. Moreover, a template should explicitly in- or exclude types or work with wildcards.

Report errors during generation as Msbuild errors

Templates should expose package dependencies and add dependent packages to target projects.

We should introduce a new package dependency property to the template settings file. All packages that are defined there will then be automatically added to the generator target project it it is missing those packages.

Automatically set the unsafe code setting to target projects.

The generator should enable unsafe code for the project it is adding the event sources to if the setting was not already set.

Generator should rearrange parameters that attachments are on the end

Template that does not rely on the chillicream tracing core

We need a new template that does not rely on any other packages. The current c# default template relies on the ChilliCream.Tracing.Abstractions package.

Remove chocolatey deployment and use dotnet cli task instead.

The chocolatey package is not really a good way to consume and use the generator. It would be much more useful to use the generator as dotnet cli integration.

Generation fails when the EventSource Interface contains a collection parameter

Hi,

We have an interface that contains a method which has a parameter that is a collection.

[EventSourceDefinition(Name = "xxx")]
public interface IXXXEventSource
{
    [Event(1, Level = EventLevel.Warning,
        Message = "XXX", Version = 4)]
    void SomeXXXs(List<string> xxxs);
}

The Thor Generator v1.3.3 currently fails to generate the class for this interface. We get the following error in the console output:

Processing \src\EventSources\EventSources.csproj -> \src\EventSources\EventSources.csproj ...
1>
1>Unhandled Exception: System.ArgumentNullException: Value cannot be null.
1>Parameter name: type
1> at Thor.Generator.Templates.ModelExtensions.AddParameter(EventModel eventModel, String name, String type) in C:\thor\generator\src\Generator\Templates\ModelExtensions.cs:line 65
1> at Thor.Generator.Templates.EventSourceDefinitionVisitor.VisitMethodDeclaration(MethodDeclarationSyntax node) in C:\thor\generator\src\Generator\Templates\EventSourceDefinitionVisitor.cs:line 85
1> at Microsoft.CodeAnalysis.CSharp.CSharpSyntaxWalker.Visit(SyntaxNode node)
1> at Microsoft.CodeAnalysis.CSharp.CSharpSyntaxWalker.DefaultVisit(SyntaxNode node)
1> at Microsoft.CodeAnalysis.CSharp.CSharpSyntaxWalker.Visit(SyntaxNode node)
1> at Microsoft.CodeAnalysis.CSharp.CSharpSyntaxWalker.DefaultVisit(SyntaxNode node)
1> at Microsoft.CodeAnalysis.CSharp.CSharpSyntaxWalker.Visit(SyntaxNode node)
1> at Microsoft.CodeAnalysis.CSharp.CSharpSyntaxWalker.DefaultVisit(SyntaxNode node)
1> at Microsoft.CodeAnalysis.CSharp.CSharpSyntaxWalker.Visit(SyntaxNode node)
1> at Thor.Generator.EventSourceResolver.d__3.MoveNext() in C:\thor\generator\src\Generator\EventSourceResolver.cs:line 33
1> at Thor.Generator.EventSourceGenerator.Generate() in C:\thor\generator\src\Generator\EventSourceGenerator.cs:line 39
1> at Thor.Generator.Tasks.EventSourceGeneratorTaskBase.GenerateEventSources(Project source, Project target) in C:\thor\generator\src\Generator\Tasks\EventSourceGeneratorTaskBase.cs:line 123
1> at Thor.Generator.Tasks.ProjectEventSourceGeneratorTask.Execute() in C:\thor\generator\src\Generator\Tasks\ProjectEventSourceGeneratorTask.cs:line 77
1> at Thor.Generator.CLI.Program.Main(String[] args) in C:\thor\generator\src\Generator.CLI\Program.cs:line 20
1> .nuget\packages\thor.generator\1.3.3\build\Thor.Generator.targets(16,5): error MSB3073: The command "".nuget\packages\thor.generator\1.3.3\build..\tools\win10-x64\thorgen.exe" project -s "\src\EventSources\EventSources.csproj" -t "\src\EventSources\EventSources.csproj"" exited with code -532462766.
1>Done building project "EventSources.csproj" -- FAILED.

There is an easy workaround for this issue: use a wrapper class around the collection and have the parameter be of that type.

Align build with HotChocolate and Thor-Client

Don't create attachments for enums

For enum parameter will be an attachment created which is not expected