fix(opentelemetry-resources): Update the Env Var Parsing Logic to Match Spec

[JacksonWeber]

Which problem is this PR solving?

This pull request updates the parsing logic for the OTEL_RESOURCE_ATTRIBUTES environment variable in the OpenTelemetry JS resources package to match recent specification changes. The main change is stricter handling: any parsing error now causes the entire environment variable to be discarded. The implementation and test suite have been updated to reflect these rules, while retaining backward compatibility for certain legacy behaviors.

Resource attribute parsing and validation:

• Updated EnvDetector to discard the entire OTEL_RESOURCE_ATTRIBUTES value on any parsing error, as required by the spec. This includes errors such as invalid percent-encoding, missing key/value separators, or values exceeding 255 characters. [1] [2]
• Removed W3C Baggage octet validation and related ASCII checks, since the spec no longer references these requirements. [1] [2] [3]
• Retained backward compatibility: values are still stripped of leading/trailing quotes and limited to 255 characters, as before. [1] [2]

Test suite improvements:

• Expanded tests in EnvDetector.test.ts to cover new spec-compliant behaviors, including error cases (invalid percent-encoding, unencoded = in values, missing separators), edge cases (spaces in keys/values, percent-encoded delimiters), and backward compatibility for quoted values. [1] [2] [3] [4] [5]

Logging and error handling:

• Improved debug logging to handle both Error objects and plain strings when reporting parsing failures.

Documentation:

• Updated the changelog to document the breaking change and specification alignment.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Added unit tests to ensure the behavior of the new env var parsing logic.

Checklist:

• Followed the style guidelines of this project
• Unit tests have been added
• Documentation has been updated

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.66%. Comparing base (9a44ea7) to head (9e078bf).
⚠️ Report is 32 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6261      +/-   ##
==========================================
+ Coverage   95.48%   95.66%   +0.18%     
==========================================
  Files         363      362       -1     
  Lines       11563    11731     +168     
  Branches     2669     2733      +64     
==========================================
+ Hits        11041    11223     +182     
+ Misses        522      508      -14     

Files with missing lines	Coverage Δ
...entelemetry-resources/src/detectors/EnvDetector.ts	100.00% <100.00%> (+6.25%)	⬆️

... and 15 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[trentm]

The spec on parsing OTEL_RESOURCE_ATTRIBUTES: https://opentelemetry.io/docs/specs/otel/resource/sdk/#specifying-resource-information-via-an-environment-variable

The OTEL_RESOURCE_ATTRIBUTES environment variable will contain of a list of key value pairs, and these are expected to be represented in a format matching to the W3C Baggage, except that additional semi-colon delimited metadata is not supported, i.e.: key1=value1,key2=value2. All attribute values MUST be considered strings and characters outside the baggage-octet range MUST be percent-encoded.

Regarding this PR

• I like having the JS impl align with other SDKs.
• I like considering the behaviour that one invalid attribute value does not impact other valid key/value-pairs.
• IIUC, this PR effectively allows unencoded (space), ; (semicolon), and \ (backslash) characters to be included in OTEL_RESOURCE_ATTRIBUTES values. I think I'm good with that.

Some other thoughts

(I hesitate to add this because it might derail the PR, though that isn't my intent.)

I would like EnvDetector comments/docs to be clearer about how it is basically ignoring parts of the spec there. That is already the case with the support for quoted values. Unless I'm missing something in the baggage spec.

It would probably be good to engage with the spec -- though I don't want to slam a blocker on this PR.

I find the spec weird here. Perhaps the reference to (somewhat) follow the Baggage rules is historical. If many/most SDK implementations aren't following the spec, perhaps the spec needs to update.

Some notes on the weirdness of the JS implementation:

• Double-quotes at the start or end of a value are removed, but otherwise don't do anything. This despite the code comment saying If a value contains whitespace, =, or " characters, it must always be quoted. For example OTEL_RESOURCE_ATTRIBUTES='foo=bar,spam=""answer"42' results in {foo: 'bar', spam: '"answer"42'}.
• The parsing of OTEL_RESOURCE_ATTRIBUTES is quite different to the parsing of OTEL_EXPORTER_OTLP_HEADERS. The latter uses parseKeyPairsIntoRecord from "src/baggage/utils.ts" @opentelemetry/core. Ironically src/baggage/utils.ts does not exclude some of the chars excluded from baggage-octet in the Baggage spec. Also, it doesn't treat double-quoting as special at all:

$ cd packages/opentelemetry-core
$ node
> var core = require('./build/src/index.js')
> core.parseKeyPairsIntoRecord('foo=bar,spam=eggs and ham')
{ foo: 'bar', spam: 'eggs and ham' }
> core.parseKeyPairsIntoRecord('foo=bar,spam="eggs and ham"')
{ foo: 'bar', spam: '"eggs and ham"' }
> core.parseKeyPairsIntoRecord('foo=bar,spam=  "eggs and\\ham"  ')
{ foo: 'bar', spam: '"eggs and\\ham"' }

It does treat semicolon as special for baggage attributes.

> core.parseKeyPairsIntoRecord('foo=bar,spam=  "eggs and;ham"  ')
{ foo: 'bar', spam: '"eggs and' }

Which means that OTEL_EXPORTER_OTLP_HEADERS="Authorization: Bearer blah;oops" won't give what one might expect. This is a pretty odd/rare edge case though.

[JacksonWeber]

Update is based on open-telemetry/opentelemetry-specification#4856

[trentm]

Looking good. Two Qs: breaking change in a stable package, and the quoting weirdness.

[trentm]

LGTM, with a suggested update for the changelog.