docs(logs): clarify logger format handling#4149
Conversation
Assisted-by: OpenAI Codex
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #4149 +/- ##
==========================================
- Coverage 82.99% 82.98% -0.01%
==========================================
Files 406 406
Lines 17260 17260
==========================================
- Hits 14323 14321 -2
- Misses 2937 2939 +2
🚀 New features to boost your workflow:
|
| * @param severity severity of the log | ||
| * @param event_id event identifier of the log | ||
| * @param format an utf-8 string following https://messagetemplates.org/ | ||
| * @param format a UTF-8 string stored as the log record body |
There was a problem hiding this comment.
I think the new note about no SDK-side interpolation is useful, but should we avoid removing the message-template intent entirely? My understanding is that format was kept as a user-facing API concept so custom exporters or upstream agents could interpret it as a message template, even though the OpenTelemetry spec does not require the SDK itself to format it. Maybe this should say that the SDK stores the string as the log record body and does not interpolate attributes, while preserving that exporters/agents may choose to interpret it as a message template.
cc @ThomsonTan - I believe he added the original comment.
There was a problem hiding this comment.
The original intention is recommending the user to pass in message-template. It is not required for SDK or exporter (we don't do that) to do the interpolation, but everything are there for the interpolation so it could be done later, like in the storage backend. Let's add clarification on this instead of revoing the intention.
3 participants
Description
Clarifies the logger API documentation for the
formatparameter. The current wording links to message templates, which can imply that placeholders are interpolated from attributes. This change documents the current behavior: the format string is stored as the log record body, and structured data should be passed through attributes.Fixes #2628
Type of change
Verification
git diff --checkscripts/assert-cncf-github-identity.ps1 -RepoPath upstreams\open-telemetry\opentelemetry-cppNo runtime behavior changed.