Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/x39/x39.roslyn.opentelemetry

A source generator to generate ActivitySource's from attributed method bodies
https://github.com/x39/x39.roslyn.opentelemetry

csharp csharp-library dotnet nuget nuget-package roslyn roslyn-generator source-generator

Last synced: about 2 months ago
JSON representation

A source generator to generate ActivitySource's from attributed method bodies

Awesome Lists containing this project

README 

        

* [X39.Roslyn.OpenTelemetry](#x39roslynopentelemetry)

  * [Overview](#overview)

  * [Semantic Versioning](#semantic-versioning)

    * [Key Features](#key-features)

  * [Details](#details)

    * [Purpose](#purpose)

    * [How It Works](#how-it-works)

    * [Example](#example)

      * [Before Generation](#before-generation)

      * [After Generation (Auto-generated Code)](#after-generation-auto-generated-code)

  * [Attributes](#attributes)

    * [`ActivityAttribute`](#activityattribute)

      * [Other Specialized Attributes](#other-specialized-attributes)

  * [Usage](#usage)

    * [Installation](#installation)

    * [Add Attributes](#add-attributes)

  * [Building](#building)

  * [Test coverage](#test-coverage)

  * [Contributing](#contributing)

    * [Code of Conduct](#code-of-conduct)

    * [Contributors Agreement](#contributors-agreement)

  * [License](#license)



# X39.Roslyn.OpenTelemetry



## Overview



**X39.Roslyn.OpenTelemetry** is a .NET library that provides simplified

way to integrate OpenTelemetry tracing into your projects by utilizing

Roslyn Source Generators.

The project is designed to simplify the creation and management of

`System.Diagnostics.Activity` objects, which are fundamental to distributed tracing.



## Semantic Versioning



This library follows the principles of [Semantic Versioning](https://semver.org/). This means that version numbers and

the way they change convey meaning about the underlying changes in the library. For example, if a minor version number

changes (e.g., 1.1 to 1.2), this indicates that new features have been added in a backwards-compatible manner.



### Key Features



- **Custom Attributes**: Define built-in attributes like `ActivityAttribute` and many specialized attributes (

  `InternalActivity`, `ServerActivity`, etc.) that can generate custom methods for starting activities.

- **Support for Tags and Contexts**: Provides a declarative way to attach tags, link activities, or manage contexts

  using attributes and method parameters.



## Details



### Purpose



The library is aimed at developers using the .NET platform who want to:



1. Use OpenTelemetry for distributed tracing.

2. Streamline the creation and management of `Activity` objects.

3. Improve maintainability and readability by generating boilerplate tracing code automatically.



### How It Works



The core idea of this library revolves around utilizing Roslyn Source Generators to:



- Detect methods marked with custom attributes like `[Activity]`.

- Generate the actual implementation of the tracing boilerplate code during compile-time.



For example:



- You can declare a method with `[Activity]` and specify its behavior declaratively using method parameters (e.g., tags

  or `ActivityContext`).

- The source generator will then create the appropriate implementation for you.



### Example



#### Before Generation



```csharp

using System.Diagnostics;

using X39.Roslyn.OpenTelemetry.Attributes;



public partial class Example

{

    [Activity(ActivityKind.Internal)]

    private static partial Activity? StartExampleActivity(string tag);

}

```



#### After Generation (Auto-generated Code)



```csharp

// 

#nullable enable

using System.Diagnostics;

using System.Collections.Generic;



partial class Example

{

    private static ActivitySource ExampleActivitySource = new("Example");

    private static partial Activity? StartExampleActivity(string tag)

    {

        return MyActivitySource.StartActivity(

            "Example",

            ActivityKind.Internal,

            parentContext: default,

            tags: new[] { new KeyValuePair("tag", tag) }

        );

    }

}

```



This eliminates the need for developers to write repetitive manual tracing code.



## Attributes



### `ActivityAttribute`



Attaches metadata and declarative tracing behavior to methods for automatic generation.



**Main Properties**:



- **`ActivityKind`**: Specifies the activity type (e.g., Internal, Server, Client).

- **`Identifier`**: Provides a custom identifier for the generated activity.

- **`Name`**: Allows you to override the default name for the activity.



#### Other Specialized Attributes



- `InternalActivityAttribute`

- `ServerActivityAttribute`

- `ClientActivityAttribute`

- `ProducerActivityAttribute`

- `ConsumerActivityAttribute`



These specialized attributes encapsulate specific kinds of `ActivityKind` to reduce verbosity when applied.



## Usage



### Installation



You can add this library to your project via NuGet:



```bash

dotnet add package X39.Roslyn.OpenTelemetry

```



### Add Attributes



Simply use the provided attributes to define activities. For example:



```csharp

internal static partial class MyActivities

{

    [ServerActivity]

    public static partial Activity? StartMyServerActivity(ActivityContext context);

}

```



Compile the project and the generator will produce the corresponding code.



## Building



This project uses GitHub Actions for continuous integration. The workflow is defined in `.github/workflows/main.yml`. It

includes steps for restoring dependencies, building the project, and publishing a NuGet package.



## Test coverage



This project is covered by unit tests for the generator only.

This means that the generated code is not yet tested.



## Contributing



Contributions are welcome!

Please submit a pull request or create a discussion to discuss any changes you wish to make.



### Code of Conduct



Be excellent to each other.



### Contributors Agreement



First of all, thank you for your interest in contributing to this project!

Please add yourself to the list of contributors in the [CONTRIBUTORS](CONTRIBUTORS.md) file when submitting your

first pull request.

Also, please always add the following to your pull request:



```

By contributing to this project, you agree to the following terms:

- You grant me and any other person who receives a copy of this project the right to use your contribution under the

  terms of the GNU Lesser General Public License v3.0.

- You grant me and any other person who receives a copy of this project the right to relicense your contribution under

  any other license.

- You grant me and any other person who receives a copy of this project the right to change your contribution.

- You waive your right to your contribution and transfer all rights to me and every user of this project.

- You agree that your contribution is free of any third-party rights.

- You agree that your contribution is given without any compensation.

- You agree that I may remove your contribution at any time for any reason.

- You confirm that you have the right to grant the above rights and that you are not violating any third-party rights

  by granting these rights.

- You confirm that your contribution is not subject to any license agreement or other agreement or obligation, which

  conflicts with the above terms.

```



This is necessary to ensure that this project can be licensed under the GNU Lesser General Public License v3.0 and

that a license change is possible in the future if necessary (e.g., to a more permissive license).

It also ensures that I can remove your contribution if necessary (e.g., because it violates third-party rights) and

that I can change your contribution if necessary (e.g., to fix a typo, change implementation details, or improve

performance).

It also shields me and every user of this project from any liability regarding your contribution by deflecting any

potential liability caused by your contribution to you (e.g., if your contribution violates the rights of your

employer).

Feel free to discuss this agreement in the discussions section of this repository, i am open to changes here (as long as

they do not open me or any other user of this project to any liability due to a **malicious contribution**).



## License



This project is licensed under the GNU Lesser General Public License v3.0. See the [LICENSE](LICENSE) file for details.