DefStream-Redis 0.1.4__tar.gz → 0.1.5__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Potentially problematic release.
This version of DefStream-Redis might be problematic. Click here for more details.
- {defstream_redis-0.1.4 → defstream_redis-0.1.5/DefStream_Redis.egg-info}/PKG-INFO +13 -2
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/DefStream_Redis.egg-info/SOURCES.txt +4 -0
- defstream_redis-0.1.5/DefStream_Redis.egg-info/requires.txt +2 -0
- {defstream_redis-0.1.4/DefStream_Redis.egg-info → defstream_redis-0.1.5}/PKG-INFO +13 -2
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/README.en.md +12 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/README.md +11 -0
- defstream_redis-0.1.5/issues/feature/5/IMPLEMENTS.md +81 -0
- defstream_redis-0.1.5/issues/feature/5/README.md +38 -0
- defstream_redis-0.1.5/issues/feature/5/REQUIREMENTS.md +123 -0
- defstream_redis-0.1.5/sample/Sample.Stream.py +87 -0
- defstream_redis-0.1.5/sample/Sample.py +76 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/setup.py +1 -1
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/src/Connection.py +102 -11
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/src/Consumer.py +173 -18
- defstream_redis-0.1.5/src/Event.py +191 -0
- defstream_redis-0.1.5/src/Queue.py +284 -0
- defstream_redis-0.1.5/test/test_logging.py +336 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/test/test_redis_integration.py +1 -1
- defstream_redis-0.1.4/DefStream_Redis.egg-info/requires.txt +0 -2
- defstream_redis-0.1.4/sample/Sample.Stream.py +0 -50
- defstream_redis-0.1.4/sample/Sample.py +0 -38
- defstream_redis-0.1.4/src/Event.py +0 -83
- defstream_redis-0.1.4/src/Queue.py +0 -151
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/.github/workflows/ci.yml +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/.gitignore +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/DefStream_Redis.egg-info/dependency_links.txt +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/DefStream_Redis.egg-info/top_level.txt +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/LICENSE +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/issues/fix/1/IMPLEMENTS.md +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/issues/fix/1/README.md +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/issues/fix/1/REQUIREMENTS.md +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/issues/fix/3/IMPLEMENTS.md +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/issues/fix/3/README.md +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/issues/fix/3/REQUIREMENTS.md +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/setup.cfg +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/src/Configuration.py +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/src/Serializer.py +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/src/Subscription.py +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/src/__init__.py +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/test/test_redis.py +0 -0
- {defstream_redis-0.1.4 → defstream_redis-0.1.5}/test/test_release_workflow.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: DefStream-Redis
|
|
3
|
-
Version: 0.1.
|
|
3
|
+
Version: 0.1.5
|
|
4
4
|
Summary: Redis Streams broker adapter for DefStream
|
|
5
5
|
Home-page: https://github.com/yong5eon/DefStream-Redis
|
|
6
6
|
Author: Heo Yongseon
|
|
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
|
|
|
16
16
|
Requires-Python: >=3.9
|
|
17
17
|
Description-Content-Type: text/markdown
|
|
18
18
|
License-File: LICENSE
|
|
19
|
-
Requires-Dist: DefStream>=0.1.
|
|
19
|
+
Requires-Dist: DefStream>=0.1.9
|
|
20
20
|
Requires-Dist: redis>=5.1.1
|
|
21
21
|
Dynamic: author
|
|
22
22
|
Dynamic: classifier
|
|
@@ -116,6 +116,17 @@ finally:
|
|
|
116
116
|
Cluster는 Redis Cluster를 사용하며 `database=0`이어야 합니다.
|
|
117
117
|
운영 인증 정보는 환경변수·비밀 저장소에서 읽으세요.
|
|
118
118
|
|
|
119
|
+
## 로깅
|
|
120
|
+
|
|
121
|
+
`Connection`, `Consumer`, `Queue`, `Event`는 각각
|
|
122
|
+
`DefStream.Broker.Implements.Redis.<클래스명>` 로거를 사용하며 상위
|
|
123
|
+
`DefStream` 로거와 루트 로거로 전파합니다. 라이브러리는 핸들러나 로그 수준을
|
|
124
|
+
설정하지 않으므로 애플리케이션에서 필요한 출력 대상과 필터를 구성하세요.
|
|
125
|
+
기록에는 메시지 본문과 인증 정보가 포함되지 않으며, 오류 로그 후에도 기존
|
|
126
|
+
예외는 호출자에게 전파됩니다. 호출자가 같은 실패를 다시 기록할 수 있으므로
|
|
127
|
+
traceback은 담당 경계 한 곳에서만 남기세요. 예제는 실행 진입점에서만 `Sample`
|
|
128
|
+
및 Redis 로거 계층을 DEBUG로 출력하도록 설정합니다.
|
|
129
|
+
|
|
119
130
|
## 소비자 그룹과 이력
|
|
120
131
|
|
|
121
132
|
- `connection.queue(name, group='DefStream')`과 `connection.stream(name, group='DefStream')`은
|
|
@@ -9,6 +9,9 @@ DefStream_Redis.egg-info/SOURCES.txt
|
|
|
9
9
|
DefStream_Redis.egg-info/dependency_links.txt
|
|
10
10
|
DefStream_Redis.egg-info/requires.txt
|
|
11
11
|
DefStream_Redis.egg-info/top_level.txt
|
|
12
|
+
issues/feature/5/IMPLEMENTS.md
|
|
13
|
+
issues/feature/5/README.md
|
|
14
|
+
issues/feature/5/REQUIREMENTS.md
|
|
12
15
|
issues/fix/1/IMPLEMENTS.md
|
|
13
16
|
issues/fix/1/README.md
|
|
14
17
|
issues/fix/1/REQUIREMENTS.md
|
|
@@ -25,6 +28,7 @@ src/Queue.py
|
|
|
25
28
|
src/Serializer.py
|
|
26
29
|
src/Subscription.py
|
|
27
30
|
src/__init__.py
|
|
31
|
+
test/test_logging.py
|
|
28
32
|
test/test_redis.py
|
|
29
33
|
test/test_redis_integration.py
|
|
30
34
|
test/test_release_workflow.py
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: DefStream-Redis
|
|
3
|
-
Version: 0.1.
|
|
3
|
+
Version: 0.1.5
|
|
4
4
|
Summary: Redis Streams broker adapter for DefStream
|
|
5
5
|
Home-page: https://github.com/yong5eon/DefStream-Redis
|
|
6
6
|
Author: Heo Yongseon
|
|
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.14
|
|
|
16
16
|
Requires-Python: >=3.9
|
|
17
17
|
Description-Content-Type: text/markdown
|
|
18
18
|
License-File: LICENSE
|
|
19
|
-
Requires-Dist: DefStream>=0.1.
|
|
19
|
+
Requires-Dist: DefStream>=0.1.9
|
|
20
20
|
Requires-Dist: redis>=5.1.1
|
|
21
21
|
Dynamic: author
|
|
22
22
|
Dynamic: classifier
|
|
@@ -116,6 +116,17 @@ finally:
|
|
|
116
116
|
Cluster는 Redis Cluster를 사용하며 `database=0`이어야 합니다.
|
|
117
117
|
운영 인증 정보는 환경변수·비밀 저장소에서 읽으세요.
|
|
118
118
|
|
|
119
|
+
## 로깅
|
|
120
|
+
|
|
121
|
+
`Connection`, `Consumer`, `Queue`, `Event`는 각각
|
|
122
|
+
`DefStream.Broker.Implements.Redis.<클래스명>` 로거를 사용하며 상위
|
|
123
|
+
`DefStream` 로거와 루트 로거로 전파합니다. 라이브러리는 핸들러나 로그 수준을
|
|
124
|
+
설정하지 않으므로 애플리케이션에서 필요한 출력 대상과 필터를 구성하세요.
|
|
125
|
+
기록에는 메시지 본문과 인증 정보가 포함되지 않으며, 오류 로그 후에도 기존
|
|
126
|
+
예외는 호출자에게 전파됩니다. 호출자가 같은 실패를 다시 기록할 수 있으므로
|
|
127
|
+
traceback은 담당 경계 한 곳에서만 남기세요. 예제는 실행 진입점에서만 `Sample`
|
|
128
|
+
및 Redis 로거 계층을 DEBUG로 출력하도록 설정합니다.
|
|
129
|
+
|
|
119
130
|
## 소비자 그룹과 이력
|
|
120
131
|
|
|
121
132
|
- `connection.queue(name, group='DefStream')`과 `connection.stream(name, group='DefStream')`은
|
|
@@ -76,6 +76,18 @@ The default Pool mode uses redis-py's connection pool.
|
|
|
76
76
|
Cluster mode uses Redis Cluster and requires `database=0`.
|
|
77
77
|
Read production credentials from environment variables or a secret store.
|
|
78
78
|
|
|
79
|
+
## Logging
|
|
80
|
+
|
|
81
|
+
`Connection`, `Consumer`, `Queue`, and `Event` each use a class-level logger named
|
|
82
|
+
`DefStream.Broker.Implements.Redis.<ClassName>`. Records propagate to the parent
|
|
83
|
+
`DefStream` logger and the root logger. The library does not configure handlers
|
|
84
|
+
or logging levels; configure output destinations and filters in your application.
|
|
85
|
+
Records exclude message bodies and credentials, and existing exceptions still
|
|
86
|
+
propagate to callers after an error is logged. Since callers may log the same
|
|
87
|
+
failure again, keep traceback logging at the boundary responsible for that failure.
|
|
88
|
+
The examples configure output only at their execution entry points, selecting
|
|
89
|
+
the `Sample` and Redis logger hierarchies at DEBUG level.
|
|
90
|
+
|
|
79
91
|
## Consumer groups and history
|
|
80
92
|
|
|
81
93
|
- `connection.queue(name, group='DefStream')` and `connection.stream(name, group='DefStream')`
|
|
@@ -85,6 +85,17 @@ finally:
|
|
|
85
85
|
Cluster는 Redis Cluster를 사용하며 `database=0`이어야 합니다.
|
|
86
86
|
운영 인증 정보는 환경변수·비밀 저장소에서 읽으세요.
|
|
87
87
|
|
|
88
|
+
## 로깅
|
|
89
|
+
|
|
90
|
+
`Connection`, `Consumer`, `Queue`, `Event`는 각각
|
|
91
|
+
`DefStream.Broker.Implements.Redis.<클래스명>` 로거를 사용하며 상위
|
|
92
|
+
`DefStream` 로거와 루트 로거로 전파합니다. 라이브러리는 핸들러나 로그 수준을
|
|
93
|
+
설정하지 않으므로 애플리케이션에서 필요한 출력 대상과 필터를 구성하세요.
|
|
94
|
+
기록에는 메시지 본문과 인증 정보가 포함되지 않으며, 오류 로그 후에도 기존
|
|
95
|
+
예외는 호출자에게 전파됩니다. 호출자가 같은 실패를 다시 기록할 수 있으므로
|
|
96
|
+
traceback은 담당 경계 한 곳에서만 남기세요. 예제는 실행 진입점에서만 `Sample`
|
|
97
|
+
및 Redis 로거 계층을 DEBUG로 출력하도록 설정합니다.
|
|
98
|
+
|
|
88
99
|
## 소비자 그룹과 이력
|
|
89
100
|
|
|
90
101
|
- `connection.queue(name, group='DefStream')`과 `connection.stream(name, group='DefStream')`은
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
# 로깅 지원 구현 기록
|
|
2
|
+
|
|
3
|
+
## 1. 구현 개요
|
|
4
|
+
|
|
5
|
+
[요구사항](./REQUIREMENTS.md)에 따라 Redis Streams의 연결·발행·읽기·회수·정산
|
|
6
|
+
경계에 클래스별 표준 로깅을 추가했다.
|
|
7
|
+
|
|
8
|
+
- 구현·검증일: 2026-10-20
|
|
9
|
+
- 사용자용 안내: [변경 로그](./README.md)
|
|
10
|
+
- 연계 구현: [코어 로깅](../../../../DefStream/issues/feature/8/IMPLEMENTS.md)
|
|
11
|
+
|
|
12
|
+
## 2. 로거와 기록 범위
|
|
13
|
+
|
|
14
|
+
각 클래스에 `DefStream.Broker.Implements.Redis.<클래스 이름>`의
|
|
15
|
+
클래스 멤버 `logger`를 정의했다.
|
|
16
|
+
|
|
17
|
+
| 클래스 | 구현한 관찰 지점 |
|
|
18
|
+
| --- | --- |
|
|
19
|
+
| [Connection](../../../src/Connection.py) | 단일·Cluster 연결과 ping·재사용·종료, 자원 생성·삭제·객체 생성·emit 위임 |
|
|
20
|
+
| [Consumer](../../../src/Consumer.py) | 구독·루프 생명주기, QoS·pending, 회수·cursor·전달, 콜백 예약·실행 |
|
|
21
|
+
| [Queue](../../../src/Queue.py) | 그룹 생성·재사용, xadd 발행 ID, 그룹 기반 pop·그룹 없는 read, 디코딩 |
|
|
22
|
+
| [Event](../../../src/Event.py) | ack·원자적 재큐잉·reject, 중복 정산 생략과 명령 결과 |
|
|
23
|
+
|
|
24
|
+
`Connection.stream()`은 기존 Queue를 반환하므로 별도 Stream 로거를 만들지 않았다.
|
|
25
|
+
RPC·Exchange·자동 재연결·재시도 API는 추가하지 않았다.
|
|
26
|
+
|
|
27
|
+
## 3. 레벨과 의미 구분
|
|
28
|
+
|
|
29
|
+
- INFO: 연결·Consumer 생명주기, 새 그룹 생성과 자원 삭제 결과.
|
|
30
|
+
- DEBUG: 발행·읽기·회수·정산, 기존 그룹 재사용과 정상 읽기 시간 초과.
|
|
31
|
+
- WARNING: 그룹 없는 history Event에 대한 정산 시도.
|
|
32
|
+
- ERROR: 연결·읽기·회수·디코딩·콜백·정산 등 담당 경계의 내부 실패.
|
|
33
|
+
|
|
34
|
+
`BUSYGROUP`, 정상 QoS 보류·회수·빈 조회를 경고로 취급하지 않는다.
|
|
35
|
+
반복 루프의 매 조회 대신 유의미한 결과·상태를 기록한다.
|
|
36
|
+
Redis 명령 반환값이 0이면 처리 대상 없음으로 구분하고 실제 정산 성공으로 기록하지 않는다.
|
|
37
|
+
이미 settled인 Event는 중복 정산 생략을 기록한다.
|
|
38
|
+
명령 실패 후에는 성공 로그를 남기지 않고 예외를 다시 전파한다.
|
|
39
|
+
|
|
40
|
+
기존 cursor·QoS·회수 순서·콜백 스레드·재큐잉 Lua의 원자성과 settled 갱신 계약을
|
|
41
|
+
유지했다. reject가 ACK로 구현된 기존 의미도 로그에 구분했다.
|
|
42
|
+
|
|
43
|
+
## 4. 출력·보안·샘플
|
|
44
|
+
|
|
45
|
+
- 라이브러리는 핸들러·NullHandler·포매터·필터·레벨을 설정하지 않고 기본 전파를 유지한다.
|
|
46
|
+
- 영어 메시지에 안전한 연결 정보·Stream·그룹·consumer·메시지 ID·회수 결과를 기록한다.
|
|
47
|
+
- 본문·결과·인증정보·전체 설정·예외 문자열·traceback은 로그에서 제외한다.
|
|
48
|
+
- 위임된 디코딩·정산과 Worker가 처리한 작업 실패의 중복 오류 기록을 피한다.
|
|
49
|
+
- [샘플](../../../sample)은 `print()` 대신 `Sample` 로거를 사용하며,
|
|
50
|
+
진입점에서 `Sample`과 `DefStream.Broker.Implements.Redis` 계층만 수신한다.
|
|
51
|
+
필터는 이름 경계를 확인하므로 유사 접두사인 다른 로거를 포함하지 않는다.
|
|
52
|
+
|
|
53
|
+
## 5. 검증
|
|
54
|
+
|
|
55
|
+
Python 3.13.16과 실제 Redis에서 관련 테스트 **25개가 건너뜀 없이 통과**했다.
|
|
56
|
+
[로깅 테스트](../../../test/test_logging.py) 11개는 다음을 검증한다.
|
|
57
|
+
|
|
58
|
+
- 클래스별 이름·전파와 라이브러리 설정 비개입.
|
|
59
|
+
- 단일·Cluster 연결 방식의 모의 검증, 연결 실패 시 인증정보·예외 문자열 제외.
|
|
60
|
+
- 발행 메타데이터와 본문 제외, 새 그룹 생성과 BUSYGROUP의 DEBUG 재사용.
|
|
61
|
+
- 정상 읽기 시간 초과와 오류의 레벨 구분.
|
|
62
|
+
- 회수 메시지 문맥, 정산 반환값 0·실패·그룹 없는 이벤트와 잘못된 성공 로그 방지.
|
|
63
|
+
- 핸들러 실패의 문맥·예외 타입 기록과 traceback·본문 제외.
|
|
64
|
+
- 샘플의 계층 경계 필터.
|
|
65
|
+
|
|
66
|
+
기존 Redis·Worker 실서버 통합 테스트를 함께 실행했고 큐·스트림 샘플도 실행했다.
|
|
67
|
+
영어 전환 후 소스·샘플 `compileall`과 `git diff --check`를 통과했다.
|
|
68
|
+
실제 RedisCluster 다중 노드 장애 검증, 다른 Python 버전 및 전체 정적 타입 검사를
|
|
69
|
+
완료한 것은 아니다.
|
|
70
|
+
|
|
71
|
+
### 재검증
|
|
72
|
+
|
|
73
|
+
개발 가상환경과 로컬 테스트 Redis를 준비한 작업공간 루트에서 실행한다.
|
|
74
|
+
통합 테스트가 자원을 생성·정리하므로 운영 Redis를 사용하지 않는다.
|
|
75
|
+
|
|
76
|
+
```powershell
|
|
77
|
+
$env:PYTHONIOENCODING = 'utf-8'
|
|
78
|
+
$env:DEFSTREAM_REDIS_TESTS = '1'
|
|
79
|
+
Set-Location .\DefStream-Redis\test
|
|
80
|
+
& ..\..\.venv\Scripts\python.exe -m unittest test_logging test_redis test_redis_integration
|
|
81
|
+
```
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
# 로깅 지원
|
|
2
|
+
|
|
3
|
+
## 변경 요약
|
|
4
|
+
|
|
5
|
+
Redis Streams의 연결·그룹·발행·읽기·회수·정산을 클래스별 표준 로거로
|
|
6
|
+
추적할 수 있습니다. 런타임 메시지는 영어이며 출력 정책은 애플리케이션이 정합니다.
|
|
7
|
+
|
|
8
|
+
## 로거 이름
|
|
9
|
+
|
|
10
|
+
공통 접두사는 `DefStream.Broker.Implements.Redis`입니다.
|
|
11
|
+
`Connection`, `Consumer`, `Queue`, `Event`가 각자의 클래스 멤버 `logger`를 사용합니다.
|
|
12
|
+
|
|
13
|
+
`DefStream.Broker.Implements.Redis.Consumer`처럼 클래스 하나만 선택하거나
|
|
14
|
+
Redis·Broker·DefStream 상위 계층에서 함께 수신할 수 있습니다.
|
|
15
|
+
`stream()`도 Queue 로거를 사용하며 별도 Redis.Stream 로거는 없습니다.
|
|
16
|
+
|
|
17
|
+
## 레벨과 주의사항
|
|
18
|
+
|
|
19
|
+
- INFO: 연결·소비 생명주기, 새 그룹 생성과 자원 삭제.
|
|
20
|
+
- DEBUG: 메시지 발행·읽기·회수·정산, 기존 그룹 재사용과 정상 시간 초과.
|
|
21
|
+
- WARNING: 그룹 없는 history Event에 대한 정산 시도.
|
|
22
|
+
- ERROR: 연결·읽기·회수·디코딩·정산 등 내부 실패.
|
|
23
|
+
|
|
24
|
+
BUSYGROUP, 정상 회수·QoS 보류·빈 조회를 장애로 기록하지 않습니다.
|
|
25
|
+
정산 명령 반환값이 0이면 대상 없음으로, 중복 정산은 생략으로 구분합니다.
|
|
26
|
+
본문·결과·인증정보·예외 문자열·traceback은 어댑터 로그에서 제외합니다.
|
|
27
|
+
예외는 기존대로 전파되므로 애플리케이션에서 같은 오류를 재기록하면 중복될 수 있습니다.
|
|
28
|
+
|
|
29
|
+
## 사용자 설정과 샘플
|
|
30
|
+
|
|
31
|
+
라이브러리는 핸들러·NullHandler·레벨을 자동 설정하지 않습니다.
|
|
32
|
+
설정이 없으면 표준 `logging.lastResort` 동작을 유지합니다.
|
|
33
|
+
[샘플](../../../sample)은 `print()` 대신 `Sample` 로거를 사용하며
|
|
34
|
+
`Sample`과 Redis 계층만 출력합니다.
|
|
35
|
+
실제 설정은 [사용 설명서](../../../README.md#로깅)를 참고하세요.
|
|
36
|
+
|
|
37
|
+
기존 읽기·QoS·회수·원자적 재큐잉·정산 계약을 유지합니다.
|
|
38
|
+
이번 변경으로 RPC나 자동 재연결·재시도 기능이 추가되지는 않습니다.
|
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# 로깅 지원
|
|
2
|
+
|
|
3
|
+
## 1. 목적과 범위
|
|
4
|
+
|
|
5
|
+
- Redis Streams의 연결, 그룹 생성, 발행·읽기, Consumer 순환·회수, 메시지 확인 처리를 풍부하게 관찰할 수 있도록 한다.
|
|
6
|
+
- Python 표준 `logging`을 사용하며 출력 대상·형식·레벨·필터는 사용자 애플리케이션이 결정한다.
|
|
7
|
+
- 로깅 대상은 Connection·Consumer·Queue·Event 네 클래스로 한정한다.
|
|
8
|
+
- 이 요구사항에 따라 소스와 샘플의 로깅을 구현하며, 기존 공개 API의 메시지 처리 계약을 유지한다.
|
|
9
|
+
- 코어 Worker·Inspector의 기록 책임은 [DefStream 로깅 지원](../../../../DefStream/issues/feature/8/REQUIREMENTS.md)을 따른다.
|
|
10
|
+
|
|
11
|
+
## 2. 로거 이름과 사용자 설정
|
|
12
|
+
|
|
13
|
+
- 모듈 경로나 사용자 하위 클래스에서 자동 생성하지 않고 클래스별 명시적 이름을 사용한다.
|
|
14
|
+
- 이름의 공통 형식은 `DefStream.Broker.Implements.Redis.ClassName`이다. 프로젝트·패키지 표기에 맞추어 `DefStream`으로 통일한다.
|
|
15
|
+
- DefStream·RabbitMQ와 동일하게 로거를 클래스 멤버로 보관한다. 사용자 하위 클래스는 기반 이름을 상속하며 필요하면 로거 멤버를 명시적으로 재정의할 수 있다.
|
|
16
|
+
- 사용자 애플리케이션은 `DefStream`, `DefStream.Broker`, `DefStream.Broker.Implements.Redis` 또는 클래스별 로거에서 선택적으로 수신할 수 있어야 한다.
|
|
17
|
+
- 라이브러리는 `basicConfig()`, 출력 핸들러·포매터·필터, 로그 레벨을 임의로 설정하거나 기존 설정을 제거하지 않는다. 루트까지의 기본 전파도 막지 않는다.
|
|
18
|
+
- 코어·RabbitMQ와 동일하게 출력 핸들러와 `NullHandler`를 추가하지 않는다. 미설정 시 Python의 `logging.lastResort` 기본 동작을 유지한다.
|
|
19
|
+
- 샘플은 `Sample` 로거를 사용하고 출력 핸들러를 직접 설정한다. 수신 범위는 `Sample`과 `DefStream.Broker.Implements.Redis` 계층이며, 샘플의 `print()`는 DEBUG·INFO 로그로 대체한다.
|
|
20
|
+
|
|
21
|
+
## 3. 현재 상태
|
|
22
|
+
|
|
23
|
+
- 현재 Redis 구현체에는 직접적인 로깅 호출이 없다.
|
|
24
|
+
- [Connection](../../../src/Connection.py)은 Redis 또는 RedisCluster 생성 후 `ping()`으로 연결을 확인한다.
|
|
25
|
+
- [Consumer](../../../src/Consumer.py)는 구독 큐를 순환하고, 선택적으로 `xautoclaim()`을 실행한 뒤 `xreadgroup()`으로 새 메시지를 읽는다.
|
|
26
|
+
- [Queue](../../../src/Queue.py)는 Streams 발행·그룹 생성·그룹 기반 단건 수신과 그룹 없는 읽기를 제공한다. 별도 Stream 클래스는 없다.
|
|
27
|
+
- [Event](../../../src/Event.py)는 그룹 메시지의 확인·재큐잉·거부를 수행하며 Redis 호출 후 `settled` 상태를 갱신한다.
|
|
28
|
+
- 현재 RPC·Exchange 구현은 없다. 해당 기능의 로그나 기능 추가를 이번 범위에 포함하지 않는다.
|
|
29
|
+
|
|
30
|
+
## 4. 클래스별 로거 이름
|
|
31
|
+
|
|
32
|
+
다음 네 클래스만 독립 로거를 갖는다.
|
|
33
|
+
|
|
34
|
+
| 구분 | 클래스와 소스 | 로거 이름 | 필요한 관찰 범위 |
|
|
35
|
+
| --- | --- | --- | --- |
|
|
36
|
+
| 우선 대상 | [Connection](../../../src/Connection.py) | `DefStream.Broker.Implements.Redis.Connection` | 단일 Redis·Cluster 연결·ping·종료, 자원 생성·삭제, 객체 생성 |
|
|
37
|
+
| 우선 대상 | [Consumer](../../../src/Consumer.py) | `DefStream.Broker.Implements.Redis.Consumer` | 구독·수신 루프, 회수·전달, QoS·pending, 콜백 처리·종료 |
|
|
38
|
+
| 우선 대상 | [Queue](../../../src/Queue.py) | `DefStream.Broker.Implements.Redis.Queue` | 그룹 생성, 발행, 단건 수신·그룹 없는 읽기, Event 변환 |
|
|
39
|
+
| 우선 대상 | [Event](../../../src/Event.py) | `DefStream.Broker.Implements.Redis.Event` | ack, 원자적 재큐잉, reject, settled 상태 |
|
|
40
|
+
|
|
41
|
+
### 4.1. 독립 로거를 추가하지 않을 대상
|
|
42
|
+
|
|
43
|
+
| 대상 | 판단 근거와 기록 책임 |
|
|
44
|
+
| --- | --- |
|
|
45
|
+
| [JavaScriptObjectNotationEncoder·JavaScriptObjectNotationDecoder](../../../src/Serializer.py) | 독립 로깅에서 제외한다. 직렬화·역직렬화 실패는 송수신 호출 경계에서 관찰한다. |
|
|
46
|
+
| [Configuration·ConnectionType](../../../src/Configuration.py) | 설정 보관·검증과 열거형이다. Connection에서 허용한 연결 설정만 요약한다. |
|
|
47
|
+
| [Subscription](../../../src/Subscription.py) | 큐·그룹 파싱·검증 데이터 클래스이다. 적용 결과는 Connection·Consumer·Queue에서 기록한다. |
|
|
48
|
+
| [Encoder·Decoder](../../../src/Serializer.py) | 사용자 구현용 Protocol이다. 구체 구현 또는 호출 경계에서 관찰한다. |
|
|
49
|
+
|
|
50
|
+
- `Connection.stream()`은 Queue를 반환하므로 존재하지 않는 `Redis.Stream` 클래스 로거를 추가하지 않는다.
|
|
51
|
+
- 직렬화 클래스에서 독립 로그를 추가하지 않고 송수신 호출 경계에서 실패 단계를 기록하며 기존 예외를 전파한다.
|
|
52
|
+
|
|
53
|
+
## 5. 레벨별 기록 요구사항
|
|
54
|
+
|
|
55
|
+
### 5.1. Connection
|
|
56
|
+
|
|
57
|
+
- INFO: 연결 시도, ping을 마친 연결 성공, 연결 종료. 단일 Redis·Cluster 방식을 구분한다.
|
|
58
|
+
- DEBUG: 기존 연결 재사용, 안전한 주소·포트·DB·TLS 여부·최대 연결 수·제한 시간, Consumer·Queue 생성.
|
|
59
|
+
- INFO: 명시적 자원 삭제 완료와 반환된 삭제 개수. 키가 없을 때도 삭제에 성공한 것처럼 표현하지 않는다.
|
|
60
|
+
- DEBUG: 큐·스트림 선언·그룹 생성의 위임과 `emit()`의 발행 경계. 그룹 생성 결과와 실제 발행 ID는 Queue에서 기록한다.
|
|
61
|
+
- ERROR: 연결·ping·자원 삭제·종료 실패 중 Connection이 기록 책임을 갖는 경계. 실패 시 자원 정리와 예외 전파를 보존한다.
|
|
62
|
+
- connect 성공을 무기한 연결 정상 보장이나 모든 Cluster 노드의 가용성 확인으로 표현하지 않는다.
|
|
63
|
+
|
|
64
|
+
### 5.2. Consumer
|
|
65
|
+
|
|
66
|
+
- INFO: 구독 완료, 수신 루프 시작·중지·종료. 큐·그룹·consumer 이름·QoS·회수 설정을 구분한다.
|
|
67
|
+
- DEBUG: 큐 순환, 새 메시지 수신·전달, 메시지 ID, 콜백 예약·실행, settled 항목 제거, pending 수 변화.
|
|
68
|
+
- DEBUG: `xautoclaim()` 회수 시도·회수 결과와 cursor, 이미 pending인 항목의 중복 전달 생략.
|
|
69
|
+
- DEBUG: QoS 한도에 도달해 읽기를 보류하는 상태. 정상적인 포화를 WARNING으로 출력하지 않는다.
|
|
70
|
+
- 정상적인 미확인 메시지 회수는 DEBUG로 기록한다. 회수 자체를 장애로 취급하거나 회수 명령 호출만으로 WARNING을 출력하지 않는다.
|
|
71
|
+
- ERROR: 읽기·회수·Event 디코딩·콜백 처리·핸들러 전달 실패 중 이 경계가 담당하는 오류.
|
|
72
|
+
- Worker가 처리한 사용자 작업 실패를 Consumer에서 다시 ERROR·traceback으로 기록하지 않는다.
|
|
73
|
+
- 50ms 반복 루프의 빈 조회·매회 큐 순환·대기를 무조건 출력하지 않는다. 값이 있는 결과와 유의미한 상태 변화 중심으로 기록한다.
|
|
74
|
+
- 종료 요청·루프 종료·정리 완료를 구분하며, 단순 Consumer 종료를 pending 메시지의 확인 완료로 표현하지 않는다.
|
|
75
|
+
|
|
76
|
+
### 5.3. Queue
|
|
77
|
+
|
|
78
|
+
- INFO: 새 Consumer Group 생성 성공.
|
|
79
|
+
- DEBUG: `BUSYGROUP`에 따른 기존 그룹 재사용. 정상적인 재사용은 WARNING이나 ERROR가 아니다.
|
|
80
|
+
- DEBUG: `xadd()` 발행 시작·완료, Stream 이름·반환 ID, `pop()`·`read()` 시작·읽기 위치·메시지 수신·종료.
|
|
81
|
+
- DEBUG: 그룹 기반 `pop()`과 그룹 없는 `read()`를 구분하고, 메시지 메타데이터를 Event로 변환하는 단계를 기록한다.
|
|
82
|
+
- DEBUG: 정상적인 읽기 제한 시간 종료. 메시지가 없다는 이유로 WARNING을 출력하지 않는다.
|
|
83
|
+
- ERROR: 그룹 생성의 BUSYGROUP 이외 오류, 발행·읽기·역직렬화 실패 중 이 경계가 기록하는 오류.
|
|
84
|
+
- 빈 읽기와 10ms 대기마다 로그를 남기지 않는다.
|
|
85
|
+
- `Connection.stream()`·`create_stream()` 경로에서도 같은 Queue 로거와 그룹 생성 책임을 유지한다.
|
|
86
|
+
|
|
87
|
+
### 5.4. Event
|
|
88
|
+
|
|
89
|
+
- DEBUG: ack/nack/reject 시도·완료와 큐·그룹·consumer·메시지 ID.
|
|
90
|
+
- DEBUG: 이미 settled인 이벤트의 중복 정산 생략. Redis 명령을 다시 수행한 것처럼 기록하지 않는다.
|
|
91
|
+
- DEBUG: `nack()`의 Lua 실행과 처리 결과. 원자적 재큐잉과 확인의 성공 여부는 실제 반환 결과에 맞춰 표현한다.
|
|
92
|
+
- DEBUG: `reject()`는 현재 ack로 pending에서 제외하는 동작임을 구분한다. Stream 항목 삭제·별도 오류 큐 이동으로 표현하지 않는다.
|
|
93
|
+
- WARNING: 그룹 없는 `read()` 결과에 ack/nack/reject를 시도해 거부되는 사건. 기존 RuntimeError는 보존한다.
|
|
94
|
+
- ERROR: `xack()` 또는 재큐잉 Lua 실행 실패. Redis 호출 실패 후 settled 또는 처리 성공으로 기록하지 않는다.
|
|
95
|
+
- Redis 명령 반환값이 0이면 처리 대상을 실제로 확인·재큐잉한 것처럼 표현하지 않는다. 로그 추가를 이유로 기존 정산 정책을 변경하지 않는다.
|
|
96
|
+
|
|
97
|
+
## 6. 기록 품질과 호환성
|
|
98
|
+
|
|
99
|
+
- 공개 라이브러리와 샘플의 런타임 로그 메시지는 영어로 작성한다. 한국어 문서·주석은 유지하고 클래스·API·식별자는 원문을 유지한다.
|
|
100
|
+
- 비밀번호·사용자 인증정보·연결 URI의 자격 증명·Configuration 전체·메시지 본문·결과·Lua 인자 전체를 기록하지 않는다.
|
|
101
|
+
- 허용 문맥은 사건·단계, 안전한 주소·DB·연결 방식, Stream·그룹·consumer·메시지 ID, QoS·pending 수·회수 설정 등으로 제한한다.
|
|
102
|
+
- 객체 `repr()`와 예외 문자열·traceback의 민감정보 노출 가능성을 검토한다.
|
|
103
|
+
- Connection→Queue 위임, Consumer→Queue 디코딩, Consumer→Event 정산에서 동일 예외의 ERROR·traceback을 중복 출력하지 않는다.
|
|
104
|
+
- DEBUG 비활성 시 추가 Redis 명령·직렬화·pending 전체 순회를 로그 목적으로 수행하지 않고 지연 메시지 치환을 활용한다.
|
|
105
|
+
- 기존 예외 전파, 읽기 cursor, QoS·회수·순환 순서, 콜백 스레드, Lua 원자성, settled 갱신과 그룹 없는 읽기 계약을 보존한다.
|
|
106
|
+
- 자동 재연결·재시도·RPC·새 핸들러 주입 API는 이번 로깅 요구사항에 포함하지 않는다.
|
|
107
|
+
|
|
108
|
+
## 7. 확정 사항과 구현 원칙
|
|
109
|
+
|
|
110
|
+
1. 독립 로깅 대상과 이름은 4장의 네 클래스로 한정하고 로거는 클래스 멤버로 보관한다.
|
|
111
|
+
2. 핸들러 설정은 사용자 책임이며 라이브러리는 출력 핸들러·NullHandler를 추가하지 않는다.
|
|
112
|
+
3. 연결·생명주기·자원 생성·삭제는 INFO, 메시지별 정상 흐름과 회수는 DEBUG, 잘못된 정산 시도는 WARNING, 내부 장애는 ERROR로 구분한다.
|
|
113
|
+
4. 반복 읽기·QoS 보류·회수의 출력량과 상세 문맥은 5·6장의 원칙에 따라 구현 시 구체화한다. 별도 설정 API를 미리 추가하지 않는다.
|
|
114
|
+
5. 사용자 애플리케이션이 상위 경계에서도 같은 예외를 기록할 수 있다는 점을 안내한다. 사용자의 로깅을 억제하거나 예외 전파를 변경하지 않는다.
|
|
115
|
+
|
|
116
|
+
## 8. 구현 후 수용 기준
|
|
117
|
+
|
|
118
|
+
- 확정한 클래스별 로거와 상위 Redis·Broker·DefStream 로거에서 선택 수신 및 루트 전파가 가능하다.
|
|
119
|
+
- 단일 Redis·Cluster 연결, 그룹 생성·재사용, 발행·읽기·회수·정산의 정상·실패 로그를 검증한다.
|
|
120
|
+
- BUSYGROUP, 빈 조회, 정상적인 대기 종료·QoS 보류가 반복 경고로 출력되지 않는다.
|
|
121
|
+
- 그룹 없는 이벤트, 중복 정산, Redis 명령 반환값 0·실패가 성공 로그와 구분된다.
|
|
122
|
+
- 사용자 로깅 설정과 예외 전파를 유지하고, 동일 실패의 중복 traceback 및 민감정보 누출이 없다.
|
|
123
|
+
- 기존 Redis·Worker 연동·통합 테스트가 보장하는 메시지 처리·재큐잉·종료 동작을 유지한다.
|
|
@@ -0,0 +1,87 @@
|
|
|
1
|
+
from logging import (
|
|
2
|
+
DEBUG,
|
|
3
|
+
Filter,
|
|
4
|
+
Formatter,
|
|
5
|
+
StreamHandler,
|
|
6
|
+
getLogger,
|
|
7
|
+
)
|
|
8
|
+
from uuid import uuid4
|
|
9
|
+
|
|
10
|
+
from DefStream.Broker.Implements.Redis import (
|
|
11
|
+
Connection,
|
|
12
|
+
Configuration,
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
logger = getLogger('Sample')
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class SampleLogFilter(Filter):
|
|
19
|
+
def filter(self, record) -> bool:
|
|
20
|
+
return any(
|
|
21
|
+
record.name == prefix or record.name.startswith(prefix + '.')
|
|
22
|
+
for prefix in (
|
|
23
|
+
'Sample',
|
|
24
|
+
'DefStream.Broker.Implements.Redis',
|
|
25
|
+
)
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def main() -> None:
|
|
30
|
+
handler = StreamHandler()
|
|
31
|
+
handler.setLevel(DEBUG)
|
|
32
|
+
handler.setFormatter(Formatter('%(asctime)s %(name)s %(levelname)s %(message)s'))
|
|
33
|
+
handler.addFilter(SampleLogFilter())
|
|
34
|
+
root_logger = getLogger()
|
|
35
|
+
root_logger.setLevel(DEBUG)
|
|
36
|
+
root_logger.addHandler(handler)
|
|
37
|
+
|
|
38
|
+
broker = Connection(Configuration())
|
|
39
|
+
name = 'defstream-stream-sample-' + uuid4().hex
|
|
40
|
+
try:
|
|
41
|
+
broker.connect()
|
|
42
|
+
stream = broker.stream(name)
|
|
43
|
+
ids = []
|
|
44
|
+
for number in range(3):
|
|
45
|
+
ids.append(stream.send({
|
|
46
|
+
'message': 'Hello Redis Stream',
|
|
47
|
+
'number': number,
|
|
48
|
+
}))
|
|
49
|
+
|
|
50
|
+
logger.info(
|
|
51
|
+
'Reading stream from beginning: queue=%s',
|
|
52
|
+
name,
|
|
53
|
+
)
|
|
54
|
+
for event in stream.read(
|
|
55
|
+
offset=0,
|
|
56
|
+
timeout=1000,
|
|
57
|
+
):
|
|
58
|
+
logger.debug(
|
|
59
|
+
'Stream message received: queue=%s id=%s',
|
|
60
|
+
name,
|
|
61
|
+
event.id,
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
logger.info(
|
|
65
|
+
'Reading stream again after first message: queue=%s offset=%s',
|
|
66
|
+
name,
|
|
67
|
+
ids[0],
|
|
68
|
+
)
|
|
69
|
+
for event in stream.read(
|
|
70
|
+
offset=ids[0],
|
|
71
|
+
timeout=1000,
|
|
72
|
+
):
|
|
73
|
+
logger.debug(
|
|
74
|
+
'Stream message received: queue=%s id=%s',
|
|
75
|
+
name,
|
|
76
|
+
event.id,
|
|
77
|
+
)
|
|
78
|
+
finally:
|
|
79
|
+
try:
|
|
80
|
+
if broker.connection is not None:
|
|
81
|
+
broker.delete_stream(name)
|
|
82
|
+
finally:
|
|
83
|
+
broker.close()
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
if __name__ == '__main__':
|
|
87
|
+
main()
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
from logging import (
|
|
2
|
+
DEBUG,
|
|
3
|
+
Filter,
|
|
4
|
+
Formatter,
|
|
5
|
+
StreamHandler,
|
|
6
|
+
getLogger,
|
|
7
|
+
)
|
|
8
|
+
from uuid import uuid4
|
|
9
|
+
|
|
10
|
+
from DefStream.Broker.Implements.Redis import (
|
|
11
|
+
Connection,
|
|
12
|
+
Configuration,
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
logger = getLogger('Sample')
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class SampleLogFilter(Filter):
|
|
19
|
+
def filter(self, record) -> bool:
|
|
20
|
+
return any(
|
|
21
|
+
record.name == prefix or record.name.startswith(prefix + '.')
|
|
22
|
+
for prefix in (
|
|
23
|
+
'Sample',
|
|
24
|
+
'DefStream.Broker.Implements.Redis',
|
|
25
|
+
)
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
def main() -> None:
|
|
30
|
+
handler = StreamHandler()
|
|
31
|
+
handler.setLevel(DEBUG)
|
|
32
|
+
handler.setFormatter(Formatter('%(asctime)s %(name)s %(levelname)s %(message)s'))
|
|
33
|
+
handler.addFilter(SampleLogFilter())
|
|
34
|
+
root_logger = getLogger()
|
|
35
|
+
root_logger.setLevel(DEBUG)
|
|
36
|
+
root_logger.addHandler(handler)
|
|
37
|
+
|
|
38
|
+
broker = Connection(Configuration())
|
|
39
|
+
name = 'defstream-sample-' + uuid4().hex
|
|
40
|
+
try:
|
|
41
|
+
broker.connect()
|
|
42
|
+
queue = broker.queue(name)
|
|
43
|
+
message_id = queue.send({
|
|
44
|
+
'message': 'Hello Redis',
|
|
45
|
+
'number': 1,
|
|
46
|
+
})
|
|
47
|
+
logger.info(
|
|
48
|
+
'Message published: queue=%s id=%s',
|
|
49
|
+
name,
|
|
50
|
+
message_id,
|
|
51
|
+
)
|
|
52
|
+
event = queue.pop(timeout=1000)
|
|
53
|
+
if event is None:
|
|
54
|
+
raise TimeoutError('Redis sample did not receive its message')
|
|
55
|
+
logger.info(
|
|
56
|
+
'Message received: queue=%s id=%s',
|
|
57
|
+
name,
|
|
58
|
+
event.id,
|
|
59
|
+
)
|
|
60
|
+
event.ack()
|
|
61
|
+
for event in queue.read(timeout=100):
|
|
62
|
+
logger.debug(
|
|
63
|
+
'History message received: queue=%s id=%s',
|
|
64
|
+
name,
|
|
65
|
+
event.id,
|
|
66
|
+
)
|
|
67
|
+
finally:
|
|
68
|
+
try:
|
|
69
|
+
if broker.connection is not None:
|
|
70
|
+
broker.delete_queue(name)
|
|
71
|
+
finally:
|
|
72
|
+
broker.close()
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
if __name__ == '__main__':
|
|
76
|
+
main()
|