opentelemetry-php-contrib
opentelemetry-php-contrib copied to clipboard
open-telemetry
[Monolog] Add option to directly assign context elements as attributes
This PR modifies how Monolog context and extras arrays behave, and adds specific behavior for exceptions.
General Attributes
Per PSR-3:
[The context array] is meant to hold any extraneous information that does not fit well in a string. The array can contain anything. Implementors MUST ensure they treat context data with as much lenience as possible. A given value in the context MUST NOT throw an exception nor raise any php error, warning or notice.
Per Monolog:
The second way is to add extra data for all records by using a processor. Processors can be any callable. They will get the record as parameter and must return it after having eventually changed the
extrapart of it.
Per OTel Spec Logs Data Model:
[The Attributes Field is] additional information about the specific event occurrence. Unlike the
Resourcefield, which is fixed for a particular source,Attributescan vary for each occurrence of the event coming from the same source. Can contain information about the request context (other than Trace Context Fields). This field is optional.
These descriptions indicate the intent of the context array of PSR-3, and to a lesser extent, the extras array of Monolog, has the same intended function as the Log Record Attributes of OpenTelemetry.
While identifying the need to prevent breaking existing implementations of the OpenTelemetry Monolog Handler, we suggest adding OTEL_PHP_MONOLOG_ATTRIB_MODE as a runtime configuration option to switch between the current behavior that prioritizes PSR-3 flexibility and safety, and a new behavior that prioritizes the OpenTelemetry spec and SemConv.
Examples are in the README.md.
Exceptions
Per PSR-3:
If an
Exceptionobject is passed in the context data, it MUST be in the'exception'key. Logging exceptions is a common pattern and this allows implementors to extract a stack trace from the exception when the log backend supports it. Implementors MUST still verify that the'exception'key is actually anExceptionbefore using it as such, as it MAY contain anything.
Per the OTel Spec:
Additional information about errors and/or exceptions that are associated with a log record MAY be included in the structured data in the
Attributessection of the record. If included, they MUST follow the OpenTelemetry semantic conventions for exception-related attributes.
Per the OTel SemConv:
Exceptions SHOULD be recorded as attributes on the LogRecord passed to the Logger emit operations. Exceptions MAY be recorded on "logs" or "events" depending on the context.
These descriptions indicate that exceptions included in the context array under the exception key should be treated differently than other general keys. This behavior is also included in this PR, regardless of the attributes mode.
Codecov Report
:white_check_mark: All modified and coverable lines are covered by tests.
:white_check_mark: Project coverage is 81.63%. Comparing base (42f350a) to head (760a307).
:warning: Report is 1 commits behind head on main.
Additional details and impacted files
@@ Coverage Diff @@
## main #467 +/- ##
============================================
+ Coverage 73.42% 81.63% +8.21%
- Complexity 134 2192 +2058
============================================
Files 11 159 +148
Lines 459 8238 +7779
============================================
+ Hits 337 6725 +6388
- Misses 122 1513 +1391
Flags with carried forward coverage won't be shown. Click here to find out more.
| Files with missing lines | Coverage Δ | |
|---|---|---|
| src/Logs/Monolog/src/Handler.php | 100.00% <100.00%> (ø) |
... and 153 files with indirect coverage changes
Continue to review full report in Codecov by Sentry.
Legend - Click here to learn more
Δ = absolute <relative> (impact),ø = not affected,? = missing dataPowered by Codecov. Last update 42f350a...760a307. Read the comment docs.
:rocket: New features to boost your workflow:
- :snowflake: Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
![codecov[bot] avatar](https://avatars.githubusercontent.com/in/254?v=4 "Published by a pub.dev verified publisher"){kind=small}
I think this makes sense. Can the non-default mode (OTEL_PHP_MONOLOG_ATTRIB_MODE=otel) be tested ?
I think this makes sense. Can the non-default mode (OTEL_PHP_MONOLOG_ATTRIB_MODE=otel) be tested ?
I copied the behavior from the PSR-3 Instrumentation library, which appears to be the only instance of ConfigurationResolver in use, but the phpt coverage tests for that library have a bunch of failures which makes it appear that the ConfigurationResolver related lines are not tested (not sure if they actually are or not). All that to say I'll need to do some trial and error to figure out the unit testing.