X39.Roslyn.OpenTelemetry 1.0.0.3

• X39.Roslyn.OpenTelemetry
  • Overview
  • Semantic Versioning
    • Key Features
  • Details
    • Purpose
    • How It Works
    • Example
      • Before Generation
      • After Generation (Auto-generated Code)
  • Attributes
    • ActivityAttribute
      • Other Specialized Attributes
  • Usage
    • Installation
    • Add Attributes
  • Building
  • Test coverage
  • Contributing
    • Code of Conduct
    • Contributors Agreement
  • 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. 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

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)

// <auto-generated/>
#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<string, object?>("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:

dotnet add package X39.Roslyn.OpenTelemetry

Add Attributes

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

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 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 file for details.