Add & use ConfigureResource API. (#3307)

docs/logs/customizing-the-sdk/Program.cs

@@ -30,9 +30,7 @@ public static void Main()
             builder.AddOpenTelemetry(options =>
             {
                 options.IncludeScopes = true;
-                options.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(
-                    serviceName: "MyService",
-                    serviceVersion: "1.0.0"));
+                options.ConfigureResource(r => r.AddService(serviceName: "MyService", serviceVersion: "1.0.0"));
                 options.AddConsoleExporter();
             });
         });

docs/logs/customizing-the-sdk/README.md

@@ -52,26 +52,25 @@ var loggerFactory = LoggerFactory.Create(builder =>
 
 For more information on Processors, please review [Extending the SDK](../extending-the-sdk/README.md#processor)
 
-### SetResourceBuilder
+### ConfigureResource
 
 [Resource](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/sdk.md)
 is the immutable representation of the entity producing the telemetry.
 If no `Resource` is explicitly configured, the default is to use a resource
 indicating this [Telemetry
 SDK](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/resource/semantic_conventions#telemetry-sdk).
-The `SetResourceBuilder` method on `OpenTelemetryLoggerOptions` can be used to
-set a single `ResourceBuilder`. If `SetResourceBuilder` is called multiple
-times, only the last is kept. It is not possible to change the resource builder
+The `ConfigureResource` method on `OpenTelemetryLoggerOptions` can be used to
+configure the `ResourceBuilder`. It is not possible to change the resources
 *after* creating the `LoggerFactory`.
 
-The snippet below shows configuring a custom `ResourceBuilder` to the provider.
+The snippet below shows configuring the `ResourceBuilder` of the provider.
 
 ```csharp
 var loggerFactory = LoggerFactory.Create(builder =>
 {
     builder.AddOpenTelemetry(options =>
     {
-        options.SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(
+        options.ConfigureResource(r => r.AddService(
             serviceName: "MyService",
             serviceVersion: "1.0.0"
             ));

examples/AspNetCore/Program.cs

@@ -24,27 +24,28 @@
 
 var builder = WebApplication.CreateBuilder(args);
 
-var serviceName = "AspNetCoreExampleService";
-
 // OpenTelemetry
 var assemblyVersion = Assembly.GetExecutingAssembly().GetName().Version?.ToString() ?? "unknown";
 
 // Switch between Zipkin/Jaeger/OTLP by setting UseExporter in appsettings.json.
 var tracingExporter = builder.Configuration.GetValue<string>("UseTracingExporter").ToLowerInvariant();
 
-var resourceBuilder = tracingExporter switch
+var serviceName = tracingExporter switch
 {
-    "jaeger" => ResourceBuilder.CreateDefault().AddService(builder.Configuration.GetValue<string>("Jaeger:ServiceName"), serviceVersion: assemblyVersion, serviceInstanceId: Environment.MachineName),
-    "zipkin" => ResourceBuilder.CreateDefault().AddService(builder.Configuration.GetValue<string>("Zipkin:ServiceName"), serviceVersion: assemblyVersion, serviceInstanceId: Environment.MachineName),
-    "otlp" => ResourceBuilder.CreateDefault().AddService(builder.Configuration.GetValue<string>("Otlp:ServiceName"), serviceVersion: assemblyVersion, serviceInstanceId: Environment.MachineName),
-    _ => ResourceBuilder.CreateDefault().AddService(serviceName, serviceVersion: assemblyVersion, serviceInstanceId: Environment.MachineName),
+    "jaeger" => builder.Configuration.GetValue<string>("Jaeger:ServiceName"),
+    "zipkin" => builder.Configuration.GetValue<string>("Zipkin:ServiceName"),
+    "otlp" => builder.Configuration.GetValue<string>("Otlp:ServiceName"),
+    _ => "AspNetCoreExampleService",
 };
 
+Action<ResourceBuilder> configureResource = r => r.AddService(
+    serviceName, serviceVersion: assemblyVersion, serviceInstanceId: Environment.MachineName);
+
 // Traces
 builder.Services.AddOpenTelemetryTracing(options =>
 {
     options
-        .SetResourceBuilder(resourceBuilder)
+        .ConfigureResource(configureResource)
         .SetSampler(new AlwaysOnSampler())
         .AddHttpClientInstrumentation()
         .AddAspNetCoreInstrumentation();
@@ -88,7 +89,7 @@
 
 builder.Logging.AddOpenTelemetry(options =>
 {
-    options.SetResourceBuilder(resourceBuilder);
+    options.ConfigureResource(configureResource);
     var logExporter = builder.Configuration.GetValue<string>("UseLogExporter").ToLowerInvariant();
     switch (logExporter)
     {
@@ -114,7 +115,7 @@
 // Metrics
 builder.Services.AddOpenTelemetryMetrics(options =>
 {
-    options.SetResourceBuilder(resourceBuilder)
+    options.ConfigureResource(configureResource)
         .AddHttpClientInstrumentation()
         .AddAspNetCoreInstrumentation();
 

examples/Console/TestConsoleExporter.cs

@@ -39,7 +39,7 @@ private static object RunWithActivitySource()
             // and use Console exporter.
             using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                     .AddSource("Samples.SampleClient", "Samples.SampleServer")
-                    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("console-test"))
+                    .ConfigureResource(res => res.AddService("console-test"))
                     .AddProcessor(new MyProcessor()) // This must be added before ConsoleExporter
                     .AddConsoleExporter()
                     .Build();

examples/Console/TestHttpClient.cs

@@ -34,7 +34,7 @@ internal static object Run()
 
             using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                 .AddHttpClientInstrumentation()
-                .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("http-service-example"))
+                .ConfigureResource(r => r.AddService("http-service-example"))
                 .AddSource("http-client-test")
                 .AddConsoleExporter()
                 .Build();

examples/Console/TestInMemoryExporter.cs

@@ -51,7 +51,7 @@ private static void RunWithActivitySource(ICollection<Activity> exportedItems)
             // and use InMemory exporter.
             using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                     .AddSource("Samples.SampleClient", "Samples.SampleServer")
-                    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("inmemory-test"))
+                    .ConfigureResource(r => r.AddService("inmemory-test"))
                     .AddInMemoryExporter(exportedItems)
                     .Build();
 

examples/Console/TestJaegerExporter.cs

@@ -56,7 +56,7 @@ internal static object RunWithActivity(string host, int port)
             // Enable OpenTelemetry for the sources "Samples.SampleServer" and "Samples.SampleClient"
             // and use the Jaeger exporter.
             using var tracerProvider = Sdk.CreateTracerProviderBuilder()
-                    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("jaeger-test"))
+                    .ConfigureResource(r => r.AddService("jaeger-test"))
                     .AddSource("Samples.SampleClient", "Samples.SampleServer")
                     .AddJaegerExporter(o =>
                     {

examples/Console/TestMetrics.cs

@@ -33,7 +33,7 @@ internal static object Run(MetricsOptions options)
             using var meter = new Meter("TestMeter");
 
             var providerBuilder = Sdk.CreateMeterProviderBuilder()
-                .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("myservice"))
+                .ConfigureResource(r => r.AddService("myservice"))
                 .AddMeter(meter.Name); // All instruments from this meter are enabled.
 
             if (options.UseExporter.Equals("otlp", StringComparison.OrdinalIgnoreCase))

examples/Console/TestOTelShimWithConsoleExporter.cs

@@ -28,7 +28,7 @@ internal static object Run(OpenTelemetryShimOptions options)
             // and use a single pipeline with a custom MyProcessor, and Console exporter.
             using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                     .AddSource("MyCompany.MyProduct.MyWebServer")
-                    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MyServiceName"))
+                    .ConfigureResource(r => r.AddService("MyServiceName"))
                     .AddConsoleExporter()
                     .Build();
 

examples/Console/TestOpenTracingShim.cs

@@ -31,7 +31,7 @@ internal static object Run(OpenTracingShimOptions options)
             // and use Console exporter.
             using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                     .AddSource("MyCompany.MyProduct.MyWebServer")
-                    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("MyServiceName"))
+                    .ConfigureResource(r => r.AddService("MyServiceName"))
                     .AddConsoleExporter()
                     .Build();
 

examples/Console/TestOtlpExporter.cs

@@ -71,7 +71,7 @@ private static object RunWithActivitySource(string endpoint, string protocol)
             // and use OTLP exporter.
             using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                     .AddSource("Samples.SampleClient", "Samples.SampleServer")
-                    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("otlp-test"))
+                    .ConfigureResource(r => r.AddService("otlp-test"))
                     .AddOtlpExporter(opt =>
                     {
                         // If endpoint was not specified, the proper one will be selected according to the protocol.

examples/Console/TestZipkinExporter.cs

@@ -39,7 +39,7 @@ internal static object Run(string zipkinUri)
             // and use the Zipkin exporter.
             using var tracerProvider = Sdk.CreateTracerProviderBuilder()
                     .AddSource("Samples.SampleClient", "Samples.SampleServer")
-                    .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService("zipkin-test"))
+                    .ConfigureResource(r => r.AddService("zipkin-test"))
                     .AddZipkinExporter(o =>
                     {
                         o.Endpoint = new Uri(zipkinUri);

examples/GrpcService/Startup.cs

@@ -45,7 +45,7 @@ public void ConfigureServices(IServiceCollection services)
             {
                 case "jaeger":
                     services.AddOpenTelemetryTracing((builder) => builder
-                        .SetResourceBuilder(ResourceBuilder.CreateDefault().AddService(this.Configuration.GetValue<string>("Jaeger:ServiceName")))
+                        .ConfigureResource(r => r.AddService(this.Configuration.GetValue<string>("Jaeger:ServiceName")))
                         .AddAspNetCoreInstrumentation()
                         .AddJaegerExporter(jaegerOptions =>
                         {

src/OpenTelemetry/.publicApi/net462/PublicAPI.Unshipped.txt

@@ -9,4 +9,7 @@ OpenTelemetry.Logs.LogRecord.TraceId.set -> void
 OpenTelemetry.Logs.LogRecord.TraceState.set -> void
 OpenTelemetry.Logs.OpenTelemetryLoggerProvider.ForceFlush(int timeoutMilliseconds = -1) -> bool
 OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider() -> void
-OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider(System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>! configure) -> void
+OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider(System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>! configure) -> void
+OpenTelemetry.Logs.OpenTelemetryLoggerOptions.ConfigureResource(System.Action<OpenTelemetry.Resources.ResourceBuilder!>! configure) -> OpenTelemetry.Logs.OpenTelemetryLoggerOptions!
+~static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.ConfigureResource(this OpenTelemetry.Metrics.MeterProviderBuilder meterProviderBuilder, System.Action<OpenTelemetry.Resources.ResourceBuilder> configure) -> OpenTelemetry.Metrics.MeterProviderBuilder
+~static OpenTelemetry.Trace.TracerProviderBuilderExtensions.ConfigureResource(this OpenTelemetry.Trace.TracerProviderBuilder tracerProviderBuilder, System.Action<OpenTelemetry.Resources.ResourceBuilder> configure) -> OpenTelemetry.Trace.TracerProviderBuilder

src/OpenTelemetry/.publicApi/net6.0/PublicAPI.Unshipped.txt

@@ -7,6 +7,9 @@ OpenTelemetry.Logs.LogRecord.Timestamp.set -> void
 OpenTelemetry.Logs.LogRecord.TraceFlags.set -> void
 OpenTelemetry.Logs.LogRecord.TraceId.set -> void
 OpenTelemetry.Logs.LogRecord.TraceState.set -> void
+OpenTelemetry.Logs.OpenTelemetryLoggerOptions.ConfigureResource(System.Action<OpenTelemetry.Resources.ResourceBuilder!>! configure) -> OpenTelemetry.Logs.OpenTelemetryLoggerOptions!
 OpenTelemetry.Logs.OpenTelemetryLoggerProvider.ForceFlush(int timeoutMilliseconds = -1) -> bool
 OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider() -> void
-OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider(System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>! configure) -> void
+OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider(System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>! configure) -> void
+~static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.ConfigureResource(this OpenTelemetry.Metrics.MeterProviderBuilder meterProviderBuilder, System.Action<OpenTelemetry.Resources.ResourceBuilder> configure) -> OpenTelemetry.Metrics.MeterProviderBuilder
+~static OpenTelemetry.Trace.TracerProviderBuilderExtensions.ConfigureResource(this OpenTelemetry.Trace.TracerProviderBuilder tracerProviderBuilder, System.Action<OpenTelemetry.Resources.ResourceBuilder> configure) -> OpenTelemetry.Trace.TracerProviderBuilder

src/OpenTelemetry/.publicApi/netstandard2.0/PublicAPI.Unshipped.txt

@@ -9,4 +9,7 @@ OpenTelemetry.Logs.LogRecord.TraceId.set -> void
 OpenTelemetry.Logs.LogRecord.TraceState.set -> void
 OpenTelemetry.Logs.OpenTelemetryLoggerProvider.ForceFlush(int timeoutMilliseconds = -1) -> bool
 OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider() -> void
-OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider(System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>! configure) -> void
+OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider(System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>! configure) -> void
+OpenTelemetry.Logs.OpenTelemetryLoggerOptions.ConfigureResource(System.Action<OpenTelemetry.Resources.ResourceBuilder!>! configure) -> OpenTelemetry.Logs.OpenTelemetryLoggerOptions!
+~static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.ConfigureResource(this OpenTelemetry.Metrics.MeterProviderBuilder meterProviderBuilder, System.Action<OpenTelemetry.Resources.ResourceBuilder> configure) -> OpenTelemetry.Metrics.MeterProviderBuilder
+~static OpenTelemetry.Trace.TracerProviderBuilderExtensions.ConfigureResource(this OpenTelemetry.Trace.TracerProviderBuilder tracerProviderBuilder, System.Action<OpenTelemetry.Resources.ResourceBuilder> configure) -> OpenTelemetry.Trace.TracerProviderBuilder

src/OpenTelemetry/.publicApi/netstandard2.1/PublicAPI.Unshipped.txt

@@ -7,6 +7,9 @@ OpenTelemetry.Logs.LogRecord.Timestamp.set -> void
 OpenTelemetry.Logs.LogRecord.TraceFlags.set -> void
 OpenTelemetry.Logs.LogRecord.TraceId.set -> void
 OpenTelemetry.Logs.LogRecord.TraceState.set -> void
+OpenTelemetry.Logs.OpenTelemetryLoggerOptions.ConfigureResource(System.Action<OpenTelemetry.Resources.ResourceBuilder!>! configure) -> OpenTelemetry.Logs.OpenTelemetryLoggerOptions!
 OpenTelemetry.Logs.OpenTelemetryLoggerProvider.ForceFlush(int timeoutMilliseconds = -1) -> bool
 OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider() -> void
-OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider(System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>! configure) -> void
+OpenTelemetry.Logs.OpenTelemetryLoggerProvider.OpenTelemetryLoggerProvider(System.Action<OpenTelemetry.Logs.OpenTelemetryLoggerOptions!>! configure) -> void
+~static OpenTelemetry.Metrics.MeterProviderBuilderExtensions.ConfigureResource(this OpenTelemetry.Metrics.MeterProviderBuilder meterProviderBuilder, System.Action<OpenTelemetry.Resources.ResourceBuilder> configure) -> OpenTelemetry.Metrics.MeterProviderBuilder
+~static OpenTelemetry.Trace.TracerProviderBuilderExtensions.ConfigureResource(this OpenTelemetry.Trace.TracerProviderBuilder tracerProviderBuilder, System.Action<OpenTelemetry.Resources.ResourceBuilder> configure) -> OpenTelemetry.Trace.TracerProviderBuilder

src/OpenTelemetry/CHANGELOG.md

@@ -38,6 +38,10 @@ Released 2022-June-1
 * Swallow `ObjectDisposedException` in `BatchExportProcessor` and
   `PeriodicExportingMetricReader`.
   ([#3291](https://github.com/open-telemetry/opentelemetry-dotnet/pull/3291))
+* Add `ConfigureResource` which can replace SetResourceBuilder more succinctly
+  in most cases and has greater flexibility (applies to
+  TracerProvicerBuilder, MeterProviderBuilder, OpenTelemetryLoggingOptions).
+  ([#3307](https://github.com/open-telemetry/opentelemetry-dotnet/pull/3307))
 
 ## 1.3.0-beta.2
 

src/OpenTelemetry/Logs/OpenTelemetryLoggerOptions.cs

@@ -16,6 +16,7 @@
 
 #nullable enable
 
+using System;
 using System.Collections.Generic;
 using OpenTelemetry.Internal;
 using OpenTelemetry.Resources;
@@ -73,6 +74,8 @@ public OpenTelemetryLoggerOptions AddProcessor(BaseProcessor<LogRecord> processo
         /// <summary>
         /// Sets the <see cref="ResourceBuilder"/> from which the Resource associated with
         /// this provider is built from. Overwrites currently set ResourceBuilder.
+        /// You should usually use <see cref="ConfigureResource(Action{ResourceBuilder})"/> instead
+        /// (call <see cref="ResourceBuilder.Clear"/> if desired).
         /// </summary>
         /// <param name="resourceBuilder"><see cref="ResourceBuilder"/> from which Resource will be built.</param>
         /// <returns>Returns <see cref="OpenTelemetryLoggerOptions"/> for chaining.</returns>
@@ -83,5 +86,18 @@ public OpenTelemetryLoggerOptions SetResourceBuilder(ResourceBuilder resourceBui
             this.ResourceBuilder = resourceBuilder;
             return this;
         }
+
+        /// <summary>
+        /// Modify the <see cref="ResourceBuilder"/> from which the Resource associated with
+        /// this provider is built from in-place.
+        /// </summary>
+        /// <param name="configure">An action which modifies the provided <see cref="ResourceBuilder"/> in-place.</param>
+        /// <returns>Returns <see cref="OpenTelemetryLoggerOptions"/> for chaining.</returns>
+        public OpenTelemetryLoggerOptions ConfigureResource(Action<ResourceBuilder> configure)
+        {
+            Guard.ThrowIfNull(configure, nameof(configure));
+            configure(this.ResourceBuilder);
+            return this;
+        }
     }
 }

src/OpenTelemetry/Metrics/MeterProviderBuilderBase.cs

@@ -45,6 +45,16 @@ protected MeterProviderBuilderBase()
 
         internal List<MetricReader> MetricReaders { get; } = new List<MetricReader>();
 
+        internal ResourceBuilder ResourceBuilder
+        {
+            get => this.resourceBuilder;
+            set
+            {
+                Debug.Assert(value != null, $"{nameof(this.ResourceBuilder)} must not be set to null");
+                this.resourceBuilder = value;
+            }
+        }
+
         /// <inheritdoc />
         public override MeterProviderBuilder AddInstrumentation<TInstrumentation>(Func<TInstrumentation> instrumentationFactory)
         {
@@ -126,14 +136,6 @@ internal MeterProviderBuilder SetMaxMetricPointsPerMetricStream(int maxMetricPoi
             return this;
         }
 
-        internal MeterProviderBuilder SetResourceBuilder(ResourceBuilder resourceBuilder)
-        {
-            Debug.Assert(resourceBuilder != null, $"{nameof(resourceBuilder)} must not be null");
-
-            this.resourceBuilder = resourceBuilder;
-            return this;
-        }
-
         /// <summary>
         /// Run the configured actions to initialize the <see cref="MeterProvider"/>.
         /// </summary>