배포 가이드
django-wireview 앱을 운영에 올릴 때의 설정이다.
ASGI 서버#
권장: uvicorn + uvloop#
pip install uvicorn[standard] uvloop
uvicorn myproject.asgi:application --host 0.0.0.0 --port 8000 --workers 4 --loop uvloop \
--ws-per-message-deflate false
wireview가 uvicorn의 종료 결함을 막는다(#226). uvicorn 0.50부터 기본 WebSocket 구현(--ws auto)은
websockets-sansio다. 이 구현과 --ws wsproto의 shutdown()은, 페이지가 먼저 닫기 시작한 연결이 남아 있을 때
종료 신호를 받으면 예외를 던진다. 그 예외가 종료 절차 전체를 끊어, 남은 연결은 1012로 닫히지 않고 앱 태스크
(leaving())를 기다리는 단계도 건너뛴다(롤링 배포). 페이지가 오가는 서버에서는 흔한 순간이다.
wireview는 첫 WebSocket 연결 때 이 메서드를 감싸, 그 경우의 예외만 받고 연결을 닫는다. 메서드가 결함이 있는
모양일 때만 적용하므로 uvicorn이 고치면 저절로 빠지고, 프로세스 전체에 걸리므로 같은 서버의 다른 앱 소켓도 함께
고쳐진다. 그래서 --ws 옵션은 기본값 그대로 둔다. 끄려면 WIREVIEW = {"PATCH_UVICORN_SHUTDOWN": False}다.
permessage-deflate를 끄는 이유. uvicorn은 WebSocket 압축을 기본으로 협상하고, 그러면 연결마다 zlib의 deflate·inflate 컨텍스트를 들고 있게 된다 — 실측 연결당 159KB다. uvicorn이 연결당 daphne보다 4배 무거워 보이는 이유가 통째로 이것이다(2,000연결에서 211KB 대 46KB, 압축을 끄면 51KB). wireview가 보내는 것은 잘 안 줄어드는 작은 diff라서(전형적인 이벤트 페이로드가 16% 남짓 줄어든다) 그 메모리로 사는 대역폭이 거의 없다.
보안 이유도 있다. 압축은 한 연결의 메시지들을 한 문맥(컨텍스트 테이크오버, 32KB 창)에서 줄인다. 그 안에서 연결의 비밀 — 페이지에 그린 개인 정보, 컴포넌트 폼의 CSRF 토큰(연결마다 하나) — 이 다른 사용자가 정한 텍스트(채팅 메시지, 스트림 항목) 옆에 거듭 실리면, 경로를 엿보는 쪽이 압축된 길이로 그 비밀을 맞혀 볼 수 있다(BREACH·CRIME). Django가 HTTP 응답마다 CSRF 마스크를 바꾸는 이유가 이것인데, 소켓은 응답이 하나가 아니라 연결 내내 이어진다. 그래서 운영에서는 끈다. 첫 렌더나 스트림이 큰 HTML을 밀어내 대역폭이 정말 문제일 때에만, 양쪽을 재 보고 그 위험을 받아들일 수 있는 화면에서 켠다. daphne는 압축을 협상하지 않는다.
make bench ARGS="--connections 2000 --server uvicorn"
make bench ARGS="--connections 2000 --server uvicorn-nodeflate"
Docker 예:
FROM python:3.13-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
# 앞단 웹 서버가 서빙할 /static/을 STATIC_ROOT에 모은다(아래 「정적 파일」). STATIC_ROOT = BASE_DIR / "staticfiles"이면
# /app/staticfiles다. 이 파일은 이 이미지 안에 있다 — 앞단이 거기에 닿는 길은 「정적 파일」의 컨테이너 배포를 본다.
# collectstatic도 설정을 import하므로, 설정이 빌드 때 없는 환경 변수(비밀 키 등)를 요구하면 이 줄에만 임시 값을 준다.
RUN python manage.py collectstatic --noinput
CMD ["uvicorn", "myproject.asgi:application", "--host", "0.0.0.0", "--port", "8000", "--workers", "4", "--loop", "uvloop", "--ws-per-message-deflate", "false"]
대안: Daphne#
Django Channels의 레퍼런스 ASGI 서버다.
pip install daphne
daphne -b 0.0.0.0 -p 8000 myproject.asgi:application
대안: Hypercorn#
HTTP/2를 지원한다.
pip install hypercorn
hypercorn myproject.asgi:application --bind 0.0.0.0:8000 --workers 4
권하지 않는 것: Granian#
Rust로 만든 ASGI 서버라 빨라 보이지만, wireview 앱에서는 처리량이 압축 끈 uvicorn과 측정 편차 안에서 엎치락뒤치락하고
연결당 메모리는 더 쓴다. 무엇보다 SIGTERM에 leaving()을 끝까지 돌려 주지 않는다 — 닫힘 프레임 없이 0.1초 안에
프로세스가 끝나서, leaving()에서 presence를 지우거나 DB에 쓰는 앱은 배포할 때마다 그 정리를 잃는다(daphne도 종료할 때
leaving()을 시작만 하고 끝까지 기다리지 않는다, SIGTERM 드레인 절차).
--workers-kill-timeout을 줘도 같다. 프록시 헤더도 CLI 옵션이 없어 granian.utils.proxies.wrap_asgi_with_proxy_headers로
application을 감싸야 한다. 두 기계(macOS, Windows 10 실기)의 수치와 종료 동작 표는
성능 가이드에 있다.
채널 레이어#
이 프로젝트가 겨냥하는 것은 NATS다. E2E 스위트가 그 위에서 돌고 아래 배포 레시피도 그것을 전제한다.
channels_redis도 완전히 지원하며, Redis가 이미 인프라에 있다면 그쪽이 맞다. 나란히 재 보면 성능은
대등하므로(docs/design/transport-abstraction.md §5-3) 선택은 운영 문제다.
운영: NATS#
channels-nats는 채널 레이어를 NATS 서버 위에서 돌린다. Go 바이너리 하나이고 Linux·macOS·Windows
네이티브 빌드가 있으며 운영할 영속성 계층이 없다. 컨슈머와 wireview 코드는 그대로이고 설정만 다르다.
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_nats.NatsChannelLayer",
"CONFIG": {"servers": [os.environ["NATS_URL"]]},
}
}
같은 NATS 서버를 가리키는 서버 프로세스 여럿이 레이어 하나를 공유한다. 단일 서버 SQLite 배포에 필요한 것은 이게 전부이고, SQLite + Windows 전제에서 빠져 있던 조각이 이것이었다. 토큰 인증, Windows 서비스 등록, channels_redis와의 차이는 channels-nats README에 있다.
운영: Redis#
# settings.py
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {
"hosts": [{"address": "redis://redis:6379", "socket_timeout": None}],
"capacity": 1500,
"expiry": 10,
},
},
}
socket_timeout: None을 적는 이유. redis-py 8부터 연결의 읽기 시한(socket_timeout)이 기본 5초다. 그런데
channels_redis 4.3은 메시지를 기다릴 때 Redis에서 5초씩 블로킹하므로(BZPOPMIN), 5초 동안 조용한 채널의 읽기가
redis.exceptions.TimeoutError로 끝난다 — 소켓이 몇 초마다 끊기고 페이지가 다시 붙는 일이 되풀이된다
(django/channels_redis#422). redis-py 7 이하에서는 기본값이
None이라 적지 않아도 같다. 튜플(("redis", 6379))로 적은 항목에는 옵션을 붙일 수 없으므로 dict로 적는다.
Redis 여러 대(샤딩):
hosts에 여럿을 적으면 channels_redis가 채널·그룹 이름의 해시로 서로 독립된 Redis 서버들에 나눠 싣는다.
Redis Cluster 모드가 아니다 — Cluster의 노드 목록을 적으면 안 된다. 모든 프로세스가 같은 목록을 같은 순서로
가져야 같은 그룹이 같은 서버로 간다. 한 서버가 죽으면 그 서버에 해시된 그룹의 브로드캐스트가 사라지므로,
샤딩은 처리량을 늘릴 뿐 가용성을 높이지 않는다.
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {
"hosts": [
{"address": "redis://redis-shard-1:6379", "socket_timeout": None},
{"address": "redis://redis-shard-2:6379", "socket_timeout": None},
{"address": "redis://redis-shard-3:6379", "socket_timeout": None},
],
},
},
}
장애 조치가 필요하면 각 항목을 Sentinel이 지키는 마스터로 적는다.
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels_redis.core.RedisChannelLayer",
"CONFIG": {
"hosts": [
{
"sentinels": [("sentinel-1", 26379), ("sentinel-2", 26379)],
"master_name": "wireview",
"socket_timeout": None,
},
],
},
},
}
개발: In-Memory#
개발과 단일 프로세스 테스트 전용이다. 프로세스가 둘 이상이면 실패하지 않고 보내는 프로세스의 연결에만 브로드캐스트를 전달하고 나머지는 버린다.
CHANNEL_LAYERS = {
"default": {
"BACKEND": "channels.layers.InMemoryChannelLayer"
}
}
Windows 단일 서버: uvicorn × N + Caddy, NATS, SQLite#
2026-09-08에 Windows 11 게스트에서 실측했다(docs/design/transport-abstraction.md §5-2,
bench/results/win11-parlab-*.json). 구성을 결정하는 Windows 사실이 둘이다.
- Windows에서 daphne를 쓰지 않는다. daphne는 asyncio를 selector 루프로 고정하는데 CPython의
Windows
select()는 소켓 512개가 상한이다. daphne 프로세스는 연결 500개 근처에서ValueError: too many file descriptors in select()로 죽는다. - Windows에서
uvicorn --workers를 쓰지 않는다. 다중 워커 모드도 같은 selector 루프로 떨어진다. 단일 프로세스 uvicorn은 IOCP 위에서 돌아 벤치마크에서 2,000연결을 버텼다. 포트마다 uvicorn을 하나씩 띄우고 Caddy가 연결을 분배하게 한다.
Windows에서는 INSTALLED_APPS에서 "daphne"도 뺀다. runserver를 받쳐 줄 뿐인데 import되는 것만으로
프로세스 전체의 asyncio 정책이 바뀐다.
# 코어마다 단일 프로세스 uvicorn 하나, 각자 자기 포트에 (--workers 없이).
# 운영에서는 NSSM이나 작업 스케줄러로 서비스 등록한다.
1..4 | ForEach-Object {
Start-Process uvicorn -ArgumentList "myproject.asgi:application --host 127.0.0.1 --port $(8000 + $_) --ws-per-message-deflate false"
}
:80 {
handle_path /static/* {
root * C:/srv/myproject/staticfiles # STATIC_ROOT. 배포마다 collectstatic
file_server
}
reverse_proxy 127.0.0.1:8001 127.0.0.1:8002 127.0.0.1:8003 127.0.0.1:8004
}
Caddy는 바이너리 하나이고 WebSocket 업그레이드를 알아서 처리하며 TLS 종단도 맡을 수 있다. /static/도 Caddy가
서빙한다 — 운영(DEBUG = False)의 uvicorn은 정적 파일을 서빙하지 않으므로, 그 블록을 빼면 wireview.min.js가 404가
되고 어떤 컴포넌트도 살아나지 않는다(정적 파일). 채널
레이어는 channels-nats이고 nats-server.exe를 Windows 서비스로 띄운다(channels-nats README).
SQLite는 모든 프로세스가 공유하므로 WAL과 busy timeout을 켠다. pragma는 init_command로 직접 실행한다.
DATABASES = {
"default": {
"ENGINE": "django.db.backends.sqlite3",
"NAME": BASE_DIR / "db.sqlite3",
"OPTIONS": {
"timeout": 20,
"transaction_mode": "IMMEDIATE",
"init_command": "PRAGMA journal_mode=WAL; PRAGMA synchronous=NORMAL;",
},
}
}
용량 산정: Windows에서 uvicorn은 연결당 약 160KB의 RSS를 쓰는데 거의 전부가 permessage-deflate다.
--ws-per-message-deflate false를 주면 daphne 수준으로 떨어진다(ASGI 서버).
이벤트 처리량은 uvicorn 프로세스 수에 비례한다 — 벤치마크에서 1개에서 4개로 늘렸을 때 초당 이벤트가
3배, 브로드캐스트가 3.6배 빨라졌다.
운영용 Django 설정#
# settings.py
DEBUG = False
ALLOWED_HOSTS = ["yourdomain.com"]
# wireview 설정
WIREVIEW = {
"DEBUG_SYNC_TRANSITIONS": False, # 운영에서는 끈다
# 서명 상태 (data-state)
"STATE_MAX_AGE": 14 * 24 * 3600, # data-state 유효 기간
"STATE_REFRESH_AFTER": None, # None이면 STATE_MAX_AGE // 2
# 서명 키. 미설정이면 SECRET_KEY를 쓴다
"SIGNING_KEY": None,
"SIGNING_KEY_FALLBACKS": None,
}
# 보안
CSRF_COOKIE_SECURE = True
SESSION_COOKIE_SECURE = True
SECURE_SSL_REDIRECT = True
# 데이터베이스 커넥션 재사용 (권장)
DATABASES = {
"default": {
"ENGINE": "django.db.backends.postgresql",
"NAME": "mydb",
"CONN_MAX_AGE": 60,
"CONN_HEALTH_CHECKS": True,
}
}
정적 파일#
ASGI 서버는 정적 파일을 서빙하지 않는다. {% wireview_header %}가 부르는 wireview.min.js도 정적 파일이라,
빠뜨리면 페이지는 200으로 그려지는데 어떤 컴포넌트도 살아나지 않는다 — 오류도, 검사 경고도 없다.
- 개발.
runserver는 스스로/static/을 서빙하지만 uvicorn은asgi.py의application만 서빙한다. 스타터 템플릿과 시작하기 튜토리얼의asgi.py는DEBUG일 때 HTTP 앱을django.contrib.staticfiles.handlers.ASGIStaticFilesHandler로 감싸 둘 다 된다. - 운영(
DEBUG = False). 그 래퍼는 꺼진다.STATIC_ROOT를 정하고 배포마다python manage.py collectstatic을 돌린 뒤, 앞단의 웹 서버가/static/을 서빙한다.
location /static/ {
alias /srv/myproject/staticfiles/; # STATIC_ROOT
}
yourdomain.com {
handle_path /static/* {
root * /srv/myproject/staticfiles
file_server
}
reverse_proxy localhost:8000
}
컨테이너 배포. Docker 예의 collectstatic은 파일을 앱 이미지 안에 모은다. 앞단이
호스트나 다른 컨테이너에 있으면 위의 alias가 가리키는 디렉터리는 비어 있고, 운영의 uvicorn은 정적 파일을 서빙하지
않으므로 wireview.min.js가 404다. 앞단 이미지를 앱 이미지에서 복사해 만든다.
# 위 Docker 예로 빌드한 앱 이미지. 릴리스마다 둘을 같은 태그로 함께 빌드한다
FROM myproject:1.0 AS app
FROM nginx:1.27
COPY --from=app /app/staticfiles /srv/myproject/staticfiles
# 위의 location /static/ 과 앱으로 가는 proxy_pass
COPY nginx.conf /etc/nginx/conf.d/default.conf
명명 볼륨으로 앱 컨테이너의 /app/staticfiles를 앞단과 공유하는 방법은 피한다. Docker는 비어 있는 명명 볼륨만
이미지의 내용으로 채우므로, 다음 릴리스의 이미지로 바꿔도 볼륨에는 첫 배포의 번들이 남는다(아래의 ?v=가 그것을
가리지 못한다). 볼륨을 쓴다면 컨테이너가 시작할 때마다 collectstatic을 그 볼륨에 다시 돌린다.
{% wireview_header %}는 번들 주소에 패키지 버전을 ?v=로 붙인다. 업그레이드 뒤 collectstatic을 빠뜨리면
새 버전 번호로 옛 번들을 받게 되므로, 릴리스마다 collectstatic을 배포 절차에 둔다.
WebSocket의 Origin#
WebSocket 핸드셰이크에는 브라우저의 쿠키가 실린다. 막지 않으면 로그인한 사용자가 방문한 다른 사이트의 페이지가
이 사이트로 소켓을 열어 그 사용자로 행동할 수 있다(교차 사이트 WebSocket 하이재킹, CSWSH). SameSite=Lax 세션
쿠키가 일부를 막지만, 같은 사이트의 다른 서브도메인이나 SameSite=None 설정에서는 막지 못한다.
그래서 wireview의 컨슈머는 소켓을 받기 전에 Origin 헤더의 호스트를 ALLOWED_HOSTS와 대조한다(#96).
Django가 Host 헤더에 쓰는 규칙과 같고, DEBUG이면서 ALLOWED_HOSTS가 비어 있으면 localhost를 허용한다.
asgi.py에서 AllowedHostsOriginValidator로 감쌌는지와 상관없이 켜져 있다.
Origin이 없는 연결은 통과한다. 브라우저는 WebSocket 핸드셰이크에 항상Origin을 보내므로, 없다는 것은 브라우저가 아니라는 뜻이다(서버 간 호출, 헬스체크). CSWSH에는 남의 쿠키를 실어 줄 브라우저가 필요하다.- 페이지와 소켓의 호스트가 다르면(예: 페이지는
www.example.com, 소켓은ws.example.com) 페이지의 호스트도ALLOWED_HOSTS에 있어야 한다. - 끄려면
WIREVIEW["CHECK_ORIGIN"] = False. 앞단 프록시가 같은 검사를 확실히 할 때만 끈다.
업그레이드: AUTO_BROADCAST의 필드 목록#
AUTO_BROADCAST.senders를 매핑으로 적어 보낼 필드를 줄이면(설정), 받는 쪽은
온 필드만 불러오고 나머지를 deferred로 둔다. 그 처리는 1.0부터 있다(#153). 1.0.0rc4 이전 프로세스가 같은
브로커에서 그 알림을 받으면 빠진 필드를 기본값으로 채운 인스턴스를 mutation()에 넘기고, 오류는 나지 않는다.
그런 버전에서 올리는 롤링 배포라면 모든 프로세스를 새 버전으로 올린 뒤에, 다음 배포에서 매핑 설정을 켠다.
업그레이드: 서명된 컴포넌트 상태#
v2 상태 봉투(#58) 이후 data-state 값은 발급된 컴포넌트 클래스, 페이지의 live_session, 발급
당시의 인증 세대와 함께 서명되고 WIREVIEW["STATE_MAX_AGE"](기본 14일)이 지나면 만료된다.
v1 봉투(#76)와 그 이전의 두 형식은 경계를 담고 있지 않으므로 서버가 거절한다. 예전 배포가 그린 탭이 다시 붙으면 join이 거절되고 reload 명령을 받아
새 배포에서 페이지를 다시 읽는다. 그것이 의도된 복구다 — 현재 인증 컨텍스트와 새 토큰으로 돌아온다.
롤링 배포에서 따라오는 것이 둘이다.
- 열려 있던 탭의 미저장 입력은 리로드와 함께 사라진다. 옛 토큰을 받아 주던 롤아웃 창
(
STATE_ACCEPT_LEGACY)은 1.0 전에 없어졌다(#99). v2 봉투 이전 토큰은 0.3.0 이전 배포가 그린 탭에만 있고, 그 탭은 한 번 새로 읽힌다. 이 거절은 서명 불일치(invalid)로 기록된다. - 모든 프로세스가
SECRET_KEY를 공유해야 한다. 전에도 그랬지만, 이제 어긋나면 컴포넌트가 조용히 사라지는 대신 리로드 루프로 드러난다. 클라이언트는 30초 안에 두 번 리로드하기를 거부하고 경고를 남기므로, 설정 오류가 페이지를 돌리는 대신 브라우저 콘솔에 보인다.
live_session을 쓰는 프로젝트에는 둘 더 있다.
로그아웃이 기존 소켓을 닫는 것은 브로커를 지난다. InMemory 채널 레이어에서는 같은 프로세스의
연결에만 닿으므로, 다중 워커에서는 다른 워커가 들고 있는 소켓이 닫히지 않는다.
manage.py check --deploy의 wireview.W006이 같은 것을 가리킨다. 브로커가 있어도 그룹 발행 자체는
최선 노력이다(채널 레이어 규격이 용량 초과 시 폐기와 멤버십 만료를 허용한다). 놓친 소켓은 스스로
다시 연결할 때까지 살아 있고 그동안 이벤트를 계속 처리한다 — join 재확인이 회수하는 것은 "다음
연결"이지 "언젠가 그 연결"이 아니다.
공개로 돌던 페이지에 경계를 붙일 때는 순서가 있다. 서버는 토큰이 말하는 경계만 보고 발급 시점은
모르므로, 그 전에 발급된 경계 없는 토큰은 새 정책을 지나지 않는다. 보호할 컴포넌트에
Meta.live_sessions를 먼저 선언하고, 즉시 끊어야 하면 SIGNING_KEY를 fallback 없이 교체한다. 상세는
live_session.
세션 백엔드가 로그아웃의 의미를 정한다. signed_cookies 백엔드는 서버에 아무 기록을 남기지
않으므로, 로그인 시점의 쿠키를 보관했다가 로그아웃 뒤 다시 제출하면 같은 사용자로 인증된다(Django
자신의 한계다). 경계 뒤에 진짜 인가가 걸린 페이지가 있다면 db·cache·cached_db 중 하나를 쓴다.
상세는 live_session.
STATE_REFRESH_AFTER는 상태가 그대로여도 토큰을 다시 발급하기까지의 나이다. 반드시
STATE_MAX_AGE보다 작아야 한다. STATE_MAX_AGE - STATE_REFRESH_AFTER마다 한 번이라도 렌더되는
컴포넌트는 페이지가 열려 있는 동안 만료되지 않는다.
WebSocket 프록시#
WebSocket 은 선택이 아니라 요구사항이다. django-wireview 에는 HTTP 폴백이 없다 —
프록시가 업그레이드를 통과시키지 못하면 페이지는 첫 HTML 만 그려지고 그 뒤로 아무것도 하지 않는다.
폴백을 만들지 않기로 한 근거는 docs/design/longpolling-fallback.md §5 에 있다.
아래 설정은 "권장"이 아니라 최소 조건이다. WebSocket 업그레이드와 함께 /static/도 앞단이 서빙한다.
앱으로 넘기면 운영에서는 wireview.min.js가 404이고, 페이지는 그려지지만 어떤 컴포넌트도 살아나지 않는다(정적 파일).
Nginx#
upstream django {
server 127.0.0.1:8000;
}
server {
listen 80;
server_name yourdomain.com;
location /static/ {
alias /srv/myproject/staticfiles/; # STATIC_ROOT. 배포마다 collectstatic
}
location / {
proxy_pass http://django;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
location /__wireview__ {
proxy_pass http://django;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_read_timeout 86400;
}
}
Caddy#
yourdomain.com {
handle_path /static/* {
root * /srv/myproject/staticfiles # STATIC_ROOT
file_server
}
reverse_proxy localhost:8000
}
Caddy는 WebSocket 업그레이드를 알아서 처리한다.
AWS ALB#
- idle timeout을 최소 3600초로 둔다
- 타깃 그룹 헬스체크는 HTTP 헬스체크 경로로 건다. ALB 헬스체크는 HTTP/HTTPS만 지원해 WebSocket으로는 걸 수 없다
- sticky session(타깃 그룹 stickiness)은 켜지 않아도 된다 — 수평 확장 참고
모니터링#
볼 지표#
- 연결 — 열린 소켓 수, 연결 수명, 닫힘 코드 분포. 롤링 배포 중에는 재연결 속도
- join 거절 — 사유별 비율.
invalid가 오르면 서명 키가 인스턴스마다 다르다 - 렌더 성능 — 렌더·이벤트 지연(P50, P95, P99), diff 크기 분포
- 채널 레이어 — 거부된 메시지(
publish_failed), 레이어 자신의 유실 로그, 브로커 메모리·지연
1~3과 4의 앞부분은 telemetry 시그널로 나온다. wireview는 지표를 쌓지 않고 시그널만
보낸다. 켜려면 WIREVIEW = {"TELEMETRY": True}.
telemetry 시그널을 지표로#
수신자를 모듈 하나에 모으고 AppConfig.ready()에서 import한다. 수신자는 렌더·이벤트 경로 안에서 동기로 돌므로
카운터를 올리는 것 이상은 하지 않는다.
Prometheus (prometheus_client):
# myapp/metrics.py -- import it from MyAppConfig.ready()
from django.dispatch import receiver
from prometheus_client import Counter, Gauge, Histogram
from wireview import telemetry
CONNECTIONS = Gauge("wireview_connections", "Open wireview sockets", multiprocess_mode="livesum")
CONNECTION_SECONDS = Histogram(
"wireview_connection_seconds", "How long a socket stayed open", buckets=[1, 10, 60, 300, 1800, 3600, 14400]
)
CLOSES = Counter("wireview_connection_closes_total", "Closed sockets by close code", ["code"])
REJECTED = Counter("wireview_join_rejected_total", "Refused sockets and joins", ["reason"])
PUBLISH_FAILED = Counter("wireview_publish_failed_total", "Messages the channel layer refused", ["kind", "dropped"])
EVENT_SECONDS = Histogram("wireview_event_seconds", "Event handler time", ["component"])
RENDER_SECONDS = Histogram("wireview_render_seconds", "Template render time", ["component"])
EVENT_ERRORS = Counter("wireview_event_errors_total", "Handlers that raised", ["component"])
@receiver(telemetry.connection_opened)
def connection_opened(sender, **kwargs):
CONNECTIONS.inc()
@receiver(telemetry.connection_closed)
def connection_closed(sender, code, duration_ms, **kwargs):
CLOSES.labels(code=str(code)).inc()
# None: telemetry came on after this socket opened, so it was never counted in
if duration_ms is not None:
CONNECTIONS.dec()
CONNECTION_SECONDS.observe(duration_ms / 1000)
@receiver(telemetry.join_rejected)
def join_rejected(sender, reason, **kwargs):
# A closed set (telemetry.JOIN_REJECTED_REASONS): safe as a label
REJECTED.labels(reason=reason).inc()
@receiver(telemetry.publish_failed)
def publish_failed(sender, kind, dropped, **kwargs):
PUBLISH_FAILED.labels(kind=kind, dropped=str(dropped).lower()).inc()
@receiver(telemetry.event_handled)
def event_handled(sender, component_name, duration_ms, error, **kwargs):
EVENT_SECONDS.labels(component=component_name).observe(duration_ms / 1000)
if error is not None:
EVENT_ERRORS.labels(component=component_name).inc()
@receiver(telemetry.component_rendered)
def component_rendered(sender, component_name, duration_ms, **kwargs):
RENDER_SECONDS.labels(component=component_name).observe(duration_ms / 1000)
uvicorn --workers N처럼 프로세스가 여럿이면 prometheus_client의 multiprocess 모드(PROMETHEUS_MULTIPROC_DIR)로
돌린다. multiprocess_mode="livesum"이 살아 있는 프로세스들의 연결 수를 더한다. /metrics 노출은
django-prometheus나 prometheus_client.make_asgi_app()으로 한다.
컴포넌트 이름 라벨은 컴포넌트 클래스 수만큼만 는다. component_id는 라벨로 쓰지 않는다 — 연결마다 새로 생긴다.
OpenTelemetry (opentelemetry-api, 내보내기는 SDK와 익스포터 설정의 몫):
# myapp/otel_metrics.py -- import it from MyAppConfig.ready()
from django.dispatch import receiver
from opentelemetry import metrics
from wireview import telemetry
meter = metrics.get_meter("wireview")
connections = meter.create_up_down_counter("wireview.connections", description="Open wireview sockets")
rejected = meter.create_counter("wireview.join.rejected", description="Refused sockets and joins")
publish_failed = meter.create_counter("wireview.publish.failed", description="Messages the channel layer refused")
render = meter.create_histogram("wireview.render.duration", unit="ms", description="Template render time")
@receiver(telemetry.connection_opened)
def opened(sender, **kwargs):
connections.add(1)
@receiver(telemetry.connection_closed)
def closed(sender, duration_ms, **kwargs):
if duration_ms is not None:
connections.add(-1)
@receiver(telemetry.join_rejected)
def refused(sender, reason, **kwargs):
rejected.add(1, {"reason": reason})
@receiver(telemetry.publish_failed)
def refused_by_layer(sender, kind, dropped, **kwargs):
publish_failed.add(1, {"kind": kind, "dropped": dropped})
@receiver(telemetry.component_rendered)
def rendered(sender, component_name, duration_ms, **kwargs):
render.record(duration_ms, {"component": component_name})
두 예시는 tests/test_deployment_examples.py가 가짜 prometheus_client·opentelemetry를 끼워 실제로 돌린다.
수신자의 인자 이름이 시그널과 어긋나면 그 테스트가 실패한다.
브로드캐스트 유실은 레이어의 로그에서 세지만, 다 세지는 못한다. 연결 하나가 밀리면(컴포넌트가 알림 하나를
처리하는 동안 더 온다) 그 연결의 큐는 capacity개까지 담고, 레이어는 넘치는 것을 예외 없이 버린다.
- channels-nats — 받는 쪽 프로세스의
channels_nats로거에 WARNING(mailbox for ... is full)을 남기고 새로 온 것을 버린다. 로그는 첫 유실과 그 뒤 60초마다 한 번이고, 그때까지 버린 수를 함께 적는다. - channels_redis — 버리는 곳이 둘이다. 그 프로세스의 어느 연결도 읽지 않아 Redis에 쌓이면
group_send가 새로 온 것을 버리고channels_redis.core로거에 INFO(... channels over capacity in group ...)를 남긴다. 같은 프로세스의 다른 연결이 읽고 있으면 메시지는 연결별 프로세스 내부 버퍼로 옮겨지고, 그 버퍼가 차면 가장 오래된 것을 로그 없이 버린다. 연결이 많은 운영 프로세스에서는 뒤쪽이 흔하다. - InMemory — 로그 없이 새로 온 것을 버린다.
그래서 로그로 센 수는 하한이다. publish_failed가 잡는 것은 채널 하나로 보내다 거부된 것(ChannelFull)과
브로커 오류뿐이다.
같은 채널에는 연결이 자기에게 보내는 메일(스트림 연산, push_event, JS, defer(), joined, 잡아 둔 패치의 해제 등)도
선다. 그것은 버려도 잃지 않는다(#211): 연결이 사본을 지니고 있다가, 레이어가 거절하면 바로 다음 차례에, 말없이 버리면
뒤 메일이 먼저 오거나 5초 동안 아무것도 처리하지 않을 때 그 사본을 처리한다. 메일끼리는 보낸 순서 그대로지만, 사본으로
처리한 메일은 알림과의 자리를 잃는다. 그래서 publish_failed의 kind="send_to_session", dropped=True는 그 연결이 밀리고
있다는 신호이지 메일을 잃었다는 뜻이 아니다. 말없이 버린 것을 되찾을 때는 wireview 로거에 WARNING(... did not come ...)이
남는다. 사본에는 상한이 있다 — 처리되지 않은 메일이 1000개(MAIL_LIMIT)나 16 MiB(MAIL_BYTES)를 넘으려 하면 연결을 닫고(1013,
WARNING ... past MAIL_LIMIT ...) 페이지가 다시 join한다. 핸들러 하나가 항목을 하나씩 수백 개 넣는다면 stream()에 목록으로 넘긴다. 형식은 wire protocol.
버려진 브로드캐스트는 오류가 아니라 낡은 화면으로 남는다. 다음에 그 컴포넌트가 렌더될 때(다음 알림이나
사용자 이벤트) 템플릿이 원천에서 다시 읽는 값은 맞아지지만, 들은 것을 상태에 더해 가는 컴포넌트(채팅 목록에
메시지를 덧붙이는 식)는 버려진 것을 되찾지 못한다. 틀리면 곤란한 값은 렌더 때 다시 읽거나 사용자 액션에서
다시 조회한다. capacity(channels_redis·channels-nats·InMemory 모두 기본 100)를 늘리면 짧은 폭주는 견디지만,
계속 밀리는 연결은 결국 넘친다. 근거는 tests/test_broadcast_loss_e2e.py다.
로깅#
LOGGING = {
"version": 1,
"handlers": {
"console": {"class": "logging.StreamHandler"},
},
"loggers": {
"wireview": {
"handlers": ["console"],
"level": "WARNING", # 디버깅할 때는 INFO
},
"wireview.sync_detector": {
"handlers": ["console"],
"level": "WARNING",
},
},
}
헬스체크#
HTTP#
# urls.py
from django.http import JsonResponse
def health_check(request):
return JsonResponse({"status": "ok"})
urlpatterns = [
path("health/", health_check),
# ...
]
Readiness: 채널 레이어 왕복#
HTTP 헬스체크는 프로세스가 살아 있다는 것만 말한다. wireview의 브로드캐스트·세션 메일·로그아웃 무효화는 모두
채널 레이어를 지나므로, 브로커가 죽은 인스턴스는 페이지를 그리고 소켓도 받지만 서로의 소식을 전하지 못한다.
readiness는 레이어에 메시지를 한 번 돌려 본다. 그룹으로 보내 자기 채널에서 받으므로 wireview의 팬아웃과
같은 길(group_add → group_send → receive)이다.
# myapp/health.py
import asyncio
import uuid
from channels.layers import get_channel_layer
from django.http import JsonResponse
ROUND_TRIP_TIMEOUT = 2 # seconds
async def channel_layer_ready(request):
layer = get_channel_layer()
if layer is None:
return JsonResponse({"status": "unready", "reason": "no channel layer"}, status=503)
group = f"readiness.{uuid.uuid4().hex}"
try:
async with asyncio.timeout(ROUND_TRIP_TIMEOUT):
channel = await layer.new_channel()
await layer.group_add(group, channel)
try:
await layer.group_send(group, {"type": "readiness.ping"})
await layer.receive(channel)
finally:
await layer.group_discard(group, channel)
except Exception as error:
return JsonResponse({"status": "unready", "reason": repr(error)}, status=503)
return JsonResponse({"status": "ready"})
# urls.py
from django.urls import path
from myapp.health import channel_layer_ready
urlpatterns = [
path("health/", health_check), # liveness: the process answers
path("ready/", channel_layer_ready), # readiness: the broker answers too
]
- async 뷰다.
ATOMIC_REQUESTS를 켠 프로젝트는django.db.transaction.non_atomic_requests로 감싼다 — Django가 async 뷰를 트랜잭션으로 감쌀 수 없어 뷰를 부르기 전에 500을 낸다. - in-memory 레이어는 늘 통과한다. 같은 프로세스 안의 큐라 확인할 브로커가 없다. 운영 레이어에서만 뜻이 있다.
- liveness에 걸지 않는다. 브로커 장애는 인스턴스를 재시작해도 낫지 않는다. liveness가 이것을 보면 브로커가 잠깐 흔들릴 때 모든 인스턴스가 함께 재시작되고, 재시작마다 모든 페이지가 다시 join한다(아래 롤링 배포 절).
- 요청마다 그룹 하나를 만들고 지운다. 주기는 5~10초면 충분하다.
이 예시는 tests/test_deployment_examples.py가 in-memory 레이어와 실패하는 레이어로 돌린다.
WebSocket 핸드셰이크#
핸드셰이크만 해 보고 닫는다. ASGI 서버, 라우팅, CHANNEL_LAYERS 설정이 갖춰졌는지 본다 — 레이어 설정이
없으면 컨슈머가 accept 전에 거절한다. 브로커가 응답하는지는 보지 못한다. 레이어는 소켓을 받을 때 브로커에
묻지 않으므로(channels_redis의 new_channel은 이름만 만든다) 그것은 위의 readiness가 본다. 메시지를 보낼
필요는 없고, wireview 프로토콜에는 ping 같은 명령도 없다.
# management/commands/check_websocket.py
import websocket # pip install websocket-client
from django.core.management.base import BaseCommand
class Command(BaseCommand):
def handle(self, *args, **options):
ws = websocket.create_connection("ws://localhost:8000/__wireview__", timeout=5)
ws.close()
self.stdout.write("WebSocket OK")
wireview는 Origin 헤더가 있으면 그 호스트가 ALLOWED_HOSTS에 있어야 연결을 받는다(WebSocket의 Origin).
websocket-client는 접속 주소로 Origin을 채운다.
확장#
수평 확장#
- 브로커 기반 채널 레이어를 쓴다 (다중 인스턴스의 필수 조건)
- 세션 저장소를 공유한다 (DB, Redis/Memcached. signed-cookie 백엔드는 저장소가 필요 없다)
- 서명 키(
SECRET_KEY또는WIREVIEW["SIGNING_KEY"])를 모든 인스턴스에 같게 둔다
sticky session은 필요 없다. 로드밸런서가 요청마다 아무 인스턴스에나 보내도 된다.
- WebSocket은 101 업그레이드 뒤 TCP 연결 하나가 끝날 때까지 한 인스턴스에 머문다. sticky 설정은 여러 HTTP 요청에 걸치는 전송(long-polling 등)을 위한 것인데, wireview는 WebSocket만 쓴다 (longpolling-fallback.md).
- 페이지를 그린 인스턴스와 join을 받는 인스턴스가 달라도 된다. join은 페이지에 실린 서명된
data-state만으로 컴포넌트를 복원한다. 재연결도 같은 상태로 다시 join하므로 어디에 붙어도 된다. - 청크 업로드도 무상태다(아래 절).
인스턴스 사이에서 같아야 하는 것은 위의 세 가지와 업로드 디렉터리뿐이다. sticky를 켜도 동작은 하지만 롤링 배포 뒤 새 인스턴스로 부하가 고르게 퍼지지 않고, 켜야만 동작하는 것처럼 읽힌다.
롤링 배포와 재연결#
인스턴스 하나를 내리면 그 인스턴스가 들고 있던 소켓이 한꺼번에 닫힌다. 페이지는 다른 인스턴스로 다시 연결하고, 연결마다 페이지의 모든 컴포넌트가 서명된 상태로 다시 join한다(상태는 페이지에 있으므로 어느 인스턴스든 받는다). 그래서 롤링 배포의 부하는 요청 수가 아니라 join 수다.
재연결이 돌려주는 것#
다시 붙은 페이지는 마지막으로 받은 렌더의 상태로 돌아온다. 페이지를 처음 로드했을 때의 상태가 아니다.
data-state는 상태를 바꾼 렌더마다 새로 서명되어 그 렌더의 diff에 실린다. 상태가 그대로인 렌더는 같은 토큰을 다시 쓴다(STATE_REFRESH_AFTER가 지나기 전까지). 재연결의 join이 보내는 것이 이 속성이다.- 받는 서버에 필요한 것은 서명 키뿐이다. 페이지를 그린 프로세스가 재시작했든 다른 워커가 받든 페이지는 새로고침 없이 이어진다.
- 사용자가 입력하고 아직 보내지 않은 값은 입력란에 그대로 남는다. join의 렌더도 사용자가 고친 값을 덮지 않는다.
그 값을 서버에 다시 알리려면
wire-auto-recover를 단다. - 돌아오지 않는 것: 서명 상태에 실리지 않는 값(
Meta.exclude_fields, temporary assign —joined()에서 다시 읽는다), 끊긴 동안 보낸 이벤트와 훅의pushEvent(버려진다), 끊긴 동안의 브로드캐스트. - 서명이 맞지 않거나(서명 키가 다른 서버)
STATE_MAX_AGE보다 오래된 상태는 거절되고 페이지가 새로고침된다. 그때는 페이지 로드 때의 상태로 시작하고 입력하던 값도 사라진다.
근거는 tests/test_reconnect_state_e2e.py(같은 서버·재시작한 프로세스·다른 워커)와 tests/test_signed_state.py(거절)다.
필드를 바꾸는 배포#
배포가 컴포넌트의 필드를 바꾸면, 열려 있던 페이지는 옛 클래스가 서명한 상태로 새 클래스에 join한다(#231).
서버는 그 상태를 앱 코드(on_mount 훅, joined())가 돌기 전에 새 클래스로 읽고, 둘 중 하나로 답한다.
- 받아들이면 이어진다. 새로고침 없이 그 상태에서 계속한다.
- 받아들이지 않으면 한 번 새로고침한다(
reload, 사유stale). 새 코드가 페이지를 다시 그리고 자기 상태를 낸다. 입력하던 값과 상태는 페이지 로드 때의 것으로 돌아간다.
| 바꾼 것 | 결과 |
|---|---|
| 기본값 있는 필드 추가 | 이어진다. 새 필드는 기본값 |
| 기본값 없는 필드 추가 | 새로고침 |
| 필드 삭제 | 이어진다. 옛 값은 버린다 |
값이 들어맞는 타입 변경(int → float) |
이어진다. Pydantic이 바꾼다 |
값이 들어맞지 않는 타입 변경(int → list[int]) |
새로고침 |
| 필드 이름 변경 | 삭제와 추가다. 새 이름에 기본값이 있으면 그 값으로 이어지고, 없으면 새로고침 |
모델 필드가 다른 모델을 가리킴(book: Book → book: Author) |
새로고침. 상태에는 pk만 있어 다른 모델의 같은 번호 행으로 읽힐 것이었다 |
앱의 검증기(@field_validator)가 옛 값을 거절 |
새로고침 |
필드를 Meta.exclude_fields·Meta.temporary_assigns에 넣음 |
이어진다. 옛 값은 버리고, 그 클래스의 모든 join처럼 시작한다 |
| 클래스 이름 변경·삭제 | 새로고침(사유 invalid) |
on_mount·joined()가 던짐 |
새로고침이 아니다. join 실패다(errors) |
부모의 join에 딸려 온 자식(LiveComponent, 중첩된 {% component %})의 상태를 새 클래스가 받아들이지 않으면
그 상태만 버리고, 자식은 부모 템플릿이 넘기는 값으로 새로 시작한다. 부모는 이어진다. 서명이 맞지 않는 자식
상태와 같은 처리다.
새로고침은 고리가 되지 않는다. 새로 그린 페이지의 상태는 새 클래스가 서명한 것이라 받아들여진다. 그래도 거절되면(프로세스마다 코드가 다르면) 클라이언트가 30초 안의 두 번째 새로고침을 막고 콘솔에 경고를 남긴다.
끊김 없이 배포하려면:
- 새 필드에는 기본값을 준다. 그러면 열린 페이지가 새로고침 없이 이어진다.
- 뜻이 바뀐 필드는 이름도 바꾼다. 서버는 타입만 보므로 같은
int가 원에서 센트로 바뀐 것은 모른다. 이름을 바꾸면 옛 값은 버려지고 새 이름의 기본값으로 시작한다. - 두 버전이 함께 도는 롤링 배포에서는 받아들이지 않는 변경의 새로고침이 옛 프로세스에 닿아 옛 상태를 다시 받을 수 있다. 그 사이를 건너려면 두 번에 나눈다 — 먼저 기본값 있는 필드로 내보내고, 모든 프로세스가 올라간 뒤 기본값을 없앤다. 모델 필드가 가리키는 모델을 바꾸는 것은 필드 이름도 바꾼다.
모델 필드의 검사는 상태 봉투의 m(필드마다 가리키는 모델)으로 한다. 이 검사가 들어오기 전의 서버가 낸 상태에는
m이 없어 검사하지 않는다 — 이 버전으로 올리는 배포와 같은 배포에서 모델 필드의 모델을 바꾸지 않는다.
근거는 tests/test_deploy_field_changes.py(바꾼 것마다의 결과)와 tests/test_reconnect_state_e2e.py(다른 필드로
재시작한 프로세스)다.
용량은 join/s로 잰다#
평상시 처리량(이벤트/s)이 넉넉해도 배포 순간에는 join이 몰린다. 필요한 join 속도는 대략
내리는 인스턴스의 연결 수 × 페이지당 루트 컴포넌트 수 ÷ 재연결이 퍼지는 시간(초)
이고, 이것을 남은 인스턴스들의 join/s 합이 받아야 한다. 재연결이 퍼지는 시간은 클라이언트 백오프의
첫 대기 구간, 곧 RECONNECT_MIN_DELAY_MS부터 RECONNECT_MIN_DELAY_MS + RECONNECT_JITTER_MS까지다(기본 1~5초,
폭 4초).
프로세스 하나의 join/s 실측(make bench, 연결 2,000개, 항목 5개 컴포넌트,
transport-abstraction.md §5-1~5-3):
| 구성 | join/s |
|---|---|
| daphne 1개, InMemory, macOS | 1,086~1,123 |
| daphne 4개, channels-nats, macOS | 1,979~2,245 (프로세스 합) |
| uvicorn 1개, InMemory, Windows ARM64 | 677 |
| daphne 1개, InMemory, Windows x64 에뮬 | 341 |
컴포넌트가 무거우면 더 낮다(항목 50개에서 daphne 1개 691). 이슈 #124의 외부 실측은 daphne 437~613 joins/s였다.
자기 컴포넌트로 make bench를 돌려 잰 값을 쓴다.
예: 인스턴스 넷, 각 5,000연결, 페이지당 루트 컴포넌트 둘, 프로세스당 600 join/s. 하나를 내리면 10,000 join이
생긴다. 기본 폭 4초면 초당 2,500이 남은 셋(합 1,800/s)에 떨어져 넘친다. 넘치면 join이 밀리고 사용자는
끊김 표시(.wireview-disconnected)를 그만큼 오래 본다 — 오류는 아니지만, 밀린 사이 다음 배포 단계가 오면
쌓인다. RECONNECT_JITTER_MS를 10,000으로 늘리면 초당 1,000으로 떨어져 들어간다.
WIREVIEW = {
# 첫 재시도: 1~11초 사이에서 페이지마다 한 번 뽑는다
"RECONNECT_MIN_DELAY_MS": 1000,
"RECONNECT_JITTER_MS": 10000,
# 이후 재시도는 1.5배씩, 30초까지
"RECONNECT_GROW_FACTOR": 1.5,
"RECONNECT_MAX_DELAY_MS": 30000,
}
키의 뜻은 설정에 있다. 폭을 늘리면 평소의 끊김(네트워크가 잠깐 끊긴 노트북)도 그만큼 늦게 복구된다는 것이 대가다. 새 값은 새로 그려진 페이지부터 적용된다 — 이미 열린 페이지는 자기가 로드될 때의 값으로 재연결한다.
사용자가 돌아오면 대기를 끝까지 기다리지 않는다(#228). 탭이 다시 보이거나(visibilitychange) 네트워크가
돌아오거나(online) 페이지가 뒤로·앞으로 캐시에서 되살아나면(pageshow의 persisted) 백오프를 기다리던 페이지는 바로 연결한다. 그래서 대기를 크게 잡아도(RECONNECT_MAX_DELAY_MS
60초 등) 배포 중에 숨겨 둔 탭으로 돌아온 사용자는 그 대기를 보지 않는다. 바뀌지 않는 것:
- 보는 사람이 없는 페이지는 지금처럼 대기를 다 채운다. 배포의 재연결 무리를 흩는 것은 여전히 위의 설정이다 —
사용자가 같은 순간에 돌아오지는 않는다. 숨은 탭은
online에도 아무것도 하지 않는다. - 열려 보이는 소켓은 돌아온 순간 한 번 확인한다. 1초 넘게 조용했던 소켓에
sync를 보내고(vsn 8 이상 서버, wire-protocol) 4초 안에 아무것도 오지 않으면 새 소켓을 연다 — 휴대폰에서 얼었다 되살아난 탭은 연결이 죽었는데도 소켓이 OPEN이라, 전에는 첫 클릭이 답을 받지 못했다. 주기적인 ping은 없다. 숨은 탭 전부가 트래픽을 만들기 때문이다. - 확인은 대화가 쉬고 있을 때만 한다. 마지막으로 서버에서 받은 뒤 페이지가 보낸 것이 있으면 묻지 않는다.
연결의 메시지는 순서대로 처리되므로, 핸들러가 외부 API를 몇 초 기다리는 동안에는
sync도 답을 받지 못한다 — 그때 물으면 살아 있는 소켓을 닫고 그 핸들러의 render를 버리게 된다. 한계: 죽은 소켓에 이벤트를 보낸 채로 얼었던 탭은 돌아와도 감지되지 않는다. 이 변경 전과 같다 — 그 소켓은 브라우저나 서버가 닫을 때까지 남는다. "보낸 것이 있는가"는 답을 하나하나 짝짓는 장부가 아니라 신호 하나라 두 쪽으로 어긋난다: 답이 없는 메시지(leave등)를 마지막으로 보낸 소켓은 다음에 무엇이든 받을 때까지 확인하지 않고, 보낸 뒤 그와 무관한 프레임(브로드캐스트 등)을 받은 소켓은 느린 핸들러가 아직 돌고 있어도 확인한다 — 그 핸들러가 4초를 넘기면 살아 있는 소켓을 새로 연다. - 탭이 보이는 것과
online이 함께 와도 연결은 한 번이고, 방금 연 소켓은 다시 확인하지 않는다. - 서버가 상한으로 닫은 연결(1008·1009)도 끊긴 소켓이라, 사용자가 돌아오면 그 대기도 건너뛴다. 건너뛰는 것은 지금의 대기 하나다 — 재시도 횟수는 그대로라, 다시 곧 닫히면 다음 대기는 전처럼 늘어난다. 그래서 스스로 같은 것을 다시 보내는 페이지가 더 붙는 것은 사람의 동작(탭을 숨겼다 보이기) 하나에 연결 하나뿐이다.
운영자가 할 일은 없다. 근거는 tests/test_offline_e2e.py와 tests/test_reconnect_state_e2e.py의
"돌아온" 테스트들, 판단 규칙은 wireview/static/wireview/reconnect.mjs(tests/js/reconnect.test.mjs)다.
첫 대기의 끝(RECONNECT_MIN_DELAY_MS + RECONNECT_JITTER_MS)은 RECONNECT_MAX_DELAY_MS 이하로 둔다. 어떤 대기도
상한을 넘지 못하므로, 넘는 쪽을 뽑은 페이지는 상한에서 다시 한꺼번에 붙는다. 지터만 늘리고 상한을 그대로 두면
그렇게 된다. 이 조합과 클라이언트가 쓸 수 없는 값(음수, 숫자가 아닌 값), 0으로 도는 대기는 manage.py check가
wireview.W016으로 알린다. 환경 변수에서 읽는다면 int()로 바꿔 넣는다 — 문자열도 경고 대상이다.
SIGTERM 드레인 절차#
wireview가 소켓을 조금씩 닫아 주지는 않는다. ASGI 서버가 종료 신호에 소켓을 한꺼번에 닫고, 흩는 것은 위의 클라이언트 백오프다. 한 인스턴스를 내리는 순서:
-
새 연결을 먼저 끊는다. 로드밸런서에서 인스턴스를 빼고(ALB 대상 등록 해제, Kubernetes는 파드가 종료 중이 되면 엔드포인트에서 빠진다) 그것이 퍼질 시간을 준다 — Kubernetes면
preStop에sleep 10. 이미 열린 WebSocket은 이 단계에서 끊기지 않는다. -
SIGTERM. uvicorn은 새 연결을 받지 않고, 열린 모든 WebSocket을 닫힘 코드 1012(service restart)로 닫은 뒤, 앱 태스크가 끝나기를
--timeout-graceful-shutdown초까지 기다리고 남은 것을 취소한다. 소켓이 닫히면 wireview가 연결마다 컴포넌트의leaving()을 부르고 구독을 정리한다(connection_closed의code가 1012).leaving()에서 presence를 지우거나 DB에 쓰는 앱이면 이 시간이 그만큼 필요하다. 한 연결의leaving()들은 모두 합쳐 5초(wireview.session.LEAVING_SECONDS) 안에 끝나야 한다 — 넘으면 돌던 것을 취소하고 남은 것은 부르지 않는다(경고 로그). 그래도 구독·작업 정리와,presence_leave()를 하지 못한 프로듀서의 presence 퇴장은 한다.uvicorn myproject.asgi:application --workers 4 --timeout-graceful-shutdown 20 ...Kubernetes의
terminationGracePeriodSeconds는preStop대기와 이 값의 합보다 길게 둔다. -
다음 인스턴스로 넘어가기 전에 가라앉는 것을 본다. 남은 인스턴스의
connection_opened속도가 평소로 돌아오고wireview_connections합이 배포 전 수준이 될 때까지 기다린다. 쿨다운 없이 연달아 내리면 방금 재연결한 페이지들이 또 끊긴다.maxSurge로 새 인스턴스를 먼저 띄우면 남은 용량이 줄지 않는다.
앱이 disconnect 없이 끝나도 연결은 한 번 정리된다(#211). 서버가 앱을 취소하거나 앱이 예외로 끝나면
Channels는 disconnect()를 부르지 않는다. wireview는 앱의 끝(ASGI __call__의 finally)에서도 세션을 끝낸다 —
disconnect가 먼저 왔으면 그 정리를 기다릴 뿐 두 번 하지 않는다. 그 정리는 자기 태스크에서 돌아 서버의 취소가
중간에 끊지 않고, leaving()은 위의 5초 안에서 돈다. connection_closed의 code는 None이다. 서버의 취소를
삼키지는 않는다 — 앱 태스크는 취소된 채 끝나고, 정리는 이벤트 루프가 살아 있는 동안 이어진다. 그런 끝은 셋이다.
- daphne의 close timeout. 클라이언트가 끊겼는데 핸들러가 오래 걸려
disconnect처리를 막으면, daphne는--application-close-timeout(기본 10초) 뒤 앱을 취소한다. 그 핸들러는 취소되고, 프로세스는 계속 산다 — 그래서 정리가 끝까지 돈다. 전에는 PatchHub의 항목·채널 그룹·start_async작업·presence가 연결마다 쌓이고 다른 탭의 목록에 떠난 사용자가 남았다. - daphne의 종료. daphne는 종료할 때 WebSocket에
disconnect를 보내지 않고 모든 앱을 취소한 뒤gather로 기다린다(daphne/server.py의kill_all_applications). 그gather는 가장 먼저 끝난 앱 하나에서 끝나고 프로세스가 내려간다. 그래서leaving()은 연결마다 시작되지만, 연결이 둘 이상이면 먼저 끝난 것 말고는 끝까지 돈다는 보장이 없다 — 1.5초짜리leaving()도 끊긴다. - uvicorn의
--timeout-graceful-shutdown초과. 남은 앱 태스크를 취소하고 기다리지 않고 프로세스를 내린다. 정리는 시작되지만 끝까지 돈다는 보장은 없다.
어느 서버도 종료할 때 정리가 끝나는 것을 보장하지 않는다. uvicorn은 graceful 시한 안에서만, daphne는 먼저 끝난
연결 하나까지만 기다리고, 오케스트레이터의 SIGKILL(terminationGracePeriodSeconds)은 어느 쪽이든 끊는다. 그래서:
- presence 퇴장과
leaving()의 마지막 쓰기에 정합성을 걸지 않는다. 퇴장이 오지 않은 탭은 다른 사람의 목록에 남을 수 있다 — 재연결한 탭의 입장이 그 항목을 덮고, 오지 않은 탭의 항목은 그 목록을 그린 페이지를 새로고침하면 사라진다(재연결과 서버 종료). 잃으면 안 되는 상태는 이벤트 핸들러에서 그때그때 쓰고,leaving()은 그것을 정돈하는 데만 쓴다. - 정리를 최대한 돌리려면 위의 드레인 순서를 uvicorn으로 지킨다. 로드밸런서에서 먼저 빼고, SIGTERM이 소켓을
1012로 닫아
disconnect로 정리가 돌게 하고,--timeout-graceful-shutdown을leaving()시한(5초)보다 넉넉히,terminationGracePeriodSeconds를 그보다 길게 둔다. daphne의 종료는 소켓을 닫지 않으므로 이 순서를 탈 수 없다.
Windows에서 SIGTERM에 해당하는 것은 Ctrl+C·Ctrl+Break(서비스 관리자의 정지)다. 이것이 정상 종료이고, 위의
uvicorn·daphne 동작이 그대로 적용된다. 강제 종료(TerminateProcess, 작업 관리자의 "작업 끝내기")는 leaving()을 돌리지 않는다.
실제 서버로 무엇이 끝나고 무엇이 끝나지 않는지는 tests/test_server_shutdown.py가 연결 둘(짧은 훅·긴 훅)로 본다
(Windows에서는 Ctrl+Break로).
배포가 서명 키를 바꾸면 재연결한 모든 페이지가 invalid로 거절돼 전체 새로고침을 한다 — join이 아니라
HTTP 페이지 렌더가 몰린다. 키를 바꿀 때는 옛 키를 SIGNING_KEY_FALLBACKS(또는 SECRET_KEY_FALLBACKS)에 두고
배포한다(업그레이드). 배포 중 wireview_join_rejected_total{reason="invalid"}가
오르면 이것이다.
청크 업로드와 다중 프로세스#
청크는 WebSocket이 아니라 HTTP로 오므로 로드밸런서가 아무 워커에나 보낸다. #83 이후로는 그래도 된다. 엔드포인트가 업로드 상태를 하나도 들고 있지 않고 서명된 토큰만으로 판단해, 토큰에서 계산한 경로에 쓰기 때문이다. 스티키 라우팅도, 업로드 전용 워커도 필요 없다.
모든 워커에서 같아야 하는 값이 둘이다.
| 값 | 왜 |
|---|---|
WIREVIEW["UPLOAD_TEMP_DIR"] |
청크 저장소. 청크를 받는 워커와 완성된 파일을 읽는 워커가 같은 디렉터리를 봐야 한다. 미설정이면 시스템 temp인데, 한 호스트 안에서는 그것이 이미 공유다 |
WIREVIEW["SIGNING_KEY"] (또는 SECRET_KEY) |
토큰이 청크의 유일한 권한 증거다. 키가 다른 워커는 403을 준다 |
| 배포 | 되나 |
|---|---|
| 한 호스트에 워커 N개 (포트마다 uvicorn + Caddy — 위 Windows 구성 그대로) | 된다. 추가 인프라 0 |
| 여러 호스트 | UPLOAD_TEMP_DIR을 공유 볼륨(NFS/EFS)으로 두거나, external 업로드(external=, presigned S3/GCS — docs/features/external-uploads.md)를 쓴다. external은 워커를 아예 지나지 않는다 |
| 공유 볼륨 없는 여러 호스트 | 아직 안 된다. 오브젝트 스토리지 백엔드가 필요한데, Django Storage API에 append가 없어 청크가 다른 쓰기 모델이 된다 |
업로드 중에 워커가 죽으면 그 청크 파일이 남고, 무상태 엔드포인트는 이미 떠난 컴포넌트의 청크를
토큰이 만료될 때까지 받아 준다. 둘 다 UPLOAD_TOKEN_MAX_AGE로 묶이므로 정리 기준은 나이 하나다.
쓰기 경로가 워커당 10분에 한 번 기회적으로 청소하고, cron으로 돌리고 싶으면 다음이 있다.
python manage.py wireview_upload_gc
상세는 docs/features/chunked-uploads.md.
수직 확장#
- 워커 수를 늘린다:
--workers N(N = CPU 코어 수). 비동기 워커 하나가 연결 수천 개를 들고 있으므로 WSGI의코어 × 2 + 1공식은 맞지 않는다. 1개에서 4개로 늘렸을 때의 실측은 Windows 단일 서버에 있다 - uvloop을 쓴다
- 데이터베이스 커넥션을 재사용한다
속도 제한#
# middleware.py
from django.core.cache import cache
class WebSocketRateLimitMiddleware:
def __init__(self, inner):
self.inner = inner
async def __call__(self, scope, receive, send):
if scope["type"] == "websocket":
ip = scope["client"][0]
key = f"ws_rate_{ip}"
# add()는 키가 없을 때만 만들므로 창은 첫 연결에서 60초로 고정되고 연결마다 늘어나지 않는다
await cache.aadd(key, 0, 60)
try:
count = await cache.aincr(key)
except ValueError: # add와 incr 사이에 창이 끝났다
await cache.aset(key, 1, 60)
count = 1
if count > 100: # 분당 연결 100개. 101번째부터 거절한다
await send({"type": "websocket.close", "code": 4029})
return
return await self.inner(scope, receive, send)
incr이 원자적인 캐시(Redis, Memcached)여야 동시 연결이 같은 값을 읽고 한도를 넘기지 않는다. 프로세스가 여럿이면
LocMemCache는 프로세스마다 따로 센다.
이것은 연결 수만 센다. 열린 연결 안에서 오는 메시지는 아래 메시지 크기와 빈도가 막는다.
메시지 크기와 빈도#
.throttle·.debounce는 브라우저에서만 돈다. 소켓에 직접 프레임을 쓰는 클라이언트는 그것을 거치지 않으므로, 연결
하나가 서버에 쓰게 할 수 있는 것에 wireview가 상한을 둔다(#230). 넘으면 그 메시지를 처리하지 않고 소켓을 닫는다.
클라이언트는 닫힘 코드를 가리지 않고 끊김 하나로 다룬다(wireview/static/wireview/wireview.js의 close 리스너): 컴포넌트에
wireview-disconnected를 붙이고 로딩 표시를 풀고 기다리던 훅 pushEvent 응답을 "disconnected"로 거절한 뒤, 재연결 백오프
(RECONNECT_*, 연결이 5초를 못 버티면 대기가 계속 는다. 사용자가 탭으로 돌아오면 지금의 대기만 건너뛴다 —
롤링 배포와 재연결)만큼 기다려 다시 붙고 모든 컴포넌트를 요소의 data-state로 다시 join한다.
거절된 메시지와 끊긴 동안 보낸 메시지는 다시 보내지 않는다(_send가 버린다) — 그래서 다시 끊기는 것은 페이지가 스스로 같은
것을 다시 보낼 때뿐이다: wire-auto-recover 폼은 재연결 뒤 그 값을 다시 보내고(recoverForms), 훅의 mounted()·reconnected()가
보내는 것도 다시 나간다.
| 상한 | 설정 | 기본 | 넘으면 |
|---|---|---|---|
| 메시지 하나의 크기 | INBOUND_MAX_BYTES |
1 MiB | 1009 (message too big). JSON 파싱 전에 UTF-8 바이트로 잰다 |
| 연결의 메시지 빈도 | INBOUND_RATE_PER_SECOND, INBOUND_BURST |
끔 (켜면 버킷 200) | 1008 (policy violation) |
| 연결이 드는 컴포넌트 수 | CONNECTION_MAX_COMPONENTS |
끔 | 1008 |
| 바이너리 프레임 | — | 언제나 | 1003 (unsupported data) |
# settings.py
WIREVIEW = {
# 훅이 pushEvent로 큰 데이터를 보내거나 큰 textarea 폼이 있으면 올린다
"INBOUND_MAX_BYTES": 1024 * 1024,
# 연결 하나가 초당 20개, 한꺼번에 200개까지. 모든 메시지를 센다(join 포함)
"INBOUND_RATE_PER_SECOND": 20,
"INBOUND_BURST": 200,
# 가장 큰 페이지의 컴포넌트 수의 두 배쯤
"CONNECTION_MAX_COMPONENTS": 2000,
}
- 메모리를 지키는 것은 ASGI 서버의 상한이다. wireview의 검사는 서버가 프레임을 다 읽어 앱에 넘긴 뒤에 돈다 —
그 뒤의 파싱·검증·핸들러가 쓰는 것을 막는다. 프레임을 읽는 동안의 메모리는 서버가 정한다: uvicorn
--ws-max-size(기본 16 MiB, 넘으면 1009), daphne--websocket-max-message-size·--websocket-max-frame-size(4.2.3에서 기본 1 MiB,runserver는DAPHNE_WEBSOCKET_MAX_MESSAGE_SIZE). Caddy·nginx의 프록시는 메시지 크기를 보지 않는다. 두 상한이 함께 있으면 작은 쪽이 먼저 끊는다 — 서버가 먼저 끊으면 wireview의 로그·텔레메트리가 남지 않는다. 그래서 uvicorn은INBOUND_MAX_BYTES보다 조금 크게(--ws-max-size 2097152),INBOUND_MAX_BYTES를 올리면 daphne의 두 값도 함께 올린다. - 빈도 제한은 1.x에서 기본으로 꺼져 있다. 정상 페이지도 몰려 보낸다 — 페이지 로드와 boost 이동은 컴포넌트마다 join을
한꺼번에, 스로틀 없는 훅은 이벤트마다 하나를. 켤 때는
INBOUND_BURST를 가장 큰 페이지의 컴포넌트 수보다 넉넉하게 둔다. 재연결한 연결은 새 버킷으로 시작하므로 이것은 한 연결의 몰림을 끊을 뿐이다 — 다시 연결하는 빈도는 위의 연결 미들웨어가 막는다. - 컴포넌트 수. 서명된 상태가 있어야 join되지만, id 없이 그린 컴포넌트는 페이지를 불러올 때마다 새 id(
rx-…)로 서명된다. 그래서 클라이언트가 페이지를 여러 번 불러 모은 상태로 한 연결의 인스턴스를 얼마든지 늘릴 수 있다.CONNECTION_MAX_COMPONENTS가 그것을 막는다. 상한은 봉투(서명·만료·신분·경계·모델 필드가 가리키던 모델)를 확인한 뒤, 인스턴스를 만들기 전에 본다 — 봉투가 거절한 join은 인스턴스를 더하지 않으므로 상한에서도reload로 답한다. 배포한 클래스가 필드를 받아 주지 않는 상태(stale, 필드를 바꾸는 배포)는 만들어 봐야 알 수 있으므로, 상한에 닿은 연결에서는 1008로 먼저 닫히고 페이지의 다음 연결이reload를 받는다. - 컴포넌트마다의 세밀한 제한은
handle_event훅이다. 이 설정들은 연결을 끊는 거친 상한이고, 특정 핸들러(쓰기, 외부 API, 비싼 질의)만 초당 몇 번으로 묶고 넘치는 이벤트는 조용히 버리려면 라이프사이클 훅의 토큰 버킷을 쓴다. - 닫을 때 WARNING 로그(크기와 상한만, 메시지 내용은 싣지 않는다)와 텔레메트리
message_refused(reason:size·rate·binary·components)를 남긴다(telemetry).connection_closed의code에도 닫힘 코드가 실린다.
문제 해결#
WebSocket 연결이 끊긴다
- 프록시 타임아웃 설정을 본다
- 브로커 연결이 안정적인지 확인한다
- 서버 자원 한도를 확인한다
메모리를 많이 쓴다
- 컴포넌트 인스턴스 수를 관찰한다
- 이벤트 핸들러의 누수를 찾는다
- 스트림 사용 패턴을 다시 본다
렌더가 느리다
DEBUG_SYNC_TRANSITIONS를 잠시 켠다- Django Debug Toolbar로 프로파일링한다
- N+1 질의를 찾는다
최적화는 성능 가이드에 있다.