feat(logger): add OpenTelemetry-compatible log emission - #759
Abhijeet Prasad (AbhiPrasad) wants to merge 2 commits into
Conversation
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Add `Logger.emit_log()` so applications can emit independent `type="log"`
rows without constructing spans manually. Correlate rows with the active
Braintrust or OpenTelemetry context when available.
Seed each logger with a baseline trace ID for unscoped logs. This keeps
consecutive logs from one logger together while preserving unique row and span
IDs, and avoids grouping logs emitted by separate logger instances.
Map the six base OpenTelemetry severities into `context.otel.log` and add
`trace()`, `debug()`, `info()`, `warn()`, `error()`, and `fatal()` helpers.
logger.error("Payment failed", metadata={"payment_id": "pay_123"})
helper -> emit_log -> `type="log"` row
|-- active span: reuse trace/span IDs
`-- no span: reuse logger trace, generate span ID
fb2baaa to
29dcbc0
Compare
Allow `emit_log()` and severity helpers to interpolate named parameters with Python format strings. Preserve the original template and parameter values in `braintrust.template` metadata so repeated messages remain queryable by their stable structure. Missing placeholders and malformed templates remain unchanged so logging does not disrupt application code.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: fd6b7345e4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "Codex (@codex) review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".
| ) | ||
| rendered_metadata["braintrust.template"] = body | ||
| try: | ||
| rendered_body = body.format_map(_LogTemplateParameters(parameters)) |
There was a problem hiding this comment.
When an omitted placeholder has a conversion or format specifier, such as logger.info("{user} owes {amount:.2f}", user="alice"), __missing__ supplies the string "{amount}", formatting that string as a float raises, and this broad fallback restores the entire original template. Consequently even supplied parameters are left uninterpolated, contrary to the documented behavior that only missing parameters remain as placeholders. Preserve the missing field's conversion/specifier instead of abandoning all rendering.
Useful? React with 👍 / 👎.
| if parameters: | ||
| if not isinstance(body, str): | ||
| raise TypeError("Log body must be a string when template parameters are provided") | ||
| rendered_metadata = dict(metadata) if metadata is not None else {} |
There was a problem hiding this comment.
When a caller combines template parameters with Pydantic-style metadata accepted by the rest of the logger API, this direct conversion can raise TypeError: an object implementing the supported model_dump() or dict() protocol is not necessarily iterable. The same metadata works when no template parameters are supplied because the normal event sanitizer handles those protocols, so logger.info("User {id}", metadata=model, id=...) unexpectedly emits no log. Retain the Metadata input contract and normalize it before merging the template attributes.
Useful? React with 👍 / 👎.
1 participant
resolves https://linear.app/braintrustdata/issue/SDK-341/add-logging-api-to-python-sdk
AI Summary
Add first-class log emission to the project logger so applications can create independent
type="log"rows without constructing spans manually.Logger.emit_log(body, level, metadata).trace(),debug(),info(),warn(),error(), andfatal()convenience methods.context.otel.log.SpanTypeAttribute.LOG.errorfrom string bodies emitted aterrororfatalseverity.Usage
Emit directly or use a severity helper:
Log methods also accept named
str.formatparameters:The row stores the rendered message in
output:It also retains the stable template and its parameters for querying and grouping:
{ "source": "checkout", "braintrust.template": "User {user_id} paid {amount:.2f}", "braintrust.template.parameter.user_id": "user_123", "braintrust.template.parameter.amount": 12.5, }Missing parameters remain as placeholders, and malformed templates fall back to the original body so formatting errors do not disrupt application code. Bodies may remain non-string JSON values when no template parameters are supplied.
Trace correlation
Each log has a unique row ID and span ID unless it is correlated with an active span. A logger seeds one baseline trace ID when it is created, so consecutive unscoped logs from that logger remain grouped without grouping logs from separate logger instances.
This works with both native Braintrust spans and active OpenTelemetry spans through the existing context manager abstraction.
Testing
pytest src/braintrust/test_logger.py(209 passed)nox -s test_typesnox -s pylint