NH-108345 - Added SW_ PREFIX environment variables support

[jerrytfleung]

This pull request introduces several enhancements and refactors to SolarWinds APM PHP's configuration and sampling logic. The main focus is on supporting new environment variables for tracing control, simplifying configuration structures, and improving transaction name handling. It also updates documentation and examples to reflect these changes.

Configuration and Environment Variable Enhancements:

• Added support for new environment variables: SW_APM_TRACING_MODE, SW_APM_TRIGGER_TRACE_ENABLED, SW_APM_TRANSACTION_NAME, and SW_APM_TRANSACTION_SETTINGS to allow more granular control over tracing and transaction naming. [1] [2]
• Updated documentation (CONFIGURATION.md) to describe the new configuration options and their usage, including details on transaction settings as a JSON array.
• Updated the example in examples/other.php to demonstrate usage of the new environment variables.

Configuration Refactoring:

• Refactored the Configuration class to remove unused fields and methods (enabled, headers, and transactionName), simplifying its interface and string representation. [1] [2] [3] [4]
• Updated SwoSamplerFactory to use the new environment variables and to build configuration objects accordingly, including robust parsing and error handling for SW_APM_TRANSACTION_SETTINGS. [1] [2]

Sampler and Span Processing Improvements:

• Modified HttpSampler and related classes to remove dependency on custom headers, aligning with the simplified configuration. [1] [2] [3]
• Enhanced transaction settings parsing in Sampler to support regex-based transaction filtering as defined in the new configuration.
• Improved TransactionNameSpanProcessor to prioritize the transaction name from the SW_APM_TRANSACTION_NAME environment variable, with detailed debug logging for tracing name resolution. [1] [2] [3]

Bug Fixes and Minor Improvements:

• Fixed potential type issues in Kubernetes pod UID detection by explicitly casting values to strings before validation.
• Updated the sampler factory to accept a resource parameter, improving resource attribute handling for service naming.

These changes collectively provide more flexible and robust configuration for tracing and transaction naming, while simplifying the codebase and improving maintainability.

Related issues

NH-108345

[cheempz]

the regex here is different from line 462:
'/^http:\\/\\/localhost\\/test$/'
'/^http:\/\/localhost\/test$/'

and i'm trying to understand why both seem to work. what i understand is in order to pass the regex as a JSON string we need to escape the JSON escape char \, copilot chat output below:

In JSON, the escape character is \ (backslash).

For regex-in-JSON specifically: every regex backslash must be escaped again for JSON.
Example: regex \/ becomes JSON text \\/.

which is making me wonder if these tests are actually running the regex through the json_decode step?

So a few hopefully last comments on this PR:

• again, if we want to show examples for the tracing' => enabled` case, it should be made clear that only is meaningful when global trace mode is disabled. look over what you're saying in the config docs right now, it's not very clear
• add examples where the regex needs to use escapes, for example matching for http://my.domain.com/foo?
• do the tests actually verify regex properly?

[jerrytfleung]

Both cases work. It is due to the PHP string parser and regex use the backslash (\) as an escape character.

Here is the explanation from copilot

In PHP, when using preg_match, double escaping is necessary because both the PHP string parser and the regular expression engine use the backslash (\) as an escape character. 
First level (PHP string parsing): The PHP interpreter processes the string literal first. A single backslash must be escaped with another backslash to pass a literal backslash to the regex engine.
Second level (Regex engine): The regex engine then receives the resulting string and interprets its own escape sequences. 

I added unit tests to verify both regex are working.

====================

again, if we want to show examples for the tracing' => enabled` case, it should be made clear that only is meaningful when global trace mode is disabled. look over what you're saying in the config docs right now, it's not very clear

Re: @cheempz Not sure if I get it correct. My understandingtracing=>enabled is meaningful when the regex matched. From apm-js code, the global tracing mode is used to init the local settings at the beginning and the transactionSettings regex can change it (enabled / disabled) if regex is matched.

add examples where the regex needs to use escapes, for example matching for http://my.domain.com/foo?
Re: Sure. Added unit test cases to match http://my.domain.com/foo and also the example in CONFIGURATION.md

do the tests actually verify regex properly?
Re: Yes, the preg_match function verified the regex and return 1 if matched.

[jerrytfleung]

Per discussed, I will try to add a more complete integration test in SwoSamplerFactoryTest.php and update CONFIGURATION.md for a better regex and JSON string clarification.

[jerrytfleung]

@cheempz
Added the test case test_get_solarwinds_configuration_transaction_settings_file_end2end and test_get_solarwinds_configuration_transaction_settings_env_end2end to test the transaction settings routine from end to end.

Both test case first global set tracing to false and enable tracing using the transaction settings.

However, as it is an unit test, I am unable to test the real url path. Instead, I put http://my.domain.com/foo in the span name and use the regex #^INTERNAL:http://my.domain.com/foo$# to test the regex loading from file or env.

[cheempz]

LGTM, thanks for the discussions and revisits @jerrytfleung!