Connection pool metrics

[eilon-shai]

Hi,

can you please provide an example of collecting the connection pool status, I want to be able to
get insight regarding the free vs used connection in the pool
I thought about a seperate thread that pull the information and report it in some interval but I cant find a way to get this information

Thanks,
Eilon

[SirHegel]

There is no public metrics API on httpx.Client, but the pool underneath it is an httpcore.ConnectionPool, and that object exposes what you need:

• pool.connections is a public property returning the list of connection objects currently in the pool (httpcore/_sync/connection_pool.py).
• Each connection has is_idle(), is_available(), has_expired(), is_closed() and info() (httpcore/_sync/connection.py, delegating to the HTTP/1.1 or HTTP/2 implementation).
• repr(pool) already summarises it: <ConnectionPool [Requests: 3 active, 2 queued | Connections: 3 active, 0 idle]>.

The only non-public step is reaching the pool from the client: client._transport is the HTTPTransport, and HTTPTransport._pool is the ConnectionPool (httpx/_transports/default.py). Both are underscore attributes, so pin the versions you validate against.

import httpx

def pool_stats(client: httpx.Client) -> dict[str, int]:
    pool = client._transport._pool  # httpcore.ConnectionPool
    conns = pool.connections
    return {
        "connections": len(conns),
        "active": sum(not c.is_idle() for c in conns),
        "idle": sum(c.is_idle() for c in conns),
        "expired": sum(c.has_expired() for c in conns),
        "queued_requests": sum(r.is_queued() for r in pool._requests),
    }

Sampled from another thread while five requests run against a max_connections=3 client, this gives {'connections': 3, 'active': 3, 'idle': 0, 'expired': 0, 'queued_requests': 2}, and {'connections': 3, 'active': 0, 'idle': 3, ...} once they finish (httpx 0.28.1, httpcore 1.0.9). Reading pool.connections from a background thread is fine: it returns a copy of the list, and the sync pool guards its own state with a lock. pool._requests (the queue) is private, so treat "queued" as best-effort; for the connection counts, pool.connections is the supported surface. If you configure a proxy, _pool is an httpcore.HTTPProxy / SOCKSProxy instead, which subclass ConnectionPool and expose the same property.

For AsyncClient the names are identical (httpcore.AsyncConnectionPool), but sample from the same event loop rather than a thread.

Docs for the pool API: https://www.encode.io/httpcore/connection-pools/