feat(sdk-node): configure trace exporter with environment variables

experimental/CHANGELOG.md

@@ -18,6 +18,8 @@ All notable changes to experimental packages in this project will be documented
 
 ### :rocket: (Enhancement)
 
+* feat(sdk-node): configure trace exporter with environment variables [#3143](https://github.com/open-telemetry/opentelemetry-js/pull/3143) @svetlanabrennan
+
 ### :bug: (Bug Fix)
 
 ### :books: (Refine Doc)

experimental/packages/opentelemetry-sdk-node/README.md

@@ -122,7 +122,7 @@ Configure a custom sampler. By default all traces will be sampled.
 
 ### traceExporter
 
-Configure a trace exporter. If an exporter OR span processor is not configured, the tracing SDK will not be initialized and registered. If an exporter is configured, it will be used with a [BatchSpanProcessor](../../../packages/opentelemetry-sdk-trace-base/src/platform/node/export/BatchSpanProcessor.ts).
+Configure a trace exporter. If an exporter is configured, it will be used with a [BatchSpanProcessor](../../../packages/opentelemetry-sdk-trace-base/src/platform/node/export/BatchSpanProcessor.ts). If an exporter OR span processor is not configured programatically, this package will auto setup the default `otlp` exporter  with `http/protobuf` protocol with a `BatchSpanProcessor`.
 
 ### spanLimits
 
@@ -136,6 +136,30 @@ Configure views of your instruments and accepts an array of [View](../openteleme
 
 Configure the [service name](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/resource/semantic_conventions/README.md#service).
 
+## Configure Trace Exporter from  Environment
+
+This is an alternative to programmatically configuring an exporter or span processor. This package will auto setup the default `otlp` exporter with `http/protobuf` protocol if `traceExporter` or `spanProcessor` hasn't been passed into the `NodeSDK` constructor.
+
+### Exporters
+
+| Environment variable | Description |
+|----------------------|-------------|
+| OTEL_TRACES_EXPORTER | List of exporters to be used for tracing, separated by commas. Options include `otlp`, `jaeger`, `zipkin`, and `none`. Default is `otlp`. `none` means no autoconfigured exporter.
+
+### OTLP Exporter
+
+| Environment variable | Description |
+|----------------------|-------------|
+| OTEL_EXPORTER_OTLP_PROTOCOL | The transport protocol to use on OTLP trace, metric, and log requests. Options include `grpc`, `http/protobuf`, and `http/json`. Default is `http/protobuf`. |
+| OTEL_EXPORTER_OTLP_TRACES_PROTOCOL | The transport protocol to use on OTLP trace requests. Options include `grpc`, `http/protobuf`, and `http/json`. Default is `http/protobuf`. |
+| OTEL_EXPORTER_OTLP_METRICS_PROTOCOL | The transport protocol to use on OTLP metric requests. Options include `grpc`, `http/protobuf`, and `http/json`. Default is `http/protobuf`. |
+
+Additionally, you can specify other applicable environment variables that apply to each exporter such as the following:
+
+- [OTLP exporter environment configuration](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/protocol/exporter.md#configuration-options)
+- [Zipkin exporter environment configuration](https://github.com/open-telemetry/opentelemetry-specification/blob/6ce62202e5407518e19c56c445c13682ef51a51d/specification/sdk-environment-variables.md#zipkin-exporter)
+- [Jaeger exporter environment configuration](https://github.com/open-telemetry/opentelemetry-specification/blob/6ce62202e5407518e19c56c445c13682ef51a51d/specification/sdk-environment-variables.md#jaeger-exporter)
+
 ## Useful links
 
 - For more information on OpenTelemetry, visit: <https://opentelemetry.io/>

experimental/packages/opentelemetry-sdk-node/package.json

@@ -44,6 +44,11 @@
     "access": "public"
   },
   "dependencies": {
+    "@opentelemetry/exporter-jaeger": "^1.5.0",
+    "@opentelemetry/exporter-trace-otlp-grpc": "^0.31.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.31.0",
+    "@opentelemetry/exporter-trace-otlp-proto": "^0.31.0",
+    "@opentelemetry/exporter-zipkin": "^1.5.0",
     "@opentelemetry/api-metrics": "0.32.0",
     "@opentelemetry/core": "1.6.0",
     "@opentelemetry/instrumentation": "0.32.0",

experimental/packages/opentelemetry-sdk-node/src/TracerProviderWithEnvExporter.ts

@@ -0,0 +1,109 @@
+/*
+ * 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
+ *
+ *      https://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.
+ */
+
+import { diag } from '@opentelemetry/api';
+import { getEnv, getEnvWithoutDefaults } from '@opentelemetry/core';
+import { ConsoleSpanExporter, SpanExporter, BatchSpanProcessor, SimpleSpanProcessor } from '@opentelemetry/sdk-trace-base';
+import { NodeTracerConfig, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { OTLPTraceExporter as OTLPProtoTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto';
+import { OTLPTraceExporter as OTLPHttpTraceExporter} from '@opentelemetry/exporter-trace-otlp-http';
+import { OTLPTraceExporter as OTLPGrpcTraceExporter} from '@opentelemetry/exporter-trace-otlp-grpc';
+import { ZipkinExporter } from '@opentelemetry/exporter-zipkin';
+import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
+
+export class TracerProviderWithEnvExporters extends NodeTracerProvider {
+  public configuredExporters: SpanExporter[] = [];
+  public spanProcessors: (BatchSpanProcessor | SimpleSpanProcessor)[] | undefined;
+
+  static configureOtlp(): SpanExporter {
+    const protocol = this.getOtlpProtocol();
+
+    switch (protocol) {
+      case 'grpc':
+        return new OTLPGrpcTraceExporter;
+      case 'http/json':
+        return new OTLPHttpTraceExporter;
+      case 'http/protobuf':
+        return new OTLPProtoTraceExporter;
+      default:
+        diag.warn(`Unsupported OTLP traces protocol: ${protocol}. Using http/protobuf.`);
+        return new OTLPProtoTraceExporter;
+    }
+  }
+
+  static getOtlpProtocol(): string {
+    const parsedEnvValues = getEnvWithoutDefaults();
+
+    return parsedEnvValues.OTEL_EXPORTER_OTLP_TRACES_PROTOCOL ??
+          parsedEnvValues.OTEL_EXPORTER_OTLP_PROTOCOL ??
+          getEnv().OTEL_EXPORTER_OTLP_TRACES_PROTOCOL ??
+          getEnv().OTEL_EXPORTER_OTLP_PROTOCOL;
+  }
+
+  protected static override _registeredExporters = new Map<
+    string,
+    () => SpanExporter
+      >([
+        ['otlp', () => this.configureOtlp()],
+        ['zipkin', () => new ZipkinExporter],
+        ['jaeger', () => new JaegerExporter],
+        ['console', () => new ConsoleSpanExporter]
+      ]);
+
+  public constructor(config: NodeTracerConfig = {}) {
+    super(config);
+    let traceExportersList = this.filterBlanksAndNulls(Array.from(new Set(getEnv().OTEL_TRACES_EXPORTER.split(','))));
+
+    if (traceExportersList.length === 0 || traceExportersList[0] === 'none') {
+      diag.warn('OTEL_TRACES_EXPORTER contains "none" or is empty. SDK will not be initialized.');
+    } else {
+      if (traceExportersList.length > 1 && traceExportersList.includes('none')) {
+        diag.warn('OTEL_TRACES_EXPORTER contains "none" along with other exporters. Using default otlp exporter.');
+        traceExportersList = ['otlp'];
+      }
+
+      traceExportersList.forEach(exporterName => {
+        const exporter = this._getSpanExporter(exporterName);
+        if (exporter) {
+          this.configuredExporters.push(exporter);
+        } else {
+          diag.warn(`Unrecognized OTEL_TRACES_EXPORTER value: ${exporterName}.`);
+        }
+      });
+
+      if (this.configuredExporters.length > 0) {
+        this.spanProcessors = this.configureSpanProcessors(this.configuredExporters);
+      } else {
+        diag.warn('Unable to set up trace exporter(s) due to invalid exporter and/or protocol values.');
+      }
+    }
+  }
+
+  public configureSpanProcessors(exporters: SpanExporter[]): (BatchSpanProcessor | SimpleSpanProcessor)[] {
+    return exporters.map(exporter => {
+      if (exporter instanceof ConsoleSpanExporter) {
+        return new SimpleSpanProcessor(exporter);
+      } else {
+        return new BatchSpanProcessor(exporter);
+      }
+    });
+  }
+
+  public filterBlanksAndNulls(list: string[]): string[] {
+    return list.map(item => item.trim())
+      .filter(s => s !== 'null' && s !== '');
+  }
+}

experimental/packages/opentelemetry-sdk-node/src/sdk.ts

@@ -30,11 +30,12 @@ import {
 import { MeterProvider, MetricReader, View } from '@opentelemetry/sdk-metrics';
 import {
   BatchSpanProcessor,
-  SpanProcessor
+  SpanProcessor,
 } from '@opentelemetry/sdk-trace-base';
 import { NodeTracerConfig, NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
 import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
 import { NodeSDKConfiguration } from './types';
+import { TracerProviderWithEnvExporters } from './TracerProviderWithEnvExporter';
 
 /** This class represents everything needed to register a fully configured OpenTelemetry Node.js SDK */
 
@@ -60,14 +61,12 @@ export class NodeSDK {
   };
   private _meterProviderConfig?: MeterProviderConfig;
   private _instrumentations: InstrumentationOption[];
-
   private _resource: Resource;
-
   private _autoDetectResources: boolean;
-
-  private _tracerProvider?: NodeTracerProvider;
+  private _tracerProvider?: NodeTracerProvider | TracerProviderWithEnvExporters;
   private _meterProvider?: MeterProvider;
   private _serviceName?: string;
+  private _useEnvExporters = false;
 
   /**
    * Create a new NodeJS SDK instance
@@ -99,6 +98,8 @@ export class NodeSDK {
         configuration.contextManager,
         configuration.textMapPropagator
       );
+    } else {
+      this._useEnvExporters = true;
     }
 
     if (configuration.metricReader || configuration.views) {
@@ -196,19 +197,29 @@ export class NodeSDK {
         { [SemanticResourceAttributes.SERVICE_NAME]: this._serviceName }
       ));
 
-    if (this._tracerProviderConfig) {
-      const tracerProvider = new NodeTracerProvider({
-        ...this._tracerProviderConfig.tracerConfig,
+    if (this._tracerProviderConfig || this._useEnvExporters) {
+      const Provider =
+        this._tracerProviderConfig ? NodeTracerProvider : TracerProviderWithEnvExporters;
+
+      const tracerProvider = new Provider ({
+        ...this._tracerProviderConfig?.tracerConfig,
         resource: this._resource,
       });
 
       this._tracerProvider = tracerProvider;
 
-      tracerProvider.addSpanProcessor(this._tracerProviderConfig.spanProcessor);
-      tracerProvider.register({
-        contextManager: this._tracerProviderConfig.contextManager,
-        propagator: this._tracerProviderConfig.textMapPropagator,
-      });
+      const processors = this.retrieveSpanProcessors(tracerProvider);
+
+      if (processors) {
+        processors.forEach((processor: SpanProcessor) => {
+          tracerProvider.addSpanProcessor(processor);
+        });
+
+        tracerProvider.register({
+          contextManager: this._tracerProviderConfig?.contextManager,
+          propagator: this._tracerProviderConfig?.textMapPropagator,
+        });
+      }
     }
 
     if (this._meterProviderConfig) {
@@ -247,4 +258,16 @@ export class NodeSDK {
         })
     );
   }
+
+  private retrieveSpanProcessors(provider: NodeTracerProvider): SpanProcessor[] | undefined {
+    if (this._tracerProviderConfig) {
+      return [this._tracerProviderConfig.spanProcessor];
+    }
+
+    if (provider instanceof TracerProviderWithEnvExporters) {
+      return provider.spanProcessors;
+    }
+
+    return undefined;
+  }
 }