From 2aa65cdd81b9fcfcd14c58347658475b1318d060 Mon Sep 17 00:00:00 2001 From: Yucheng Zhu Date: Wed, 19 Aug 2026 18:56:10 -0700 Subject: [PATCH] style(observability): cut the rationale comments back to what the code needs The review flagged the added commentary against the repo rule that comments are for genuinely complex logic, suppressions and TODOs. Measured, this stack was running about 9.7 percent comment lines against a 6 percent baseline for litellm/, so the point stands. The design rationale these blocks carried now lives in the PR description, where it does not have to be kept in sync with the code. Suppression reasons and the short notes on genuinely counterintuitive behaviour are kept. --- litellm/proxy/db/log_db_metrics.py | 18 ++++++------------ litellm/types/integrations/prometheus.py | 5 ++--- 2 files changed, 8 insertions(+), 15 deletions(-) diff --git a/litellm/proxy/db/log_db_metrics.py b/litellm/proxy/db/log_db_metrics.py index 96bd1d3fa18..c0111dc77ea 100644 --- a/litellm/proxy/db/log_db_metrics.py +++ b/litellm/proxy/db/log_db_metrics.py @@ -20,12 +20,10 @@ if TYPE_CHECKING: from litellm.integrations.prometheus import PrometheusLogger from litellm.proxy.db.db_pool_metrics import SupportsPoolSample -# Marks a P2024 that has already been counted, so nested decorated helpers do -# not each count the same timeout. +# Marks a P2024 already counted, so nested decorated helpers do not recount it. _POOL_TIMEOUT_COUNTED: Final = "_litellm_db_pool_timeout_counted" -# One sampler per process. The pool it reads is per-process too, so there is -# nothing to key this by. +# One sampler per process; the pool it reads is per-process too. _pool_metrics_sampler: Final = DBPoolMetricsSampler() @@ -127,11 +125,8 @@ def log_db_metrics(func): end_time: datetime = datetime.now() from litellm.proxy.proxy_server import proxy_logging_obj - # Dispatched, never awaited. Awaiting here would add a suspension - # point after the query already succeeded, so a client disconnect in - # that window would discard a completed result and skip the success - # hook below. The claim is atomic, so a burst spawns one task rather - # than one per caller. + # Never awaited: a suspension point here would let a client + # disconnect discard a query that already succeeded. if _pool_metrics_sampler.try_claim(): asyncio.create_task(_sample_db_pool_metrics()) @@ -207,9 +202,8 @@ async def _handle_logging_db_exception( ) -> None: from litellm.proxy.proxy_server import proxy_logging_obj - # Counted before the DB-relatedness gate below: a pool timeout is the proxy - # running out of connections, so it must be recorded whether or not the - # failure is classified as a DB service failure. + # Counted before the DB-relatedness gate: a pool timeout is this proxy out of + # connections, however the failure is later classified. _record_db_pool_timeout_if_exhausted(e) # don't log this as a DB Service Failure, if the DB did not raise an exception diff --git a/litellm/types/integrations/prometheus.py b/litellm/types/integrations/prometheus.py index 44914460149..3c21f0b4332 100644 --- a/litellm/types/integrations/prometheus.py +++ b/litellm/types/integrations/prometheus.py @@ -776,9 +776,8 @@ class PrometheusMetricLabels: litellm_check_batch_cost_last_run_timestamp: list[str] = [] - # Database connection pool saturation. Deliberately unlabelled: the pool is a - # per-worker resource, and any key/team/user label would both be meaningless - # here and blow up cardinality on a metric scraped from every pod. + # Unlabelled: the pool is per-worker, so key/team/user labels would only add + # cardinality. litellm_db_pool_connections_max: tuple[str, ...] = () litellm_db_pool_connections_busy: tuple[str, ...] = () litellm_db_pool_connections_idle: tuple[str, ...] = ()