feat(logging): add component and logger fields to JSON logs for 3rd p…

[J-Byron]

Relevant issues

Resolves #23884

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem
• I have requested a Greptile review by commenting @greptileai and received a Confidence Score of at least 4/5 before requesting a maintainer review

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

CI (LiteLLM team)

CI status guideline:

• 50-55 passing tests: main is stable with minor issues.
• 45-49 passing tests: acceptable but needs attention
• <= 40 passing tests: unstable; be careful with your merges and assess the risk.

• Branch creation CI run
  Link:

• CI run for the last commit
  Link:

• Merge / cherry-pick CI run
  Links:

Type

🆕 New Feature

Changes

Add component and logger fields to structured JSON logs

Adds two fields to the JsonFormatter output:

• component: the logger name (e.g. LiteLLM Proxy, LiteLLM Router)
• logger: source file and line number (e.g. proxy_server.py:412)

Makes it easier to filter and route logs by component in third-party
observability tools (Datadog, Grafana, CloudWatch) without parsing the
message string.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Mar 23, 2026 11:19pm

[greptile-apps]

Greptile Summary

This PR enhances JsonFormatter in litellm/_logging.py to emit two new structured fields — component (the logger name, e.g. LiteLLM Proxy) and logger (source file + line number, e.g. proxy_server.py:412) — making it easier to filter and route logs in third-party observability tools like Datadog, Grafana, and CloudWatch without parsing the message string.

• The previously-reported silent-overwrite bug (user extra values for component/logger being dropped) has been correctly fixed: both field assignments now sit after the extra-attributes loop and are guarded by if … not in json_record.
• Three new unit tests cover the happy-path for both fields and the not-overwritten guarantee for component; however, there is no symmetric test for extra={"logger": …} not being overwritten — a minor asymmetry in coverage.
• A subtle edge case exists in _setup_json_exception_handlers, where a LogRecord is constructed with pathname="" / lineno=0, causing the logger field to render as ":0" rather than a meaningful value.
• All tests are mock-only with no real network calls, consistent with the tests/test_litellm/ policy.

Confidence Score: 4/5

• Safe to merge with a minor test coverage gap and a cosmetic edge case in the excepthook path.
• The core logic is sound — new fields are additive and the overwrite regression from the initial implementation has been addressed. The only open items are a missing mirror test for logger not being overwritten and the ":0" output for logs emitted from the excepthook, neither of which are blocking correctness issues.
• No files require special attention; the excepthook edge case in litellm/_logging.py is worth a follow-up but is not blocking.

Important Files Changed

Filename	Overview
litellm/_logging.py	Adds component (logger name) and logger (filename:lineno) fields to JsonFormatter output. The previous issue of user-supplied extra values being silently overwritten has been correctly addressed by placing the new assignments after the extra-attributes loop with if … not in json_record guards. Minor edge case: when pathname="" (used in json_excepthook) the logger field becomes ":0".
tests/test_litellm/test_logging.py	Three new unit tests cover the happy-path for both new fields and the not-overwritten guarantee for component. Tests are self-contained and mock-only (no network calls). Asymmetry: no corresponding not-overwritten test for the logger field, leaving a gap that a future regression could slip through undetected.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["logger.info(msg, extra={...})"] --> B["JsonFormatter.format(record)"]
    B --> C["Build base json_record\n{message, level, timestamp}"]
    C --> D["Parse embedded JSON/dict in message\n→ merge into json_record if key absent"]
    D --> E["Iterate record.__dict__\nfor non-standard attrs\n→ add to json_record if key absent"]
    E --> F{"'component' in json_record?"}
    F -- No --> G["json_record['component'] = record.name\ne.g. 'LiteLLM Proxy'"]
    F -- Yes --> H["Keep user-supplied value"]
    G --> I{"'logger' in json_record?"}
    H --> I
    I -- No --> J["json_record['logger'] = filename:lineno\ne.g. 'proxy_server.py:412'"]
    I -- Yes --> K["Keep user-supplied value"]
    J --> L["Append stacktrace if exc_info present"]
    K --> L
    L --> M["safe_dumps(json_record) → JSON string"]

Loading

_{Reviews (2): Last reviewed commit: "Let user-supplied extra fields win over ..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing J-Byron:feat/structured-json-logs-component-field (c1b2de2) with main (63425b4)}

[greptile-apps]

Weak assertion on logger field value

The test only verifies that the logger field ends with :123, but does not validate the filename portion. Since record.filename is derived from pathname as os.path.basename(pathname), the full expected value is predictable (proxy_server.py:123). Using an exact equality check would catch regressions where the filename is missing or the format changes.

Suggested change

	assert obj["logger"].endswith(":123"), (
	f"Expected logger field to end with ':123', got {obj['logger']!r}"
	)
	assert obj["logger"] == "proxy_server.py:123", (
	f"Expected logger='proxy_server.py:123', got {obj['logger']!r}"
	)

[greptile-apps]

component and logger silently shadow user-provided extra fields

The new keys component and logger are now written into json_record before the extra attributes loop runs. Because the loop skips keys already present (if key not in json_record), any caller that passes extra={"component": "my-service"} or extra={"logger": "custom"} will have their value silently dropped in favour of the auto-generated ones.

This is a subtle, hard-to-debug data-loss issue for users who are already using these field names for their own routing metadata:

verbose_proxy_logger.info("event", extra={"component": "auth-service"})
# JSON output will show component="LiteLLM Proxy" — the user's value is lost

Consider one of the following mitigations:

• Allow extra fields to win (move the new fields after the extra loop, and only set them if they are not already present).
• Or document these as reserved keys and raise a warning when they are overridden.

The simplest safe fix is to apply the same guard already used for embedded-JSON keys:

# After the extra-attributes loop, set component/logger only if not already set by extra
if "component" not in json_record:
    json_record["component"] = record.name
if "logger" not in json_record:
    json_record["logger"] = f"{record.filename}:{record.lineno}"

[greptile-apps]

Missing symmetric test for logger not being overwritten

There is a test verifying that a user-supplied component in extra is not silently dropped (test_json_formatter_extra_component_not_overwritten), but no equivalent test for the logger field. Both fields are guarded by the same if … not in json_record check, so the gap in test coverage means a future refactor that changes the ordering of one guard but not the other would go undetected.

Add a counterpart test to close this gap:

def test_json_formatter_extra_logger_not_overwritten():
    """User-supplied extra={"logger": "..."} must not be silently dropped."""
    formatter = JsonFormatter()
    record = logging.LogRecord(
        name="LiteLLM Proxy",
        level=logging.INFO,
        pathname="proxy_server.py",
        lineno=1,
        msg="event",
        args=(),
        exc_info=None,
    )
    record.logger = "custom-logger-value"
    obj = json.loads(formatter.format(record))
    assert obj["logger"] == "custom-logger-value", (
        f"User-supplied logger was overwritten, got {obj['logger']!r}"
    )

[greptile-apps]

Empty pathname yields uninformative ":0" for the logger field

The json_excepthook created in _setup_json_exception_handlers constructs a LogRecord with pathname="" and lineno=0:

record = logging.LogRecord(
    name="LiteLLM",
    level=logging.ERROR,
    pathname="",   # <-- empty
    lineno=0,      # <-- zero
    ...
)

record.filename is os.path.basename("") which evaluates to "", so the resulting logger field is ":0" — not particularly useful for debugging.

Consider guarding against this edge case:

Suggested change

	if "logger" not in json_record:
	json_record["logger"] = f"{record.filename}:{record.lineno}"
	if "logger" not in json_record:
	if record.filename and record.lineno:
	json_record["logger"] = f"{record.filename}:{record.lineno}"

[J-Byron]

@shivamrawat1

Screenshot shows structured JSON log output with component and logger fields added to every log line. Each internal LiteLLM subsystem gets its own component value (LiteLLM, LiteLLM Proxy, LiteLLM Router) alongside uvicorn's own loggers — making it easy to filter by source in Datadog, CloudWatch, or any other log aggregator.

The logger field also includes the filename and line number (e.g. proxy_server.py:807) so you can trace exactly where a log came from without digging through the codebase.