Jaahas.OpenTelemetry.Extensions defines extension methods to simplify the configuration of OpenTelemetry in .NET applications.
Add the Jaahas.OpenTelemetry.Extensions NuGet package to your project.
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());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.
You can configure the exporter by manually providing a JaahasOtlpExporterOptions if preferred:
// 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);You can also configure the exporter by providing an Action<JaahasOtlpExporterOptions> that can be used to configure the options:
// 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;
});You can also specify a delegate to configure the options after the configuration section has been bound:
// Bind configuration and then update via callback.
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddService(typeof(MyType).Assembly))
// TODO: configure trace and metrics instrumentation.
.AddOtlpExporter(configuration, configure: exporterOptions => {
exporterOptions.Enabled = true;
});You can register a custom IConfigureOptions<JaahasOtlpExporterOptions>, IConfigureNamedOptions<JaahasOtlpExporterOptions> or IPostConfigureOptions<JaahasOtlpExporterOptions> as a singleton service to configure or override the exporter options. This is useful when you need to perform more complex configuration that cannot be achieved via the configuration system alone.
// Perform configuration via IPostConfigureOptions<T>.
services.AddSingleton<IPostConfigureOptions<JaahasOtlpExporterOptions>, MyPostConfigureOptions>();
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddService(typeof(MyType).Assembly))
// TODO: configure trace and metrics instrumentation.
.AddOtlpExporter();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"
}
}
}
}
}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.
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 could 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"
}
}
}
}
}Alternatively, you can also use the AddNamedOtlpExporters extension method to automatically configure a named exporter for every child section found in a given configuration section:
services.AddOpenTelemetry()
.ConfigureResource(builder => builder.AddService(typeof(MyType).Assembly))
// TODO: configure trace and metrics instrumentation.
.AddNamedOtlpExporters(
configuration,
configurationSectionName: "OpenTelemetry:Exporters:OTLP"));This approach is particularly useful when the number and names of the exporters is not known at compile time, as it allows additional exporters to be added solely via a configuration change.
The repository uses Cake for cross-platform build automation. The build script allows for metadata such as a build counter to be specified when called by a continuous integration system such as TeamCity.
A build can be run from the command line using the build.ps1 PowerShell script or the build.sh Bash script. For documentation about the available build script parameters, see build.cake.
To generate a Software Bill of Materials (SBOM) for the repository in CycloneDX XML format, run build.ps1 or build.sh with the --target BillOfMaterials parameter.
The resulting SBOM is written to the artifacts/bom folder.