Metadata-Version: 2.4
Name: smello-server
Version: 0.12.0
Summary: A local dashboard for inspecting Python HTTP traffic, tests, logs, and exceptions
Project-URL: Homepage, https://github.com/smelloscope/smello
Project-URL: Repository, https://github.com/smelloscope/smello
Project-URL: Issues, https://github.com/smelloscope/smello/issues
Author-email: Roman Imankulov <roman@smello.io>
License-Expression: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.14
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: rich>=13.0.0
Requires-Dist: tortoise-orm>=0.22.0
Requires-Dist: typer>=0.15.0
Requires-Dist: uvicorn[standard]>=0.34.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/smelloscope/smello/main/docs/assets/logo.png" alt="Smello logo" width="160">
</p>

# Smello Server

A local web dashboard for inspecting outgoing and incoming HTTP requests, pytest results, logs, and exceptions captured by the [smello](https://pypi.org/project/smello/) client SDK.

## Setup

```bash
pip install smello-server
smello-server
```

Or run with Docker:

```bash
docker run -p 127.0.0.1:5110:5110 ghcr.io/smelloscope/smello
```

The server listens at `http://localhost:5110`.

Then install the client SDK and run your code with Smello:

```bash
pip install smello
smello run my_app.py
```

Outgoing HTTP requests, pytest results, unhandled exceptions, and optional log records are captured automatically.

Failed outgoing calls retain exception details. If a library raises after receiving a
response, Smello stores both the response status and headers and the exception.

To capture tests, install the client with `pip install "smello[pytest]"`. The bundled plugin supports pytest 7 and later.

Pytest events include runtime trace and span IDs plus stable collection memberships.
Outgoing Requests, HTTPX, aiohttp, botocore, and gRPC calls inherit the active test
membership as child operations. The dashboard always shows runtime parenthood. Its
**Group** selector can add one available pytest level or remote-host grouping without
changing event deep links. Virtual groups merge only across adjacent siblings, which
preserves record order.
Timeline filters retain matching records' runtime ancestors, so filtered children remain
connected to their runtime context.

See [Debug pytest tests with Smello](https://smello.io/guides/debug-pytest/) for a runnable example and dashboard walkthrough.

Calls to the OpenAI, Anthropic, and Gemini APIs render as a readable conversation in the dashboard, with the system prompt, tool calls, and token usage broken out. The raw JSON stays one tab away.

## API

Smello Server provides a JSON API for exploring captured events from the command line.

```bash
# List all captured events (unified timeline)
curl -s http://localhost:5110/api/events | python -m json.tool

# Filter by event type (http, http_incoming, test, log, exception)
curl -s 'http://localhost:5110/api/events?event_type=exception'

# Filter by method, host, status, or full-text search
curl -s 'http://localhost:5110/api/events?method=POST&host=api.stripe.com'

# Filter by app or session
curl -s 'http://localhost:5110/api/events?app=myapp&session=debug-payment'

# Get full event details
curl -s http://localhost:5110/api/events/{id} | python -m json.tool

# Clear all events
smello clear

# Equivalent HTTP API call
curl -X DELETE http://localhost:5110/api/events
```

## CLI Options

```bash
smello-server --host 0.0.0.0 --port 5110 --db-path /tmp/smello.db  # LAN access
```

## Event retention

Smello Server deletes events older than seven days when it starts and every hour after that. Set `SMELLO_RETENTION_DAYS` to a non-negative integer to change the retention period:

```bash
SMELLO_RETENTION_DAYS=30 smello-server
```

Set it to `0` to keep events indefinitely. The server rejects negative or malformed values at startup.

## Requires

- Python >= 3.14

## Links

- [Documentation](https://smello.io)
- [Source & Issues](https://github.com/smelloscope/smello)
- [Changelog](https://github.com/smelloscope/smello/blob/main/server/CHANGELOG.md)
- [smello client SDK on PyPI](https://pypi.org/project/smello/)
