feat(otlp): support per-signal protocol environment variables (#3363)

Author: bryantbiggs

opentelemetry-otlp/CHANGELOG.md

@@ -29,6 +29,19 @@
   DEBUG-only to preserve the auth-token leak safeguards from
   [#3021](https://github.com/open-telemetry/opentelemetry-rust/issues/3021).
   [#3331](https://github.com/open-telemetry/opentelemetry-rust/issues/3331)
+- Add support for per-signal protocol environment variables:
+  `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL`, `OTEL_EXPORTER_OTLP_METRICS_PROTOCOL`,
+  `OTEL_EXPORTER_OTLP_LOGS_PROTOCOL`. These allow configuring different transport protocols
+  per signal type. Signal-specific vars take precedence over generic `OTEL_EXPORTER_OTLP_PROTOCOL`.
+  The auto-select `build()` method on each exporter builder now respects the full priority chain:
+  signal-specific env var > generic env var > feature-based default.
+- Transport/protocol mismatch validation: HTTP transport returns `InvalidConfig` when gRPC protocol
+  is requested; gRPC transport returns `InvalidConfig` when an HTTP protocol is requested.
+- **Breaking**: `Protocol::default()` no longer consults the `OTEL_EXPORTER_OTLP_PROTOCOL`
+  environment variable. It now returns only the feature-based default (http-json > http-proto >
+  grpc-tonic). Protocol resolution from environment variables is handled internally by the
+  exporter builders. Users who relied on `Protocol::default()` to read env vars should use
+  `Protocol::from_env()` instead.
 - Add support for `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` environment variable
   to configure metrics temporality. Accepted values: `cumulative` (default), `delta`,
   `lowmemory` (case-insensitive). Programmatic `.with_temporality()` overrides the env var.

opentelemetry-otlp/src/exporter/http/mod.rs

@@ -156,10 +156,7 @@ pub struct HttpExporterBuilder {
 impl Default for HttpExporterBuilder {
     fn default() -> Self {
         HttpExporterBuilder {
-            exporter_config: ExportConfig {
-                protocol: Protocol::default(),
-                ..ExportConfig::default()
-            },
+            exporter_config: ExportConfig::default(),
             http_config: HttpConfig {
                 headers: Some(default_headers()),
                 ..HttpConfig::default()
@@ -176,7 +173,19 @@ impl HttpExporterBuilder {
         signal_timeout_var: &str,
         signal_http_headers_var: &str,
         signal_compression_var: &str,
+        signal_protocol_var: &str,
     ) -> Result<OtlpHttpClient, ExporterBuildError> {
+        let protocol = super::resolve_protocol(signal_protocol_var, self.exporter_config.protocol);
+
+        // Validate protocol is compatible with HTTP transport
+        #[cfg(feature = "grpc-tonic")]
+        if matches!(protocol, Protocol::Grpc) {
+            return Err(ExporterBuildError::InvalidConfig {
+                name: "protocol".to_string(),
+                reason: "gRPC protocol is not compatible with HTTP transport. Use `.with_tonic()` instead.".to_string(),
+            });
+        }
+
         let endpoint = resolve_http_endpoint(
             signal_endpoint_var,
             signal_endpoint_path,
@@ -284,7 +293,7 @@ impl HttpExporterBuilder {
             http_client,
             endpoint,
             headers,
-            self.exporter_config.protocol,
+            protocol,
             timeout,
             compression,
             #[cfg(feature = "experimental-http-retry")]
@@ -299,12 +308,13 @@ impl HttpExporterBuilder {
         super::resolve_compression_from_env(self.http_config.compression, env_override)
     }
 
-    /// Create a log exporter with the current configuration
+    /// Create a span exporter with the current configuration
     #[cfg(feature = "trace")]
     pub fn build_span_exporter(mut self) -> Result<crate::SpanExporter, ExporterBuildError> {
         use crate::{
             OTEL_EXPORTER_OTLP_TRACES_COMPRESSION, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT,
-            OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_EXPORTER_OTLP_TRACES_TIMEOUT,
+            OTEL_EXPORTER_OTLP_TRACES_HEADERS, OTEL_EXPORTER_OTLP_TRACES_PROTOCOL,
+            OTEL_EXPORTER_OTLP_TRACES_TIMEOUT,
         };
 
         let client = self.build_client(
@@ -313,6 +323,7 @@ impl HttpExporterBuilder {
             OTEL_EXPORTER_OTLP_TRACES_TIMEOUT,
             OTEL_EXPORTER_OTLP_TRACES_HEADERS,
             OTEL_EXPORTER_OTLP_TRACES_COMPRESSION,
+            OTEL_EXPORTER_OTLP_TRACES_PROTOCOL,
         )?;
 
         Ok(crate::SpanExporter::from_http(client))
@@ -323,7 +334,8 @@ impl HttpExporterBuilder {
     pub fn build_log_exporter(mut self) -> Result<crate::LogExporter, ExporterBuildError> {
         use crate::{
             OTEL_EXPORTER_OTLP_LOGS_COMPRESSION, OTEL_EXPORTER_OTLP_LOGS_ENDPOINT,
-            OTEL_EXPORTER_OTLP_LOGS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT,
+            OTEL_EXPORTER_OTLP_LOGS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_PROTOCOL,
+            OTEL_EXPORTER_OTLP_LOGS_TIMEOUT,
         };
 
         let client = self.build_client(
@@ -332,6 +344,7 @@ impl HttpExporterBuilder {
             OTEL_EXPORTER_OTLP_LOGS_TIMEOUT,
             OTEL_EXPORTER_OTLP_LOGS_HEADERS,
             OTEL_EXPORTER_OTLP_LOGS_COMPRESSION,
+            OTEL_EXPORTER_OTLP_LOGS_PROTOCOL,
         )?;
 
         Ok(crate::LogExporter::from_http(client))
@@ -345,7 +358,8 @@ impl HttpExporterBuilder {
     ) -> Result<crate::MetricExporter, ExporterBuildError> {
         use crate::{
             OTEL_EXPORTER_OTLP_METRICS_COMPRESSION, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT,
-            OTEL_EXPORTER_OTLP_METRICS_HEADERS, OTEL_EXPORTER_OTLP_METRICS_TIMEOUT,
+            OTEL_EXPORTER_OTLP_METRICS_HEADERS, OTEL_EXPORTER_OTLP_METRICS_PROTOCOL,
+            OTEL_EXPORTER_OTLP_METRICS_TIMEOUT,
         };
 
         let client = self.build_client(
@@ -354,6 +368,7 @@ impl HttpExporterBuilder {
             OTEL_EXPORTER_OTLP_METRICS_TIMEOUT,
             OTEL_EXPORTER_OTLP_METRICS_HEADERS,
             OTEL_EXPORTER_OTLP_METRICS_COMPRESSION,
+            OTEL_EXPORTER_OTLP_METRICS_PROTOCOL,
         )?;
 
         Ok(crate::MetricExporter::from_http(client, temporality))

opentelemetry-otlp/src/exporter/mod.rs

@@ -52,7 +52,7 @@ pub(crate) mod http;
 pub(crate) mod tonic;
 
 /// Configuration for the OTLP exporter.
-#[derive(Debug)]
+#[derive(Debug, Default)]
 pub(crate) struct ExportConfig {
     /// The address of the OTLP collector.
     /// Default address will be used based on the protocol.
@@ -61,7 +61,9 @@ pub(crate) struct ExportConfig {
     pub endpoint: Option<String>,
 
     /// The protocol to use when communicating with the collector.
-    pub protocol: Protocol,
+    /// `None` means the protocol will be resolved from environment variables
+    /// or feature defaults at build time.
+    pub protocol: Option<Protocol>,
 
     /// The timeout to the collector.
     /// The default value is 10 seconds.
@@ -70,19 +72,26 @@ pub(crate) struct ExportConfig {
     pub timeout: Option<Duration>,
 }
 
+/// Resolve protocol with priority:
+/// 1. Programmatic configuration (provided value)
+/// 2. Signal-specific environment variable
+/// 3. Generic OTEL_EXPORTER_OTLP_PROTOCOL environment variable
+/// 4. Feature-based default
 #[cfg(any(feature = "grpc-tonic", feature = "http-proto", feature = "http-json"))]
-impl Default for ExportConfig {
-    fn default() -> Self {
-        let protocol = Protocol::default();
-
-        Self {
-            endpoint: None,
-            // don't use default_endpoint(protocol) here otherwise we
-            // won't know if user provided a value
-            protocol,
-            timeout: None,
-        }
+pub(crate) fn resolve_protocol(
+    signal_protocol_var: &str,
+    provided_protocol: Option<Protocol>,
+) -> Protocol {
+    if let Some(protocol) = provided_protocol {
+        return protocol;
+    }
+    if let Some(protocol) = Protocol::parse_from_env_var(signal_protocol_var) {
+        return protocol;
+    }
+    if let Some(protocol) = Protocol::from_env() {
+        return protocol;
     }
+    Protocol::feature_default()
 }
 
 #[derive(Error, Debug)]
@@ -186,33 +195,19 @@ fn resolve_compression_from_env(
     }
 }
 
-/// Returns the default protocol based on environment variable or enabled features.
+/// Returns the default protocol based on enabled features.
+///
+/// Note: This does not consult environment variables. Protocol resolution
+/// from environment variables is handled internally by the exporter builders.
 ///
 /// Priority order (first available wins):
-/// 1. OTEL_EXPORTER_OTLP_PROTOCOL environment variable (if set and feature is enabled)
-/// 2. http-json (if enabled)
-/// 3. http-proto (if enabled)
-/// 4. grpc-tonic (if enabled)
+/// 1. http-json (if enabled)
+/// 2. http-proto (if enabled)
+/// 3. grpc-tonic (if enabled)
 #[cfg(any(feature = "grpc-tonic", feature = "http-proto", feature = "http-json"))]
 impl Default for Protocol {
     fn default() -> Self {
-        // Check environment variable first
-        if let Some(protocol) = Protocol::from_env() {
-            return protocol;
-        }
-
-        // Fall back to feature-based defaults
-        #[cfg(feature = "http-json")]
-        return Protocol::HttpJson;
-
-        #[cfg(all(feature = "http-proto", not(feature = "http-json")))]
-        return Protocol::HttpBinary;
-
-        #[cfg(all(
-            feature = "grpc-tonic",
-            not(any(feature = "http-proto", feature = "http-json"))
-        ))]
-        return Protocol::Grpc;
+        Protocol::feature_default()
     }
 }
 
@@ -287,7 +282,7 @@ impl<B: HasExportConfig> WithExportConfig for B {
     }
 
     fn with_protocol(mut self, protocol: Protocol) -> Self {
-        self.export_config().protocol = protocol;
+        self.export_config().protocol = Some(protocol);
         self
     }
 
@@ -503,21 +498,26 @@ mod tests {
     }
 
     #[test]
-    fn test_default_protocol_respects_env() {
-        // Test that env var takes precedence over feature-based defaults
-        #[cfg(all(feature = "http-json", feature = "http-proto"))]
-        run_env_test(
-            vec![(crate::OTEL_EXPORTER_OTLP_PROTOCOL, "http/protobuf")],
-            || {
-                // Even though http-json would be the default, env var should override
-                assert_eq!(crate::Protocol::default(), crate::Protocol::HttpBinary);
-            },
-        );
+    fn test_default_protocol_ignores_env() {
+        // Protocol::default() should always return the feature-based default,
+        // NOT consult environment variables. Env var resolution is handled
+        // by resolve_protocol().
 
+        // Without any env vars, default() equals feature_default()
+        run_env_test(vec![], || {
+            assert_eq!(
+                crate::Protocol::default(),
+                crate::Protocol::feature_default()
+            );
+        });
+
+        // Even with a valid env var set, default() still equals feature_default()
         #[cfg(all(feature = "grpc-tonic", feature = "http-json"))]
         run_env_test(vec![(crate::OTEL_EXPORTER_OTLP_PROTOCOL, "grpc")], || {
-            // Even though http-json would be the default, env var should override
-            assert_eq!(crate::Protocol::default(), crate::Protocol::Grpc);
+            assert_eq!(
+                crate::Protocol::default(),
+                crate::Protocol::feature_default()
+            );
         });
     }
 
@@ -626,4 +626,94 @@ mod tests {
             assert_eq!(timeout.as_millis(), 10_000);
         });
     }
+
+    #[test]
+    fn test_protocol_parse_from_env_var() {
+        use crate::Protocol;
+
+        // Test with custom env var name
+        temp_env::with_var_unset("MY_CUSTOM_PROTOCOL_VAR", || {
+            assert_eq!(Protocol::parse_from_env_var("MY_CUSTOM_PROTOCOL_VAR"), None);
+        });
+
+        #[cfg(feature = "http-proto")]
+        run_env_test(vec![("MY_CUSTOM_PROTOCOL_VAR", "http/protobuf")], || {
+            assert_eq!(
+                Protocol::parse_from_env_var("MY_CUSTOM_PROTOCOL_VAR"),
+                Some(Protocol::HttpBinary)
+            );
+        });
+
+        #[cfg(feature = "grpc-tonic")]
+        run_env_test(vec![("MY_CUSTOM_PROTOCOL_VAR", "grpc")], || {
+            assert_eq!(
+                Protocol::parse_from_env_var("MY_CUSTOM_PROTOCOL_VAR"),
+                Some(Protocol::Grpc)
+            );
+        });
+
+        // Invalid value returns None
+        run_env_test(vec![("MY_CUSTOM_PROTOCOL_VAR", "invalid")], || {
+            assert_eq!(Protocol::parse_from_env_var("MY_CUSTOM_PROTOCOL_VAR"), None);
+        });
+    }
+
+    #[cfg(feature = "http-proto")]
+    #[test]
+    fn test_resolve_protocol_signal_env_overrides_generic() {
+        use crate::Protocol;
+
+        run_env_test(
+            vec![
+                (crate::OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, "http/protobuf"),
+                (crate::OTEL_EXPORTER_OTLP_PROTOCOL, "grpc"),
+            ],
+            || {
+                let protocol =
+                    super::resolve_protocol(crate::OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, None);
+                assert_eq!(protocol, Protocol::HttpBinary);
+            },
+        );
+    }
+
+    #[cfg(feature = "http-proto")]
+    #[test]
+    fn test_resolve_protocol_code_overrides_all_envs() {
+        use crate::Protocol;
+
+        run_env_test(
+            vec![
+                (crate::OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, "grpc"),
+                (crate::OTEL_EXPORTER_OTLP_PROTOCOL, "grpc"),
+            ],
+            || {
+                let protocol = super::resolve_protocol(
+                    crate::OTEL_EXPORTER_OTLP_TRACES_PROTOCOL,
+                    Some(Protocol::HttpBinary),
+                );
+                assert_eq!(protocol, Protocol::HttpBinary);
+            },
+        );
+    }
+
+    #[cfg(all(feature = "grpc-tonic", feature = "http-proto"))]
+    #[test]
+    fn test_resolve_protocol_falls_back_to_generic_env() {
+        use crate::Protocol;
+
+        run_env_test(vec![(crate::OTEL_EXPORTER_OTLP_PROTOCOL, "grpc")], || {
+            let protocol = super::resolve_protocol(crate::OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, None);
+            assert_eq!(protocol, Protocol::Grpc);
+        });
+    }
+
+    #[test]
+    fn test_resolve_protocol_falls_back_to_feature_default() {
+        use crate::Protocol;
+
+        run_env_test(vec![], || {
+            let protocol = super::resolve_protocol(crate::OTEL_EXPORTER_OTLP_TRACES_PROTOCOL, None);
+            assert_eq!(protocol, Protocol::feature_default());
+        });
+    }
 }