Jaahas.OpenTelemetry.Extensions
2.3.0
dotnet add package Jaahas.OpenTelemetry.Extensions --version 2.3.0
NuGet\Install-Package Jaahas.OpenTelemetry.Extensions -Version 2.3.0
<PackageReference Include="Jaahas.OpenTelemetry.Extensions" Version="2.3.0" />
paket add Jaahas.OpenTelemetry.Extensions --version 2.3.0
#r "nuget: Jaahas.OpenTelemetry.Extensions, 2.3.0"
// Install Jaahas.OpenTelemetry.Extensions as a Cake Addin #addin nuget:?package=Jaahas.OpenTelemetry.Extensions&version=2.3.0 // Install Jaahas.OpenTelemetry.Extensions as a Cake Tool #tool nuget:?package=Jaahas.OpenTelemetry.Extensions&version=2.3.0
About
Jaahas.OpenTelemetry.Extensions defines extension methods to simplify the configuration of OpenTelemetry in .NET applications.
Registering Service Metadata via Attributes
You can annotate an assembly with the [Jaahas.OpenTelemetry.OpenTelemetryService]
attribute to mark it as containing an OpenTelemetry service:
[assembly: Jaahas.OpenTelemetry.OpenTelemetryService("my-service")]
When you construct your OpenTelemetry ResourceBuilder
, you can easily register the service with the resource builder as follows:
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddService(typeof(MyType).Assembly));
This will register the service using the name specified in the attribute, and the version of the assembly in MAJOR.MINOR.PATCH
format. You can also optionally specify a service instance ID:
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddService(typeof(MyType).Assembly, "some-id"));
If your entry assembly is annotated with an [Jaahas.OpenTelemetry.OpenTelemetryService]
attribute you can also use the AddDefaultService
extension method to simplify registration:
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddDefaultService());
Configuring a Multi-Signal OpenTelemetry Protocol (OTLP) Exporter
Jaahas.OpenTelemetry.Extensions makes it easy to configure an OpenTelemetry Protocol (OTLP) exporter via the .NET configuration system or by manually configuring exporter options. The exporter can be configured to export traces, metrics or logs, or any combination of the three:
// Assumes that configuration is an instance of your application's
// IConfiguration.
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddService(typeof(MyType).Assembly))
// TODO: configure trace and metrics instrumentation.
.AddOtlpExporter(configuration);
By default, the AddOtlpExporter
extension method will bind against a configuration section named OpenTelemetry:Exporters:OTLP
to configure an instance of JaahasOtlpExporterOptions.
The default configuration used is as follows:
{
"OpenTelemetry": {
"Exporters": {
"OTLP": {
// OTLP exporter is disabled by default.
"Enabled": false,
// Protocol can be "Grpc" or "HttpProtobuf".
"Protocol": "Grpc",
// Endpoint is inferred from the export protocol if not
// specified.
"Endpoint": null,
// The OpenTelemetry signals to export. Possible values are:
// Traces
// Logs
// Metrics
// TracesAndLogsAndMetrics
// TracesAndLogs
// TracesAndMetrics
// LogsAndMetrics
"Signals": "Traces",
// Optional headers to include in export requests (such as API
// keys) are specified as a JSON dictionary.
"Headers": null,
// Timeout for export requests.
"Timeout": "00:00:10",
// When true and the Protocol is "HttpProtobuf", the exporter
// ensures that the standard OTLP signal path is appended to
// the endpoint when exporting a given signal type. The
// standard OTLP signal path is "/v1/traces", "/v1/logs", and
// "/v1/metrics" for traces, logs, and metrics, respectively.
"AppendSignalPathToEndpoint": true
}
}
}
}
Note that the default configuration means that the OTLP exporter is disabled by default and calls to the AddOtlpExporter
extension method have no effect until it is enabled.
It is also possible to configure the exporter by providing your own JaahasOtlpExporterOptions
instance, or by providing an Action<JaahasOtlpExporterOptions>
that can be used to configure the options:
// Configure exporter options manually.
var exporterOptions = new JaahasOtlpExporterOptions() {
Enabled = true,
Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf,
Signals = OtlpExporterSignalKind.TracesAndLogs,
};
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddService(typeof(MyType).Assembly))
// TODO: configure trace and metrics instrumentation.
.AddOtlpExporter(exporterOptions);
// Configure exporter options manually via callback.
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddService(typeof(MyType).Assembly))
// TODO: configure trace and metrics instrumentation.
.AddOtlpExporter(exporterOptions => {
exporterOptions.Enabled = true;
exporterOptions.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.HttpProtobuf;
exporterOptions.Signals = OtlpExporterSignalKind.TracesAndLogs;
});
Example Configuration: Seq
Seq can ingest OTLP traces and logs. To export these signals to a local Seq instance using the HTTP/Protobuf export format, you could use the following configuration:
{
"OpenTelemetry": {
"Exporters": {
"OTLP": {
"Enabled": true,
"Protocol": "HttpProtobuf",
"Endpoint": "http://localhost:5341/ingest/otlp",
"Signals": "TracesAndLogs",
"Headers": {
"X-Seq-ApiKey": "your-api-key"
}
}
}
}
}
Example Configuration: Jaeger
Jaeger can ingest OTLP traces. To export traces to a local Jaeger instance using the HTTP/Protobuf export format, you could use the following configuration:
{
"OpenTelemetry": {
"Exporters": {
"OTLP": {
"Enabled": true,
"Protocol": "HttpProtobuf",
"Signals": "Traces"
}
}
}
}
Jaeger's OTLP trace receivers listen on the standard OTLP exporter endpoints i.e. port 4317 for gRPC and port 4318 for HTTP/Protobuf. When the Endpoint
setting is omitted from the configuration, the exporter will default to the standard port for the export format on localhost
.
Configuring Multiple Exporters
You can also configure multiple named exporters by providing a name to the AddOtlpExporter
extension method. For example, if you wanted to export logs to Seq and traces to Jaeger:
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddService(typeof(MyType).Assembly))
// TODO: configure trace and metrics instrumentation.
.AddOtlpExporter("seq",
configuration,
configurationSectionName: "OpenTelemetry:Exporters:OTLP:Seq")
.AddOtlpExporter("jaeger",
configuration,
configurationSectionName: "OpenTelemetry:Exporters:OTLP:Jaeger");
You would then configure the exporters in your appsettings.json
file as follows:
{
"OpenTelemetry": {
"Exporters": {
"OTLP": {
"Seq": {
"Enabled": true,
"Protocol": "HttpProtobuf",
"Endpoint": "http://localhost:5341/ingest/otlp",
"Signals": "Logs",
"Headers": {
"X-Seq-ApiKey": "your-api-key"
}
},
"Jaeger": {
"Enabled": true,
"Protocol": "HttpProtobuf",
"Signals": "Traces"
}
}
}
}
}
Product | Versions Compatible and additional computed target framework versions. |
---|---|
.NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. 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 was computed. 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. |
-
.NETStandard 2.0
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.9.0)
- OpenTelemetry.Extensions.Hosting (>= 1.9.0)
-
net8.0
- OpenTelemetry.Exporter.OpenTelemetryProtocol (>= 1.9.0)
- OpenTelemetry.Extensions.Hosting (>= 1.9.0)
NuGet packages
This package is not used by any NuGet packages.
GitHub repositories
This package is not used by any popular GitHub repositories.