Rougamo.OpenTelemetry.Hosting 4.0.0-priview-1723657903

.NET 6.0 This package targets .NET 6.0. The package is compatible with this framework or higher. .NET Standard 2.0 This package targets .NET Standard 2.0. The package is compatible with this framework or higher.
This is a prerelease version of Rougamo.OpenTelemetry.Hosting.
There is a newer version of this package available.
See the version list below for details. 
dotnet add package Rougamo.OpenTelemetry.Hosting --version 4.0.0-priview-1723657903                

                    
                

            
NuGet\Install-Package Rougamo.OpenTelemetry.Hosting -Version 4.0.0-priview-1723657903
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Rougamo.OpenTelemetry.Hosting" Version="4.0.0-priview-1723657903" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
paket add Rougamo.OpenTelemetry.Hosting --version 4.0.0-priview-1723657903                

                    
                

            
#r "nuget: Rougamo.OpenTelemetry.Hosting, 4.0.0-priview-1723657903"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
// Install Rougamo.OpenTelemetry.Hosting as a Cake Addin
#addin nuget:?package=Rougamo.OpenTelemetry.Hosting&version=4.0.0-priview-1723657903&prerelease

// Install Rougamo.OpenTelemetry.Hosting as a Cake Tool
#tool nuget:?package=Rougamo.OpenTelemetry.Hosting&version=4.0.0-priview-1723657903&prerelease

Rougamo.OpenTelemetry

Rougamo.OpenTelemetry is a component designed to enrich OpenTelemetry with non-IO instrumentation. It leverages the static weaving capabilities of Rougamo to add Trace instrumentation to specified methods.

Quick Start

First, install Rougamo.OpenTelemetry.Hosting in the startup project, and then install Rougamo.OpenTelemetry in the project where you want to add instrumentation:

dotnet add package Rougamo.OpenTelemetry.Hosting
dotnet add package Rougamo.OpenTelemetry

In the Startup.cs of the startup project, initialize Rougamo.OpenTelemetry:

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        // ...

        services.AddOpenTelemetryTracing(builder =>
        {
            builder
                .AddRougamoSource() // Initialize Rougamo.OpenTelemetry
                .AddAspNetCoreInstrumentation()
                .AddJaegerExporter();
        });

        // Modify Rougamo.OpenTelemetry default configuration
        services.AddOpenTelemetryRougamo(options =>
        {
            options.ArgumentsStoreType = ArgumentsStoreType.Tag;
        });
    }
}

After setup, you can add instrumentation to your project. The simplest way is to use OtelAttribute and PureOtelAttribute on methods to add instrumentation. The difference between the two attributes is that OtelAttribute records parameters and return values by default, while PureOtelAttribute does not. You can also use ApmIgnoreAttribute and ApmRecordAttribute to ignore or record specific parameters or return values.

class Service
{
    [return: ApmIgnore]     // Do not record the return value
    [Otel] // Records parameters and return values by default, use ApmIgnoreAttribute to ignore parameters or return values
    public async Task<string> M1(
            [ApmIgnore] string uid, // Do not record this parameter
            DateTime time)
    {
        // do something
        return string.Empty;
    }

    [PureOtel] // Does not record parameters and return values by default, use ApmRecordAttribute to record specified parameters or return values
    public void M2(
            [ApmRecord] double d1,  // Record this parameter
            double d2)
    {
        // do something
    }
}

By default, parameters and return values are recorded as events in the current Span. You can modify where these are stored, as shown in the Startup example above. When methods like M1 or M2 are called, a corresponding Span will be created to record the data.

Bulk Weaving via Interfaces

Local instrumentation with OpenTelemetry is performed using static weaving via Rougamo. This means you can use various code weaving methods provided by Rougamo. For example, you can use the empty interface approach for weaving:

public interface ITestService : IRougamo<OtelAttribute>
{
    // ...
}
public class TestService : ITestService
{
    // ...
}

In the code above, since ITestService implements the IRougamo<> generic interface and specifies OtelAttribute as the generic type, all public (non-static) instance methods of TestService, the implementation class, will automatically have OtelAttribute woven into them. The default OtelAttribute.Flags property value is AccessFlags.InstancePublic, which means it injects into all public instance methods. Other accessibility attributes are listed below. If these do not meet your needs, you can inherit OtelAttribute or PureOtelAttribute and override the Flags property as needed.

Minimum Version Default Records Parameters and Return Values Default Does Not Record Parameters and Return Values Accessibility
0.1.2 PublicOtelAttribute PublicPureOtelAttribute All public methods, whether static or instance
0.1.2 StaticOtelAttribute StaticPureOtelAttribute All public static methods
0.1.2 FullOtelAttribute FullPureOtelAttribute All methods, regardless of accessibility

Weaving via Proxy Attributes

Proxy attribute weaving is another weaving method provided by Rougamo. One use case is to combine with Rougamo.APM.Abstractions. The attributes used for instrumentation, such as SpanAttribute and PureSpanAttribute, do not weave code themselves but are markers. Actual weaving is done via proxies.

// Add the following assembly-level attributes in Startup.cs or AssemblyInfo.cs
[assembly: MoProxy(typeof(SpanAttribute), typeof(OtelAttribute))]
[assembly: MoProxy(typeof(PureSpanAttribute), typeof(PureOtelAttribute))]

public class Cls
{
    [Span]  // Finally, the code implementation of OtelAttribute is woven via proxy
    public int M1()
    {
        // ...
        return 123;
    }

    [PureSpan]  // Finally, the code implementation of PureOtelAttribute is woven via proxy
    private async Task<string> M2Async()
    {
        // ...
        return string.Empty;
    }
}

Proxy-based weaving does not support interface weaving and cannot customize parameters (e.g., OtelAttribute.Name). However, the advantage of using this approach is that if you are unsure of your final APM or may switch to another APM not supported by OpenTelemetry, you only need to modify the MoProxyAttribute specification in the example code.

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp2.0 was computed.  netcoreapp2.1 was computed.  netcoreapp2.2 was computed.  netcoreapp3.0 was computed.  netcoreapp3.1 was computed. 
.NET Standard netstandard2.0 is compatible.  netstandard2.1 was computed. 
.NET Framework net461 was computed.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
MonoAndroid monoandroid was computed. 
MonoMac monomac was computed. 
MonoTouch monotouch was computed. 
Tizen tizen40 was computed.  tizen60 was computed. 
Xamarin.iOS xamarinios was computed. 
Xamarin.Mac xamarinmac was computed. 
Xamarin.TVOS xamarintvos was computed. 
Xamarin.WatchOS xamarinwatchos was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
4.0.0 190 8/14/2024
4.0.0-priview-1723658928 99 8/14/2024
4.0.0-priview-1723657903 96 8/14/2024
0.1.2 360 12/15/2021
0.1.1 287 12/8/2021

- 更新NuGet依赖

 |                     包名                     |      版本变化      |
 |:-------------------------------------------:|:-----------------:|
 | `Rougamo.Fody`                              | `1.0.1 -> 4.0.0`  |
 | `Rougamo.APM.Abstractions`                  | `0.1.0 -> 4.0.0`  |
 | `Microsoft.SourceLink.GitHub`               | `1.1.1 -> 8.0.0`  |
 | `OpenTelemetry`                             | `1.1.0 -> 1.3.2+` |
 | `Microsoft.Extensions.Options`              | `3.0.0 -> 3.1.0+` |
 | `Microsoft.Extensions.Hosting.Abstractions` | `3.0.0 -> 3.1.0+` |

- 新增多个SDK支持，不同SDK将采用不同版本NuGet

---