🚀 Конфиг, логи и готовность к проду
Сервис с ноутбука от сервиса, который можно выкатить, отличают четыре вещи: откуда он берёт настройки и секреты, что пишет в логи, как сообщает о готовности принимать трафик и что делает с запросами, когда его останавливают. В демо их не видно, все вылезают на первом деплое. На собеседовании мидла отсюда четыре вопроса: как устроен конфиг, почему не print, как протащить request id через async-код и что будет с запросами при выкатке
⚙️ Конфиг из окружения: pydantic-settings
Настройки живут в переменных окружения. Один и тот же образ едет на стенд и в прод, отличаются только переменные. Через os.environ они приходят строками, а опечатка в имени всплывёт только на первом запросе. pydantic-settings собирает их в типизированную модель и проверяет при создании. Валидацию Pydantic разбирали в модуле про типизацию, здесь только то, что добавляет BaseSettings
from functools import lru_cache
from pydantic import BaseModel, PostgresDsn, SecretStr
from pydantic_settings import BaseSettings, SettingsConfigDict
class DbSettings(BaseModel):
dsn: PostgresDsn
pool_size: int = 10
class Settings(BaseSettings):
model_config = SettingsConfigDict(
env_prefix="BILLING_", # BILLING_DEBUG, BILLING_API_TOKEN
env_nested_delimiter="__", # BILLING_DB__POOL_SIZE → db.pool_size
env_file=".env",
extra="ignore",
hide_input_in_errors=True,
)
debug: bool = False
api_token: SecretStr
db: DbSettings
@lru_cache
def get_settings() -> Settings:
return Settings()С переменными BILLING_API_TOKEN=s3cr3t, BILLING_DB__DSN=postgresql://app:pw@db:5432/billing, BILLING_DB__POOL_SIZE=20, BILLING_DEBUG=true (pydantic-settings 2.16, Python 3.13):
>>> print(get_settings())
debug=True api_token=SecretStr('**********') db=DbSettings(dsn=PostgresDsn('postgresql://app:pw@db:5432/billing'), pool_size=20)env_prefixдописывается к имени каждого поля, и два сервиса в одном окружении не путают своиDEBUG. По умолчанию префикса нет, регистр имён не важенenv_nested_delimiterпо умолчанию не задан. Без него вложенную модельdbпередают одной переменнойBILLING_DBс JSON"20"сталоint,"true"сталоbool. Придёт"twenty"— сервис упадёт на старте с понятной ошибкой
Приоритет источников, от сильного к слабому: аргументы CLI (если включён cli_parse_args), аргументы Settings(...), переменные окружения, файл .env, каталог секретов secrets_dir, значения по умолчанию. Поэтому локальный .env на сервере перекрывают настоящие переменные
Конфиг читают один раз и на старте. Каждый Settings() заново читает окружение и .env, а отсутствующая переменная должна ронять деплой, а не первый запрос ночью. Рабочих варианта два. get_settings() под lru_cache отдаёт один и тот же объект, в FastAPI его берут через Depends(get_settings), а в тестах подменяют через app.dependency_overrides или cache_clear(). Либо Settings() создают в lifespan или фабрике приложения. Чего избегают: settings = Settings() на уровне модуля. Тогда любой импорт модуля, в том числе из теста, требует полного набора переменных
Секреты
Секрет не лежит в коде, репозитории и образе. В git коммитят .env.example с пустыми значениями, .env — в .gitignore, на сервере значения приходят из хранилища секретов переменными или файлами. SecretStr прячет значение в repr, поэтому log.info("%s", settings) не выдаст токен, а достают его явно, get_secret_value(), в месте использования. Две дыры видны в примере выше:
- пароль внутри
PostgresDsnпечатается целиком. Пароль держат отдельным полемSecretStrили делаютSecretStrвсю строку подключения - без
hide_input_in_errors=Trueошибка валидации печатает входные данные. Не хватило одной переменной, и в лог деплоя уходитField required [type=missing, input_value={'api_token': 's3cr3t'}, ...]
📝 Логирование: logging вместо print
У print нет уровня, времени и имени модуля, его нельзя приглушить для одной библиотеки и перевести в JSON. Когда stdout — пайп в контейнере, а не терминал, Python буферизует его блоками, и строки приходят в сборщик с задержкой или пропадают при падении. logging всё это умеет, и на нём уже пишут uvicorn, SQLAlchemy и httpx
| Что | Зачем |
|---|---|
| Logger | Точка входа с именем и уровнем: logging.getLogger("billing.db") |
| Handler | Куда писать: StreamHandler, FileHandler, QueueHandler |
| Formatter | Как выглядит строка: шаблон или JSON |
| Filter | Отбросить запись или дописать в неё поля |
Имена логгеров образуют дерево по точкам: billing.db.pool → billing.db → billing → корень. Запись поднимается до корня и выводится хендлерами, которые встретила по пути. Поэтому хендлер и формат вешают один раз на корень, а веткам ставят только уровень: sqlalchemy.engine на WARNING, billing на DEBUG. Отсюда и logging.getLogger(__name__) в каждом модуле: __name__ равен billing.api.orders, и дерево логгеров само повторяет структуру пакетов
Настраивают через logging.config.dictConfig один раз при старте. Ловушка: disable_existing_loggers по умолчанию True, и логгер, который появился при импорте модуля до настройки, молча выключается. У такого логгера disabled становится True, и он не пишет ни строки. Ставь False
Вызывают так: logger.info("order %s loaded in %d ms", order_id, ms). Подстановка выполнится, только если запись пройдёт по уровню, хотя сами аргументы вычисляются всегда. А одинаковый шаблон Sentry и сборщик логов группируют в одно событие, f-строка дала бы тысячу разных. logger.exception("payment failed") внутри except пишет ERROR с трейсбеком, logger.error(str(e)) трейсбек теряет
JSON-логи и structlog
В проде логи читает сборщик (Loki, VictoriaLogs, ELK), и искать удобнее по полям: request_id, order_id, level. Для этого каждая запись пишется одной строкой JSON: своим Formatter, пакетом python-json-logger или structlog, который строит запись как словарь и прогоняет через цепочку процессоров:
import structlog
structlog.configure(processors=[
structlog.contextvars.merge_contextvars, # подмешивает поля из contextvars
structlog.processors.add_log_level,
structlog.processors.TimeStamper(fmt="iso"),
structlog.processors.JSONRenderer(),
])
log = structlog.get_logger()
structlog.contextvars.bind_contextvars(request_id="req-aaa")
log.info("order loaded", order_id=42, ms=37){"order_id": 42, "ms": 37, "event": "order loaded", "request_id": "req-aaa", "level": "info", "timestamp": "..."}Что хранить в логах и как их собирать — на общей странице про логи в модуле про Docker, Kubernetes и наблюдаемость
🔗 Request id через contextvars
Строки одного запроса в логе перемешаны с чужими, и собрать их можно только по общему request id. Передавать его аргументом в каждую функцию никто не будет, а глобальная переменная и threading.local не подходят: сотни запросов идут в одном потоке и перетрут значение друг другу
contextvars.ContextVar хранит значение в контексте задачи asyncio. Каждая задача при создании получает копию контекста, а uvicorn на каждый запрос создаёт свою задачу. Значение, поставленное в middleware, видно во всём коде запроса и не видно соседним. Фильтр кладёт его в каждую запись:
import logging, logging.config, uuid
from contextvars import ContextVar
from fastapi import FastAPI, Request
request_id: ContextVar[str] = ContextVar("request_id", default="-")
class RequestIdFilter(logging.Filter):
def filter(self, record):
record.request_id = request_id.get()
return True
logging.config.dictConfig({
"version": 1,
"disable_existing_loggers": False,
"filters": {"rid": {"()": RequestIdFilter}},
"formatters": {"plain": {"format": "%(levelname)s %(name)s [%(request_id)s] %(message)s"}},
"handlers": {"console": {"class": "logging.StreamHandler",
"filters": ["rid"], "formatter": "plain"}},
"root": {"level": "INFO", "handlers": ["console"]},
})
log = logging.getLogger(__name__)
app = FastAPI()
@app.middleware("http")
async def add_request_id(request: Request, call_next):
rid = request.headers.get("x-request-id") or uuid.uuid4().hex[:8]
token = request_id.set(rid)
try:
response = await call_next(request)
finally:
request_id.reset(token)
response.headers["x-request-id"] = rid
return responseДва одновременных запроса к эндпоинту, который пишет строку, ждёт asyncio.sleep и пишет вторую. Строки перемешались, id у каждой свой:
INFO __main__ [req-aaa] loading order 1
INFO __main__ [req-bbb] loading order 2
INFO __main__ [req-bbb] order 2 loaded
INFO __main__ [req-aaa] order 1 loaded
INFO __main__ [-] outside of requestId берут из заголовка X-Request-ID, если его прислал балансировщик или соседний сервис, и возвращают в ответе, тогда цепочка находится через несколько сервисов. asyncio.create_task и asyncio.to_thread копируют контекст, loop.run_in_executor нет. Сквозной trace id между сервисами даёт OpenTelemetry, о нём — на странице про трейсы
🩺 Liveness и readiness со стороны кода
| Liveness | Readiness | |
|---|---|---|
| Вопрос | Пора перезапустить процесс? | Можно слать сюда трафик? |
| Ответ «нет» | Контейнер перезапустят | Под уберут из балансировки |
| Что проверять | Цикл событий отвечает | Старт закончился, база доступна |
@app.get("/health/live")
async def live():
return {"status": "ok"}
@app.get("/health/ready")
async def ready(response: Response):
try:
async with asyncio.timeout(1):
async with engine.connect() as conn: # engine создан в lifespan
await conn.execute(text("SELECT 1"))
except Exception:
response.status_code = 503
return {"status": "db unavailable"}
return {"status": "ok"}Liveness не ходит в базу. Иначе при аварии базы проба провалится у всех подов разом, все перезапустятся, база от этого не поднимется, а сотня подов на старте ещё и откроет пулы соединений. Пустой async def уже проверяет главное: если цикл заблокирован синхронным вызовом, эндпоинт не ответит
Readiness проверяет только то, без чего не обслужить ни одного запроса, и всегда с таймаутом. Внешнее API, нужное одному эндпоинту из двадцати, сюда не входит: его авария снимет с балансировки все поды. Соседние сервисы тоже не проверяют, иначе одна авария каскадом выключит систему
На старте один процесс uvicorn открывает порт только после lifespan startup: в логе «Application startup complete» идёт раньше «Uvicorn running on», и проба до этого получает отказ соединения. С --workers сокет заранее открывает родительский процесс, тогда 503 до конца старта должна отдавать сама readiness. Настройку проб в Kubernetes смотри на общей странице про пробы, ресурсы и деплой без простоя
🛑 Graceful shutdown: что происходит по SIGTERM
При деплое старый процесс получает SIGTERM. uvicorn 0.54 делает так:
- Закрывает слушающий сокет: новые подключения сразу получают «connection refused»
- Закрывает простаивающие keep-alive соединения, а там, где запрос ещё идёт, закроет соединение после ответа
- Ждёт задачи текущих запросов. Туда входят и
BackgroundTasksFastAPI: они выполняются после отправки ответа, но внутри того же ASGI-вызова - Шлёт приложению lifespan shutdown: закрыть пул базы, HTTP-клиенты, сбросить буферы
- Выходит, повторно отправив себе пойманный сигнал, с кодом 143
Сколько ждать на шаге 3, задаёт --timeout-graceful-shutdown. По умолчанию значение не задано, и uvicorn ждёт сколько угодно. Запрос на 2 с, фоновая задача ещё на 2 с, SIGTERM через полсекунды после начала запроса:
INFO: Shutting down
INFO: Waiting for connections to close. (CTRL+C to force quit)
3.0s handler done
INFO: 127.0.0.1:61051 - "GET /slow HTTP/1.1" 200 OK
INFO: Waiting for background tasks to complete. (CTRL+C to force quit)
5.0s background_task done
INFO: Waiting for application shutdown.
5.1s lifespan shutdownКлиент получил 200. С --timeout-graceful-shutdown 1 через секунду в логе Cancel 1 running task(s), timeout graceful shutdown exceeded, обработчик получает CancelledError, клиент — 500. Таймаут делают меньше, чем платформа ждёт до SIGKILL (в Kubernetes terminationGracePeriodSeconds, по умолчанию 30 с), иначе процесс убьют посередине и lifespan shutdown не выполнится
Задачи без ссылки пропадают молча
В том же эндпоинте была asyncio.create_task(job(...)) на 6 секунд. uvicorn про неё не знает и не ждёт: процесс завершился по сигналу, и в выводе нет ни «done», ни «CANCELLED», finally не выполнился. К тому же цикл держит на задачи только слабые ссылки, и задачу без сохранённой ссылки сборщик мусора может удалить посреди работы. Поэтому задачи хранят в множестве и дожидаются в shutdown:
tasks: set[asyncio.Task] = set()
def spawn(coro):
task = asyncio.create_task(coro)
tasks.add(task) # сильная ссылка
task.add_done_callback(tasks.discard)
return task
@asynccontextmanager
async def lifespan(app: FastAPI):
yield
if tasks: # asyncio.wait падает на пустом множестве
done, pending = await asyncio.wait(tasks, timeout=10)
for t in pending:
t.cancel()INFO: Shutting down
INFO: Waiting for application shutdown.
shutdown: waiting for 1 task(s)
email sent
INFO: Application shutdown complete.Это работает, пока процесс жив. Работе, которая должна пережить kill -9, нужна очередь: Celery, брокер или таблица задач в базе
И ещё окно на шаге 1: сокет закрыт сразу, а балансировщик узнаёт об остановке пода с задержкой, и несколько секунд трафик летит в закрытый порт. Это закрывают задержкой preStop на стороне платформы. Переключать readiness в lifespan shutdown поздно: он вызывается, когда соединения уже закрыты
📈 Sentry и метрики коротко
Sentry собирает необработанные исключения с трейсбеком и группирует одинаковые. Подключают вызовом sentry_sdk.init(dsn=..., environment=..., release=...) при старте, интеграция с FastAPI включается сама. В release пишут версию образа, чтобы видеть, с какой выкатки пошли ошибки
Метрики сервис отдаёт на /metrics через prometheus_client или OpenTelemetry. При нескольких воркерах uvicorn у prometheus_client нужен многопроцессный режим. Что мерить и как строить SLO — на общей странице про метрики, Prometheus и SLO
⚠️ Где ошибаются
.env с чужими переменными. У BaseSettings extra="forbid", и любая строка .env, не совпавшая с полем, валит старт ошибкой Extra inputs are not permitted. Падает даже строка без префикса сервиса вроде OTHER_TOOL_TOKEN, а её значение попадает в текст ошибки. Для общего .env ставят extra="ignore"
Логи пропали после настройки. dictConfig без "disable_existing_loggers": False выключил логгеры, созданные при импорте. С uvicorn похоже: он при старте применяет свой конфиг логирования. Свой передают через --log-config или настраивают в коде и запускают с log_config=None
Проверка базы в liveness. При аварии базы все поды уходят в цикл перезапусков и на каждом старте бьют по базе новыми соединениями
🎯 Вопросы с собеседований
Как устроить конфиг и секреты
Всё, что отличается между окружениями, приходит из переменных окружения, а в коде лежит модель BaseSettings из pydantic-settings с типами и значениями по умолчанию. Она приводит строки к типам и падает на старте, если переменной нет или значение кривое. env_prefix отделяет переменные сервиса, env_nested_delimiter="__" задаёт вложенные модели. Объект создают один раз: lru_cache на get_settings() или в lifespan. Секреты типа SecretStr, в git только .env.example, значения на сервере — из хранилища секретов
Как настроить логирование в сервисе и почему не print
getLogger(__name__) в каждом модуле, хендлер и формат один раз на корне через dictConfig, уровни по пакетам: имена логгеров образуют дерево, и записи поднимаются к корню. Вызывают с ленивой подстановкой logger.info("user %s", uid), ошибки — через logger.exception внутри except, чтобы был трейсбек. В проде формат JSON, чтобы искать по полям. У print нет ни уровней, ни времени, ни источника, и его не выключить для одной библиотеки
Как прокинуть request id через все логи запроса в async-коде
Через contextvars.ContextVar. Middleware берёт id из X-Request-ID или генерирует, делает set, а в finally — reset(token). Каждый запрос в uvicorn — своя задача asyncio с копией контекста, поэтому одновременные запросы не перетирают значение, в отличие от глобальной переменной или threading.local. В запись id попадает через logging.Filter или merge_contextvars в structlog. create_task и to_thread контекст копируют, run_in_executor нет
Чем liveness отличается от readiness с точки зрения кода
Liveness решает, перезапускать ли процесс, поэтому проверяет только, что цикл событий отвечает: пустой async def. Зависимости туда не кладут, иначе авария базы перезапустит все поды. Readiness решает, слать ли трафик: закончился ли старт и доступна ли база, без которой сервис бесполезен, с коротким таймаутом. Необязательные внешние API и соседние сервисы в ней не проверяют
Что происходит с запросами при деплое и остановке сервиса
По SIGTERM uvicorn закрывает слушающий сокет и простаивающие соединения, ждёт текущие запросы вместе с их BackgroundTasks, потом вызывает lifespan shutdown. По умолчанию ждёт без ограничения, --timeout-graceful-shutdown N через N секунд отменяет задачи, и клиент получает 500. Этот таймаут должен быть меньше, чем платформа ждёт до SIGKILL. Задачи из create_task без учёта uvicorn не ждёт, они пропадают молча, поэтому их хранят в множестве и дожидаются в shutdown, а важную работу кладут в очередь
📚 Что почитать
- pydantic-settings — префиксы, вложенные модели, приоритет источников, секреты из файлов
- FastAPI: Settings and Environment Variables —
lru_cacheнаget_settingsи подмена настроек в тестах - Logging Cookbook — контекст через
contextvarsи фильтры, структурированные логи - uvicorn: Settings — флаги таймаутов, логирования и остановки