Add support for OTEL_BSP_EXPORT_* environmental variables (#2219)

src/OpenTelemetry.Exporter.Jaeger/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+* `JaegerExporterOptions.BatchExportProcessorOptions` is initialized with
+  `BatchExportActivityProcessorOptions` which supports field value overriding
+  using `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_EXPORT_TIMEOUT`,
+  `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`
+  envionmental variables as defined in the
+  [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.5.0/specification/sdk-environment-variables.md#batch-span-processor).
+  ([#2219](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2219))
+
 ## 1.2.0-alpha2
 
 Released 2021-Aug-24

src/OpenTelemetry.Exporter.Jaeger/JaegerExporterOptions.cs

@@ -18,6 +18,7 @@
 using System.Diagnostics;
 using System.Security;
 using OpenTelemetry.Exporter.Jaeger.Implementation;
+using OpenTelemetry.Trace;
 
 namespace OpenTelemetry.Exporter
 {
@@ -82,6 +83,6 @@ public JaegerExporterOptions()
         /// <summary>
         /// Gets or sets the BatchExportProcessor options. Ignored unless ExportProcessorType is BatchExporter.
         /// </summary>
-        public BatchExportProcessorOptions<Activity> BatchExportProcessorOptions { get; set; } = new BatchExportProcessorOptions<Activity>();
+        public BatchExportProcessorOptions<Activity> BatchExportProcessorOptions { get; set; } = new BatchExportActivityProcessorOptions();
     }
 }

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+* `OtlpExporterOptions.BatchExportProcessorOptions` is initialized with
+  `BatchExportActivityProcessorOptions` which supports field value overriding
+  using `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_EXPORT_TIMEOUT`,
+  `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`
+  envionmental variables as defined in the
+  [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.5.0/specification/sdk-environment-variables.md#batch-span-processor).
+  ([#2219](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2219))
+
 ## 1.2.0-alpha2
 
 Released 2021-Aug-24

src/OpenTelemetry.Exporter.OpenTelemetryProtocol/OtlpExporterOptions.cs

@@ -18,6 +18,7 @@
 using System.Diagnostics;
 using System.Security;
 using OpenTelemetry.Exporter.OpenTelemetryProtocol.Implementation;
+using OpenTelemetry.Trace;
 
 namespace OpenTelemetry.Exporter
 {
@@ -104,7 +105,7 @@ public OtlpExporterOptions()
         /// <summary>
         /// Gets or sets the BatchExportProcessor options. Ignored unless ExportProcessorType is Batch.
         /// </summary>
-        public BatchExportProcessorOptions<Activity> BatchExportProcessorOptions { get; set; } = new BatchExportProcessorOptions<Activity>();
+        public BatchExportProcessorOptions<Activity> BatchExportProcessorOptions { get; set; } = new BatchExportActivityProcessorOptions();
 
         /// <summary>
         /// Gets or sets the metric export interval in milliseconds. The default value is 1000 milliseconds.

src/OpenTelemetry.Exporter.Zipkin/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Unreleased
 
+* `ZipkinExporterOptions.BatchExportProcessorOptions` is initialized with
+  `BatchExportActivityProcessorOptions` which supports field value overriding
+  using `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_EXPORT_TIMEOUT`,
+  `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`
+  envionmental variables as defined in the
+  [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.5.0/specification/sdk-environment-variables.md#batch-span-processor).
+  ([#2219](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2219))
+
 ## 1.2.0-alpha2
 
 Released 2021-Aug-24

src/OpenTelemetry.Exporter.Zipkin/ZipkinExporterOptions.cs

@@ -17,6 +17,7 @@
 using System;
 using System.Diagnostics;
 using OpenTelemetry.Exporter.Zipkin.Implementation;
+using OpenTelemetry.Trace;
 
 namespace OpenTelemetry.Exporter
 {
@@ -70,6 +71,6 @@ public ZipkinExporterOptions()
         /// <summary>
         /// Gets or sets the BatchExportProcessor options. Ignored unless ExportProcessorType is BatchExporter.
         /// </summary>
-        public BatchExportProcessorOptions<Activity> BatchExportProcessorOptions { get; set; } = new BatchExportProcessorOptions<Activity>();
+        public BatchExportProcessorOptions<Activity> BatchExportProcessorOptions { get; set; } = new BatchExportActivityProcessorOptions();
     }
 }

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

@@ -0,0 +1,2 @@
+OpenTelemetry.Trace.BatchExportActivityProcessorOptions
+OpenTelemetry.Trace.BatchExportActivityProcessorOptions.BatchExportActivityProcessorOptions() -> void

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

@@ -0,0 +1,2 @@
+OpenTelemetry.Trace.BatchExportActivityProcessorOptions
+OpenTelemetry.Trace.BatchExportActivityProcessorOptions.BatchExportActivityProcessorOptions() -> void

src/OpenTelemetry/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+* Add `BatchExportActivityProcessorOptions` which supports field value overriding
+  using `OTEL_BSP_SCHEDULE_DELAY`, `OTEL_BSP_EXPORT_TIMEOUT`,
+  `OTEL_BSP_MAX_QUEUE_SIZE`, `OTEL_BSP_MAX_EXPORT_BATCH_SIZE`
+  envionmental variables as defined in the
+  [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.5.0/specification/sdk-environment-variables.md#batch-span-processor).
+  ([#2219](https://github.com/open-telemetry/opentelemetry-dotnet/pull/2219))
+
 ## 1.2.0-alpha2
 
 Released 2021-Aug-24

src/OpenTelemetry/Internal/OpenTelemetrySdkEventSource.cs

@@ -21,6 +21,7 @@
 #endif
 using System.Diagnostics;
 using System.Diagnostics.Tracing;
+using System.Security;
 
 namespace OpenTelemetry.Internal
 {
@@ -125,6 +126,15 @@ public void TracerProviderException(string evnt, Exception ex)
             }
         }
 
+        [NonEvent]
+        public void MissingPermissionsToReadEnvironmentVariable(SecurityException ex)
+        {
+            if (this.IsEnabled(EventLevel.Warning, EventKeywords.All))
+            {
+                this.MissingPermissionsToReadEnvironmentVariable(ex.ToInvariantString());
+            }
+        }
+
         [Event(1, Message = "Span processor queue size reached maximum. Throttling spans.", Level = EventLevel.Warning)]
         public void SpanProcessorQueueIsExhausted()
         {
@@ -287,6 +297,18 @@ public void TracerProviderException(string evnt, string ex)
             this.WriteEvent(28, evnt, ex);
         }
 
+        [Event(29, Message = "Failed to parse environment variable: '{0}', value: '{1}'.", Level = EventLevel.Warning)]
+        public void FailedToParseEnvironmentVariable(string name, string value)
+        {
+            this.WriteEvent(29, name, value);
+        }
+
+        [Event(30, Message = "Missing permissions to read environment variable: '{0}'", Level = EventLevel.Warning)]
+        public void MissingPermissionsToReadEnvironmentVariable(string exception)
+        {
+            this.WriteEvent(30, exception);
+        }
+
 #if DEBUG
         public class OpenTelemetryEventListener : EventListener
         {

src/OpenTelemetry/README.md

@@ -202,10 +202,24 @@ purposes, the SDK provides the following built-in processors:
 * [BatchExportProcessor<T>](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#batching-processor)
   : This is an exporting processor which batches the telemetry before sending to
   the configured exporter.
+
+  The following environment variables can be used to override the default
+  values of the `BatchExportActivityProcessorOptions`.
+
+  <!-- markdownlint-disable MD013 -->
+  | Environment variable             | `BatchExportActivityProcessorOptions` property |
+  | -------------------------------- | ---------------------------------------------- |
+  | `OTEL_BSP_SCHEDULE_DELAY`        | `ScheduledDelayMilliseconds`                   |
+  | `OTEL_BSP_EXPORT_TIMEOUT`        | `ExporterTimeoutMilliseconds`                  |
+  | `OTEL_BSP_MAX_QUEUE_SIZE`        | `MaxQueueSize`                                 |
+  | `OTEL_BSP_MAX_EXPORT_BATCH_SIZE` | `MaxExportBatchSizeEnvVarKey`                  |
+  <!-- markdownlint-enable MD013 -->
+
 * [CompositeProcessor&lt;T&gt;](../../src/OpenTelemetry/CompositeProcessor.cs)
   : This is a processor which can be composed from multiple processors. This is
   typically used to construct multiple processing pipelines, each ending with
   its own exporter.
+
 * [SimpleExportProcessor&lt;T&gt;](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/trace/sdk.md#simple-processor)
   : This is an exporting processor which passes telemetry to the configured
   exporter without any batching.

src/OpenTelemetry/Trace/BatchExportActivityProcessorOptions.cs

@@ -0,0 +1,91 @@
+// <copyright file="BatchExportActivityProcessorOptions.cs" company="OpenTelemetry Authors">
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+using System.Diagnostics;
+using System.Security;
+using OpenTelemetry.Internal;
+
+namespace OpenTelemetry.Trace
+{
+    public class BatchExportActivityProcessorOptions : BatchExportProcessorOptions<Activity>
+    {
+        internal const string MaxQueueSizeEnvVarKey = "OTEL_BSP_MAX_QUEUE_SIZE";
+
+        internal const string MaxExportBatchSizeEnvVarKey = "OTEL_BSP_MAX_EXPORT_BATCH_SIZE";
+
+        internal const string ExporterTimeoutEnvVarKey = "OTEL_BSP_EXPORT_TIMEOUT";
+
+        internal const string ScheduledDelayEnvVarKey = "OTEL_BSP_SCHEDULE_DELAY";
+
+        public BatchExportActivityProcessorOptions()
+        {
+            int value;
+
+            if (TryLoadEnvVarInt(ExporterTimeoutEnvVarKey, out value))
+            {
+                this.ExporterTimeoutMilliseconds = value;
+            }
+
+            if (TryLoadEnvVarInt(MaxExportBatchSizeEnvVarKey, out value))
+            {
+                this.MaxExportBatchSize = value;
+            }
+
+            if (TryLoadEnvVarInt(MaxQueueSizeEnvVarKey, out value))
+            {
+                this.MaxQueueSize = value;
+            }
+
+            if (TryLoadEnvVarInt(ScheduledDelayEnvVarKey, out value))
+            {
+                this.ScheduledDelayMilliseconds = value;
+            }
+        }
+
+        private static bool TryLoadEnvVarInt(string envVarKey, out int result)
+        {
+            result = 0;
+
+            string value;
+            try
+            {
+                value = Environment.GetEnvironmentVariable(envVarKey);
+            }
+            catch (SecurityException ex)
+            {
+                // The caller does not have the required permission to
+                // retrieve the value of an environment variable from the current process.
+                OpenTelemetrySdkEventSource.Log.MissingPermissionsToReadEnvironmentVariable(ex);
+                return false;
+            }
+
+            if (string.IsNullOrEmpty(value))
+            {
+                return false;
+            }
+
+            if (!int.TryParse(value, out var parsedValue))
+            {
+                OpenTelemetrySdkEventSource.Log.FailedToParseEnvironmentVariable(envVarKey, value);
+                return false;
+            }
+
+            result = parsedValue;
+            return true;
+        }
+    }
+}

test/OpenTelemetry.Tests/Trace/BatchExportActivityProcessorOptionsTest.cs

@@ -0,0 +1,101 @@
+// <copyright file="BatchExportActivityProcessorOptionsTest.cs" company="OpenTelemetry Authors">
+// Copyright The OpenTelemetry Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// </copyright>
+
+using System;
+using Xunit;
+
+namespace OpenTelemetry.Trace.Tests
+{
+    public class BatchExportActivityProcessorOptionsTest : IDisposable
+    {
+        public BatchExportActivityProcessorOptionsTest()
+        {
+            this.ClearEnvVars();
+        }
+
+        public void Dispose()
+        {
+            this.ClearEnvVars();
+        }
+
+        [Fact]
+        public void BatchExportProcessorOptions_Defaults()
+        {
+            var options = new BatchExportActivityProcessorOptions();
+
+            Assert.Equal(30000, options.ExporterTimeoutMilliseconds);
+            Assert.Equal(512, options.MaxExportBatchSize);
+            Assert.Equal(2048, options.MaxQueueSize);
+            Assert.Equal(5000, options.ScheduledDelayMilliseconds);
+        }
+
+        [Fact]
+        public void BatchExportProcessorOptions_EnvironmentVariableOverride()
+        {
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.ExporterTimeoutEnvVarKey, "1");
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.MaxExportBatchSizeEnvVarKey, "2");
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.MaxQueueSizeEnvVarKey, "3");
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.ScheduledDelayEnvVarKey, "4");
+
+            var options = new BatchExportActivityProcessorOptions();
+
+            Assert.Equal(1, options.ExporterTimeoutMilliseconds);
+            Assert.Equal(2, options.MaxExportBatchSize);
+            Assert.Equal(3, options.MaxQueueSize);
+            Assert.Equal(4, options.ScheduledDelayMilliseconds);
+        }
+
+        [Fact]
+        public void BatchExportProcessorOptions_InvalidPortEnvironmentVariableOverride()
+        {
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.ExporterTimeoutEnvVarKey, "invalid");
+
+            var options = new BatchExportActivityProcessorOptions();
+
+            Assert.Equal(30000, options.ExporterTimeoutMilliseconds); // use default
+        }
+
+        [Fact]
+        public void BatchExportProcessorOptions_SetterOverridesEnvironmentVariable()
+        {
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.ExporterTimeoutEnvVarKey, "123");
+
+            var options = new BatchExportActivityProcessorOptions
+            {
+                ExporterTimeoutMilliseconds = 89000,
+            };
+
+            Assert.Equal(89000, options.ExporterTimeoutMilliseconds);
+        }
+
+        [Fact]
+        public void BatchExportProcessorOptions_EnvironmentVariableNames()
+        {
+            Assert.Equal("OTEL_BSP_EXPORT_TIMEOUT", BatchExportActivityProcessorOptions.ExporterTimeoutEnvVarKey);
+            Assert.Equal("OTEL_BSP_MAX_EXPORT_BATCH_SIZE", BatchExportActivityProcessorOptions.MaxExportBatchSizeEnvVarKey);
+            Assert.Equal("OTEL_BSP_MAX_QUEUE_SIZE", BatchExportActivityProcessorOptions.MaxQueueSizeEnvVarKey);
+            Assert.Equal("OTEL_BSP_SCHEDULE_DELAY", BatchExportActivityProcessorOptions.ScheduledDelayEnvVarKey);
+        }
+
+        private void ClearEnvVars()
+        {
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.ExporterTimeoutEnvVarKey, null);
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.MaxExportBatchSizeEnvVarKey, null);
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.MaxQueueSizeEnvVarKey, null);
+            Environment.SetEnvironmentVariable(BatchExportActivityProcessorOptions.ScheduledDelayEnvVarKey, null);
+        }
+    }
+}