Skip to content

Enable context-flattening to support context field searching#491

Merged
ChrisLightfootWild merged 4 commits intoopen-telemetry:mainfrom
nickmarden:feat/first-class-context-fields
Apr 24, 2026
Merged

Enable context-flattening to support context field searching#491
ChrisLightfootWild merged 4 commits intoopen-telemetry:mainfrom
nickmarden:feat/first-class-context-fields

Conversation

@nickmarden
Copy link
Copy Markdown
Contributor

@nickmarden nickmarden commented Dec 17, 2025

Description

Resolves open-telemetry/opentelemetry-php#1837

This PR adds an optional configuration to flatten log context attributes into individual OTLP attributes, improving searchability in observability backends.

Problem

The Laravel LogWatcher currently JSON-encodes the entire log context into a single context attribute:

context: {"http":{"method":"GET","path":"/users","status":200},"user_id":"123"}

This makes it impossible to search/filter by specific values (e.g., http.method = "GET") in backends like SigNoz, Jaeger, or Grafana.

Solution

A new configuration option OTEL_PHP_LARAVEL_LOG_ATTRIBUTES_FLATTEN that, when enabled, spreads context as individual attributes with dot-notation for nested arrays:

http.method: GET
http.path: /users
http.status: 200
user_id: 123

Changes

  • src/Watchers/LogWatcher.php: Added flattening logic with ConfigurationResolver, dot-notation for nested arrays, and proper handling of Stringable objects
  • README.md: Documented the new configuration option with examples
  • tests/Unit/Watchers/LogWatcherTest.php: Added 11 unit tests covering default behavior, flattened mode, nested arrays, exceptions, and edge cases

Backward Compatibility

  • Default behavior unchanged (off by default)
  • Existing tests continue to pass

Testing

./vendor/bin/phpunit --testsuite=unit # 18 tests, 42 assertions
./vendor/bin/phpunit --testsuite=integration # 21 tests, 120 assertions

Screenshot

Screenshot 2025-12-17 at 6 56 35 PM

@nickmarden nickmarden requested a review from a team as a code owner December 17, 2025 23:10
@linux-foundation-easycla
Copy link
Copy Markdown

linux-foundation-easycla Bot commented Dec 17, 2025

CLA Signed

The committers listed above are authorized under a signed CLA.

@codecov
Copy link
Copy Markdown

codecov Bot commented Dec 19, 2025

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 81.35%. Comparing base (9c73e84) to head (60ee14a).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

Impacted file tree graph

@@             Coverage Diff              @@
##               main     #491      +/-   ##
============================================
- Coverage     82.56%   81.35%   -1.22%     
+ Complexity     2306     1587     -719     
============================================
  Files           156       95      -61     
  Lines          8571     5759    -2812     
============================================
- Hits           7077     4685    -2392     
+ Misses         1494     1074     -420     
Flag Coverage Δ
Aws ?
Context/Swoole 0.00% <ø> (ø)
Exporter/Instana 49.80% <ø> (ø)
Instrumentation/AwsSdk 82.14% <ø> (ø)
Instrumentation/CakePHP 20.42% <ø> (ø)
Instrumentation/CodeIgniter 79.31% <ø> (ø)
Instrumentation/Curl 86.88% <ø> (ø)
Instrumentation/Doctrine 92.82% <ø> (ø)
Instrumentation/ExtAmqp 88.80% <ø> (ø)
Instrumentation/Guzzle 76.25% <ø> (ø)
Instrumentation/HttpAsyncClient 78.94% <ø> (ø)
Instrumentation/HttpConfig 28.76% <ø> (ø)
Instrumentation/IO 0.00% <ø> (ø)
Instrumentation/Laravel ?
Instrumentation/MongoDB 76.84% <ø> (ø)
Instrumentation/MySqli 93.39% <ø> (ø)
Instrumentation/OpenAIPHP 86.71% <ø> (ø)
Instrumentation/PDO 85.67% <ø> (ø)
Instrumentation/PostgreSql 91.36% <ø> (ø)
Instrumentation/Psr14 77.41% <ø> (ø)
Instrumentation/Psr15 89.74% <ø> (ø)
Instrumentation/Psr16 97.43% <ø> (ø)
Instrumentation/Psr18 79.41% <ø> (ø)
Instrumentation/Psr3 ?
Instrumentation/Psr6 97.56% <ø> (ø)
Instrumentation/Session 94.28% <ø> (ø)
Instrumentation/Slim 84.21% <ø> (ø)
Logs/Monolog ?
Propagation/CloudTrace 90.69% <ø> (ø)
Propagation/Instana 98.07% <ø> (ø)
Propagation/ServerTiming 94.73% <ø> (ø)
Propagation/TraceResponse 94.73% <ø> (ø)
ResourceDetectors/Azure 91.66% <ø> (ø)
ResourceDetectors/Container ?
ResourceDetectors/DigitalOcean 100.00% <ø> (ø)
Sampler/Xray 78.38% <ø> (ø)
Shims/OpenTracing 92.99% <ø> (ø)
SqlCommenter 95.58% <ø> (ø)
Symfony ?
Utils/Test 87.79% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.
see 61 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 data
Powered by Codecov. Last update 9c73e84...60ee14a. Read the comment docs.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@nickmarden nickmarden force-pushed the feat/first-class-context-fields branch from c13169b to 2e340d8 Compare December 19, 2025 20:38
@nickmarden
Copy link
Copy Markdown
Contributor Author

@brettmc I'm unclear how to trigger another CI run. I believe I've fixed all but one of the previously-failing CI tests, but I can't be sure. Is this something you need to trigger, or can I?

@arthurmartelli arthurmartelli force-pushed the feat/first-class-context-fields branch from 2e340d8 to ff353e9 Compare March 31, 2026 19:08
@arthurmartelli
Copy link
Copy Markdown
Contributor

Hi @brettmc, I just updated the fork by re-basing to main. Could you please run CI? thanks!

->setSeverityNumber(Severity::fromPsr3($log->level));

if ($this->flattenAttributes) {
foreach ($this->buildFlattenedAttributes($contextToProcess) as $key => $value) {
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The implementation is much cleaner with that array method :)

@arthurmartelli arthurmartelli force-pushed the feat/first-class-context-fields branch from 1c55e20 to 42197ac Compare April 24, 2026 00:36
nickmarden and others added 2 commits April 23, 2026 18:58
Replace the custom recursive flattenArray() method and the
manual normalization loop with a single array_map() +
Arr::dot() expression, removing ~25 lines of bespoke logic.
@arthurmartelli arthurmartelli force-pushed the feat/first-class-context-fields branch from 42197ac to 60ee14a Compare April 24, 2026 00:59
@ChrisLightfootWild ChrisLightfootWild merged commit 7392a9b into open-telemetry:main Apr 24, 2026
131 of 175 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Laravel] Add option to flatten log context attributes for better searchability

4 participants