feat(proxy): add LITELLM_DISABLE_ACCESS_LOG_PATHS to drop noisy access logs

[hdt12a1]

Relevant issues

Dependencies

Targets litellm_oss_branch (external-contributor branch required by the "Verify PR source branch" guard; PRs from forks to main are rejected).

Docs for the new env var live in the separate BerriAI/litellm-docs repo, which the documentation and code-quality jobs check out into docs/my-website. The matching row is in BerriAI/litellm-docs#378; that needs to merge first, otherwise tests/documentation_tests/test_env_keys.py fails with Keys not documented in 'environment settings - Reference': {'LITELLM_DISABLE_ACCESS_LOG_PATHS'}.

Linear ticket

N/A — external contributor.

Pre-Submission checklist

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

• I have added meaningful tests
• My PR passes all unit tests on make test-unit (4/4 new tests pass; targeted: pytest tests/test_litellm/test_logging.py -k healthcheck)
• 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

Screenshots / Proof of Fix

Before — k8s probes flood the proxy log (multiple lines per second), drowning real traffic:

{"message": "10.82.13.64:58658 - \"GET /health/readiness HTTP/1.1\" 200", ...}
{"message": "10.82.13.30:10944 - \"GET / HTTP/1.1\" 200", ...}
{"message": "10.82.13.140:38093 - \"GET / HTTP/1.1\" 200", ...}
{"message": "10.82.13.64:60478 - \"GET /health/liveliness HTTP/1.1\" 200", ...}
{"message": "100.65.52.208:48838 - \"GET /metrics/ HTTP/1.1\" 401", ...}

After — with LITELLM_DISABLE_ACCESS_LOG_PATHS="/,/health/liveliness,/health/readiness,/metrics/", only real traffic is logged:

{"message": "10.0.0.1:1 - \"GET /v1/chat/completions HTTP/1.1\" 200", ...}

Other application/error logs are untouched.

Tests:

$ uv run pytest tests/test_litellm/test_logging.py -k healthcheck -x -q
....                                                                     [100%]
4 passed, 10 deselected in 0.16s

Type

🆕 New Feature

Changes

Adds an opt-in env var, LITELLM_DISABLE_ACCESS_LOG_PATHS, that takes a comma-separated list of exact request paths whose uvicorn.access log lines should be dropped. Default behaviour is unchanged: when the env var is empty/unset, the filter short-circuits and all access lines are emitted as before.

Why

When the proxy runs behind kubernetes liveness/readiness probes, an ALB/NLB doing root-path health checks, and Prometheus scraping /metrics/, the access log fills with thousands of probe lines per minute. Real request lines become hard to find without external log-pipeline filtering, and the volume meaningfully inflates ingestion cost on shared log backends.

How

A new HealthCheckAccessLogFilter (logging.Filter subclass) inspects record.args — uvicorn's AccessFormatter passes (client_addr, method, full_path, http_version, status) — and returns False for any record whose path (with query string stripped) is in _DISABLED_ACCESS_LOG_PATHS. The filter is robust to malformed records (returns True on missing/short args).

It is wired in two places:

1. _get_uvicorn_json_log_config() — the JSON log_config used when JSON_LOGS=true now declares the filter under filters: and binds it on the access handler via dictConfig's native filter list.
2. _suppress_loggers() — for the non-JSON path, the filter is attached directly to logging.getLogger("uvicorn.access") at module import (only when the env var is non-empty, so there's no overhead for users who don't opt in).

Scope

• litellm.access only — application logs (LiteLLM, LiteLLM Proxy, LiteLLM Router) and uvicorn.error are untouched.
• Path matching is exact (after ? stripping). No prefix/glob matching, to keep the surface small and the behaviour obvious.
• Behind an env var so it is opt-in and trivially disabled by clearing the var.

Files changed

• litellm/_logging.py — new _parse_disabled_access_log_paths(), HealthCheckAccessLogFilter, wiring in _get_uvicorn_json_log_config() and _suppress_loggers().
• tests/test_litellm/test_logging.py — 4 new unit tests covering: env-unset pass-through, configured-path drops + non-matched paths still passing, query-string stripping before matching, and robustness to malformed args.

Example usage

# k8s deployment
env:
  - name: LITELLM_DISABLE_ACCESS_LOG_PATHS
    value: "/,/health/liveliness,/health/readiness,/metrics/"

[CLAassistant]

All committers have signed the CLA.

[codspeed-hq]

Merging this PR will not alter performance

✅ 16 untouched benchmarks

---

_{Comparing hdt12a1:feat/disable-access-log-paths (787565f) with main (343e453)}

[codecov]

Codecov Report

❌ Patch coverage is 90.00000% with 9 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
litellm/litellm_core_utils/litellm_logging.py	54.54%	5 Missing ⚠️
litellm/_logging.py	84.00%	4 Missing ⚠️

📢 Thoughts on this report? Let us know!

[greptile-apps]

Greptile Summary

This PR adds an opt-in LITELLM_DISABLE_ACCESS_LOG_PATHS env var that accepts a comma-separated list of exact request paths; any matching uvicorn.access log line is silently dropped, leaving application/error logs untouched.

• A new HealthCheckAccessLogFilter (logging.Filter subclass) reads paths from the module-level _DISABLED_ACCESS_LOG_PATHS frozenset (evaluated at import time) and drops records whose path (query-string stripped) is in the set. It degrades gracefully on malformed args.
• The filter is wired into both the non-JSON path (via _suppress_loggers()) and the JSON path (via a conditional filters entry in the dictConfig returned by _get_uvicorn_json_log_config()), correctly guarded by if _DISABLED_ACCESS_LOG_PATHS in both places, addressing the previous review comment. Four new unit tests cover env-unset pass-through, path matching, query-string stripping, and malformed-args robustness — all mocked, no network calls.

Confidence Score: 5/5

Safe to merge — the change is purely additive, opt-in via env var, and the default path (env var unset) is a no-op short-circuit with no effect on existing behaviour.

The filter is a narrow, well-guarded addition to the logging layer. It touches no request-handling code, introduces no new database or network calls, and the opt-in env var ensures zero impact for users who do not set it. Both wiring points (non-JSON and JSON log paths) are correctly gated, addressing the earlier review concern. Tests are thorough and fully mocked.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/_logging.py	Adds _parse_disabled_access_log_paths(), HealthCheckAccessLogFilter, and wires the filter into both the non-JSON (_suppress_loggers) and JSON (_get_uvicorn_json_log_config) logging paths, correctly gated on _DISABLED_ACCESS_LOG_PATHS.
tests/test_litellm/test_logging.py	Adds four well-scoped unit tests for the new filter; all use monkeypatch to avoid touching the real env var or making network calls, consistent with the repository's testing policy.

_{Reviews (2): Last reviewed commit: "fix(proxy): only wire healthcheck filter..." | Re-trigger Greptile}

[Sameerlite]

can you rebase it to "litellm_internal_staging"?

[Sameerlite]

Also please get the score to 5/5

[hdt12a1]

Done on both. Rebased onto litellm_internal_staging (also retargeted the PR base to it), and addressed the Greptile P2 by guarding the JSON log config the same way _suppress_loggers() does: the healthcheck filter and its access-handler attachment are now only wired when LITELLM_DISABLE_ACCESS_LOG_PATHS is set, so JSON_LOGS=true users who haven't opted in get no extra dictConfig machinery.

Hi @Sameerlite , please help me review again. Thanks!

[hdt12a1]

@greptileai