smello 0.8.0

Capture outgoing HTTP requests and inspect them in a local web dashboard

Smello

Capture outgoing HTTP requests from your Python code and browse them in a local web dashboard — including gRPC calls made by Google Cloud libraries.

Like Mailpit, but for HTTP requests.

Setup

Install the client SDK and the server:

pip install smello smello-server

Start the server:

smello-server run

Add two lines to your code:

import smello
smello.init(server_url="http://localhost:5110")

import requests
resp = requests.get("https://api.stripe.com/v1/charges")

# Browse captured requests at http://localhost:5110

Smello monkey-patches requests, httpx, aiohttp, grpc, and botocore to capture outgoing traffic. Browse results at http://localhost:5110.

Or leave smello.init() without arguments and set SMELLO_URL in your environment — no URL, no side effects.

Run without modifying code

For programs you don't want to (or can't) edit, wrap them with smello run:

smello run my_app.py                                    # .py files run with current Python
smello run --server http://localhost:5110 pytest tests/  # console scripts work directly
smello run uvicorn app:app

Smello activates in the wrapped process before user code runs. Subprocess instrumentation propagates automatically through PYTHONPATH, so wrapping gunicorn also captures traffic from worker processes.

CLI flags map 1:1 to the SMELLO_* env vars: --server, --capture-host, --ignore-host, --capture-all / --no-capture-all, --redact-header, --redact-query-param.

Google Cloud libraries

Many Google Cloud Python libraries — BigQuery, Firestore, Pub/Sub, Analytics Data API (GA4), Vertex AI, Speech-to-Text, Vision, Translation, and others — use gRPC under the hood. Smello captures these calls automatically:

import smello
smello.init(server_url="http://localhost:5110")

from google.cloud import bigquery
client = bigquery.Client()
rows = client.query("SELECT 1").result()

# gRPC calls to bigquery.googleapis.com appear at http://localhost:5110

Any library that calls grpc.secure_channel() or grpc.insecure_channel() is automatically captured.

What Smello Captures

• Method, URL, headers, and body
• Response status code, headers, and body
• Duration in milliseconds
• Library used (requests, httpx, aiohttp, grpc, or botocore)

Smello redacts sensitive headers (Authorization, X-Api-Key) by default and optionally redacts query string parameters.

Configuration

smello.init(
    server_url="http://localhost:5110",       # where to send captured data
    capture_hosts=["api.stripe.com"],         # only capture these hosts
    capture_all=True,                          # capture everything (default)
    ignore_hosts=["localhost"],               # skip these hosts
    redact_headers=["Authorization"],         # replace header values with [REDACTED]
    redact_query_params=["api_key", "token"], # replace query param values with [REDACTED]
)

All parameters fall back to SMELLO_* environment variables when not passed explicitly:

Parameter	Env variable	Default
server_url	SMELLO_URL	None (inactive)
capture_all	SMELLO_CAPTURE_ALL	True
capture_hosts	SMELLO_CAPTURE_HOSTS	[]
ignore_hosts	SMELLO_IGNORE_HOSTS	[]
redact_headers	SMELLO_REDACT_HEADERS	["Authorization", "X-Api-Key"]
redact_query_params	SMELLO_REDACT_QUERY_PARAMS	[]

The server URL is the activation signal — init() does nothing unless server_url is passed or SMELLO_URL is set. Boolean env vars accept true/1/yes and false/0/no (case-insensitive). List env vars are comma-separated.

Supported Libraries

• requests — patches Session.send()
• httpx — patches Client.send() and AsyncClient.send()
• aiohttp — patches ClientSession._request() to capture async HTTP traffic
• grpc — patches insecure_channel() and secure_channel() to intercept unary-unary calls
• botocore — patches URLLib3Session.send() to capture boto3 / AWS SDK traffic

Requires

• Python >= 3.10
• smello-server running locally

Links

• Documentation & Source
• smello-server on PyPI