fix(core): use false as default for getBooleanFromEnv()

Author: pichlermarc

packages/opentelemetry-core/src/platform/node/environment.ts

@@ -33,7 +33,6 @@ export function getEnv(): Required<ENVIRONMENT> {
 
 /**
  * Retrieves a number from an environment variable.
- * - Trims leading and trailing whitespace.
  * - Returns `undefined` if the environment variable is empty, unset, contains only whitespace, or is not a number.
  * - Returns a number in all other cases.
  *
@@ -75,26 +74,29 @@ export function getStringFromEnv(key: string): string | undefined {
 /**
  * Retrieves a boolean value from an environment variable.
  * - Trims leading and trailing whitespace and ignores casing.
- * - Returns `undefined` if the environment variable is empty, unset, or contains only whitespace.
- * - Returns `undefined` for strings that cannot be mapped to a boolean.
+ * - Returns `false` if the environment variable is empty, unset, or contains only whitespace.
+ * - Returns `false` for strings that cannot be mapped to a boolean.
  *
  * @param {string} key - The name of the environment variable to retrieve.
- * @returns {boolean | undefined} - The boolean value or `undefined`.
+ * @returns {boolean} - The boolean value or `false` if the environment variable is unset empty, unset, or contains only whitespace.
  */
-export function getBooleanFromEnv(key: string): boolean | undefined {
+export function getBooleanFromEnv(key: string): boolean {
   const raw = process.env[key]?.trim().toLowerCase();
   if (raw == null || raw === '') {
-    return undefined;
+    // NOTE: falling back to `false` instead of `undefined` as required by the specification.
+    // If you have a use-case that requires `undefined`, consider using `getStringFromEnv()` and applying the necessary
+    // normalizations in the consuming code.
+    return false;
   }
   if (raw === 'true') {
     return true;
   } else if (raw === 'false') {
     return false;
   } else {
     diag.warn(
-      `Unknown value ${inspect(raw)} for ${key}, expected 'true' or 'false', using defaults`
+      `Unknown value ${inspect(raw)} for ${key}, expected 'true' or 'false', falling back to 'false' (default)`
     );
-    return undefined;
+    return false;
   }
 }
 

packages/opentelemetry-core/test/node/environment.test.ts

@@ -166,17 +166,17 @@ describe('environment utility functions', function () {
       sinon.restore();
     });
 
-    it('should treat empty string as undefined', function () {
+    it('should treat empty string as false', function () {
       process.env.FOO = '';
-      assert.strictEqual(getBooleanFromEnv('FOO'), undefined);
+      assert.strictEqual(getBooleanFromEnv('FOO'), false);
 
       process.env.FOO = '  ';
-      assert.strictEqual(getBooleanFromEnv('FOO'), undefined);
+      assert.strictEqual(getBooleanFromEnv('FOO'), false);
     });
 
-    it('should treat not defined as undefined', function () {
+    it('should treat not defined as false', function () {
       delete process.env.FOO;
-      assert.strictEqual(getBooleanFromEnv('FOO'), undefined);
+      assert.strictEqual(getBooleanFromEnv('FOO'), false);
     });
 
     it('should trim extra whitespace', function () {
@@ -200,7 +200,7 @@ describe('environment utility functions', function () {
     it('should ignore bogus data and warn', function () {
       const warnStub = sinon.stub(diag, 'warn');
       process.env.FOO = 'trueFALSE';
-      assert.strictEqual(getBooleanFromEnv('FOO'), undefined);
+      assert.strictEqual(getBooleanFromEnv('FOO'), false);
       sinon.assert.calledOnceWithMatch(warnStub, 'Unknown value');
     });
   });