DefStream 0.1.8__tar.gz → 0.1.10__tar.gz

{defstream-0.1.8 → defstream-0.1.10}/DefStream.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DefStream
-Version: 0.1.8
+Version: 0.1.10
 Summary: Synchronous message processing with pluggable broker adapters
 Home-page: https://github.com/yong5eon/DefStream
 Author: Heo Yongseon
@@ -59,9 +59,60 @@ DefStream은 메시지 브로커에서 받은 작업을 일반 Python 함수처
 - [생명주기 훅](#생명주기-훅)
 - [요청·응답 계약과 검증](#요청응답-계약과-검증)
 - [상태 확인과 작업 콘솔](#상태-확인과-작업-콘솔)
+- [로깅](#로깅)
 - [브로커 선택과 운영 주의사항](#브로커-선택과-운영-주의사항)
 - [예제와 라이선스](#예제와-라이선스)
 
+## 로깅
+
+DefStream은 표준 `logging`으로 기록하며 핸들러·포매터·레벨을 설정하지 않습니다.
+애플리케이션에서 필요한 출처만 선택해 출력하세요. 샘플은 `Sample`과 `DefStream`
+이름 및 그 하위 로거만 출력하며, 샘플의 `print()`는 로그로 대체했습니다.
+Worker의 기존 시작 배너는 로깅 설정과 무관하게 그대로 출력됩니다.
+
+```python
+from logging import DEBUG, Filter, Formatter, StreamHandler, getLogger
+
+sources = (Filter('Sample'), Filter('DefStream'))
+handler = StreamHandler()
+handler.setFormatter(Formatter(
+  '%(asctime)s %(processName)s %(name)s %(levelname)s %(message)s'
+))
+handler.addFilter(lambda record: any(source.filter(record) for source in sources))
+root = getLogger()
+root.setLevel(DEBUG)
+root.addHandler(handler)
+
+logger = getLogger('Sample')
+logger.info('Application started')
+```
+
+필터는 루트 로거가 아닌 **핸들러**에 적용합니다. `Filter('DefStream')`은
+`DefStream`과 `DefStream.` 하위 이름을 포함하지만 `DefStreamExtra`는 포함하지 않습니다.
+위 설정은 독립 실행 애플리케이션을 위한 예제이며, 이미 있는 다른 핸들러의 출력은 바꾸지 않습니다.
+브로커만 보고 싶으면 `DefStream` 대신 `DefStream.Broker.Implements.RabbitMQ` 또는
+`DefStream.Broker.Implements.Redis`를 선택할 수 있습니다.
+
+- 클래스 멤버 `logger`에 `DefStream.Worker`, `DefStream.Run`, `DefStream.Executor`,
+  `DefStream.Pool`, `DefStream.ThreadPool`, `DefStream.ProcessPool`을 사용합니다.
+- Pool 공통 메서드도 실제 풀의 로거 멤버를 사용합니다. 사용자 하위 클래스는 기본 이름을
+  상속하며 원하면 `logger`를 명시적으로 재정의할 수 있습니다.
+- Inspector·Server·RequestHandler는 `DefStream.Inspector`를 공유합니다.
+  HTTP 요청 수신은 DEBUG, 응답 상태와 전송 결과는 INFO입니다.
+  확장 고유 로그는 `DefStream.Inspector.Extensions.<확장 이름>`을 사용합니다.
+- 정상 메시지별 처리 흐름은 DEBUG, 생명주기는 INFO, 주의할 사건은 WARNING,
+  처리 실패는 ERROR로 기록합니다. 본문·결과·인증정보는 기본 로그에 포함하지 않습니다.
+- 핸들러가 전혀 없으면 Python의 `lastResort`에 의해 WARNING 이상이 stderr에 나올 수 있습니다.
+  사용자 예외 메시지에는 민감한 값을 넣지 마세요. 실패 traceback에 예외 메시지가 포함됩니다.
+
+ProcessPool은 `spawn` 자식 프로세스를 사용하므로 부모의 핸들러가 자동으로 전달되지 않습니다.
+자식도 로그를 출력하려면 import 가능한 `PoolSetup` 구현에서 같은 설정을 적용하고
+`ProcessPool(..., setups=...)`로 전달하세요. 자식 초기화 훅이 실행되기 전의 DEBUG·INFO는
+그 설정으로 수신할 수 없습니다.
+[RabbitMQ 작업 예제의 LoggingSetup](./sample/Worker/RabbitMQ/Tasks.py)과
+[부모·자식 설정 예제](./sample/Worker/RabbitMQ/Worker.py)를 참고하세요.
+기존 애플리케이션에서는 이미 설정한 핸들러를 반복 추가하지 않도록 초기화 위치를 관리해야 합니다.
+
 ## 설치
 
 Python **3.9 이상**이 필요합니다. 실제 메시지 처리를 위해 사용할 브로커 서버도 준비하세요.
@@ -494,13 +545,14 @@ class Add(
     schema=request_schema,
     validator=request_validator,
     example={'a': 10, 'b': 20},
-    description='Add two integers',
   ),
   response=Specification(
     schema=response_schema,
     validator=response_validator,
     example=30,
   ),
+  name='add',
+  description='Add two integers',
 ):
   def run(
     self,
@@ -517,6 +569,8 @@ class Add(
 - 일반 JSON Schema 딕셔너리와 직접 작성한 검증 함수도 각각 `schema`, `validator`에 전달할 수 있습니다.
 - `example`은 문서용 값이며 자동 실행·검증하지 않습니다.
 - `format`의 기본값은 `application/json`입니다. 문서의 미디어 타입만 바꾸며 브로커 코덱은 별도 설정입니다.
+- Run의 `name`은 AsyncAPI Operation 키와 Metrics 작업 키에 함께 사용합니다.
+  생략하면 `모듈명.__qualname__`을 사용하며, Run의 `description`은 AsyncAPI Operation에 표시됩니다.
 - 실행 순서는 초기화 훅 → 요청 검증 → `run()` → 응답 검증 → 완료 훅 → 응답 발행·ACK입니다.
 
 검증 예외는 작업 실패로 처리되어 오류 훅과 `on_error` 정책을 따릅니다.

{defstream-0.1.8 → defstream-0.1.10}/DefStream.egg-info/SOURCES.txt

@@ -14,6 +14,13 @@ issues/feature/1/README.md
 issues/feature/1/REQUIREMENTS.md
 issues/feature/1/TASK.md
 issues/feature/1/ci.refs.json
+issues/feature/8/IMPLEMENTS.md
+issues/feature/8/README.md
+issues/feature/8/REQUIREMENTS.md
+issues/feature/8/ci.refs.json
+issues/fix/10/IMPLEMENTS.md
+issues/fix/10/README.md
+issues/fix/10/REQUIREMENTS.md
 issues/fix/3/IMPLEMENTS.md
 issues/fix/3/README.md
 issues/fix/3/REQUIREMENTS.md
@@ -83,7 +90,9 @@ test/test_dashboard_ui.cjs
 test/test_descriptor.py
 test/test_inspector.py
 test/test_inspector_console.py
+test/test_inspector_logging.py
 test/test_lifecycle_hooks.py
+test/test_logging.py
 test/test_pool_callbacks.py
 test/test_process_signals.py
 test/test_protocol_contracts.py

{defstream-0.1.8 → defstream-0.1.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: DefStream
-Version: 0.1.8
+Version: 0.1.10
 Summary: Synchronous message processing with pluggable broker adapters
 Home-page: https://github.com/yong5eon/DefStream
 Author: Heo Yongseon
@@ -59,9 +59,60 @@ DefStream은 메시지 브로커에서 받은 작업을 일반 Python 함수처
 - [생명주기 훅](#생명주기-훅)
 - [요청·응답 계약과 검증](#요청응답-계약과-검증)
 - [상태 확인과 작업 콘솔](#상태-확인과-작업-콘솔)
+- [로깅](#로깅)
 - [브로커 선택과 운영 주의사항](#브로커-선택과-운영-주의사항)
 - [예제와 라이선스](#예제와-라이선스)
 
+## 로깅
+
+DefStream은 표준 `logging`으로 기록하며 핸들러·포매터·레벨을 설정하지 않습니다.
+애플리케이션에서 필요한 출처만 선택해 출력하세요. 샘플은 `Sample`과 `DefStream`
+이름 및 그 하위 로거만 출력하며, 샘플의 `print()`는 로그로 대체했습니다.
+Worker의 기존 시작 배너는 로깅 설정과 무관하게 그대로 출력됩니다.
+
+```python
+from logging import DEBUG, Filter, Formatter, StreamHandler, getLogger
+
+sources = (Filter('Sample'), Filter('DefStream'))
+handler = StreamHandler()
+handler.setFormatter(Formatter(
+  '%(asctime)s %(processName)s %(name)s %(levelname)s %(message)s'
+))
+handler.addFilter(lambda record: any(source.filter(record) for source in sources))
+root = getLogger()
+root.setLevel(DEBUG)
+root.addHandler(handler)
+
+logger = getLogger('Sample')
+logger.info('Application started')
+```
+
+필터는 루트 로거가 아닌 **핸들러**에 적용합니다. `Filter('DefStream')`은
+`DefStream`과 `DefStream.` 하위 이름을 포함하지만 `DefStreamExtra`는 포함하지 않습니다.
+위 설정은 독립 실행 애플리케이션을 위한 예제이며, 이미 있는 다른 핸들러의 출력은 바꾸지 않습니다.
+브로커만 보고 싶으면 `DefStream` 대신 `DefStream.Broker.Implements.RabbitMQ` 또는
+`DefStream.Broker.Implements.Redis`를 선택할 수 있습니다.
+
+- 클래스 멤버 `logger`에 `DefStream.Worker`, `DefStream.Run`, `DefStream.Executor`,
+  `DefStream.Pool`, `DefStream.ThreadPool`, `DefStream.ProcessPool`을 사용합니다.
+- Pool 공통 메서드도 실제 풀의 로거 멤버를 사용합니다. 사용자 하위 클래스는 기본 이름을
+  상속하며 원하면 `logger`를 명시적으로 재정의할 수 있습니다.
+- Inspector·Server·RequestHandler는 `DefStream.Inspector`를 공유합니다.
+  HTTP 요청 수신은 DEBUG, 응답 상태와 전송 결과는 INFO입니다.
+  확장 고유 로그는 `DefStream.Inspector.Extensions.<확장 이름>`을 사용합니다.
+- 정상 메시지별 처리 흐름은 DEBUG, 생명주기는 INFO, 주의할 사건은 WARNING,
+  처리 실패는 ERROR로 기록합니다. 본문·결과·인증정보는 기본 로그에 포함하지 않습니다.
+- 핸들러가 전혀 없으면 Python의 `lastResort`에 의해 WARNING 이상이 stderr에 나올 수 있습니다.
+  사용자 예외 메시지에는 민감한 값을 넣지 마세요. 실패 traceback에 예외 메시지가 포함됩니다.
+
+ProcessPool은 `spawn` 자식 프로세스를 사용하므로 부모의 핸들러가 자동으로 전달되지 않습니다.
+자식도 로그를 출력하려면 import 가능한 `PoolSetup` 구현에서 같은 설정을 적용하고
+`ProcessPool(..., setups=...)`로 전달하세요. 자식 초기화 훅이 실행되기 전의 DEBUG·INFO는
+그 설정으로 수신할 수 없습니다.
+[RabbitMQ 작업 예제의 LoggingSetup](./sample/Worker/RabbitMQ/Tasks.py)과
+[부모·자식 설정 예제](./sample/Worker/RabbitMQ/Worker.py)를 참고하세요.
+기존 애플리케이션에서는 이미 설정한 핸들러를 반복 추가하지 않도록 초기화 위치를 관리해야 합니다.
+
 ## 설치
 
 Python **3.9 이상**이 필요합니다. 실제 메시지 처리를 위해 사용할 브로커 서버도 준비하세요.
@@ -494,13 +545,14 @@ class Add(
     schema=request_schema,
     validator=request_validator,
     example={'a': 10, 'b': 20},
-    description='Add two integers',
   ),
   response=Specification(
     schema=response_schema,
     validator=response_validator,
     example=30,
   ),
+  name='add',
+  description='Add two integers',
 ):
   def run(
     self,
@@ -517,6 +569,8 @@ class Add(
 - 일반 JSON Schema 딕셔너리와 직접 작성한 검증 함수도 각각 `schema`, `validator`에 전달할 수 있습니다.
 - `example`은 문서용 값이며 자동 실행·검증하지 않습니다.
 - `format`의 기본값은 `application/json`입니다. 문서의 미디어 타입만 바꾸며 브로커 코덱은 별도 설정입니다.
+- Run의 `name`은 AsyncAPI Operation 키와 Metrics 작업 키에 함께 사용합니다.
+  생략하면 `모듈명.__qualname__`을 사용하며, Run의 `description`은 AsyncAPI Operation에 표시됩니다.
 - 실행 순서는 초기화 훅 → 요청 검증 → `run()` → 응답 검증 → 완료 훅 → 응답 발행·ACK입니다.
 
 검증 예외는 작업 실패로 처리되어 오류 훅과 `on_error` 정책을 따릅니다.

{defstream-0.1.8 → defstream-0.1.10}/README.en.md

@@ -30,6 +30,13 @@ Configure execution, acknowledgements, failure policies, and monitoring without
 - [Broker selection and operational considerations](#broker-selection-and-operational-considerations)
 - [Examples and license](#examples-and-license)
 
+## 로깅 지원
+
+클래스별 표준 로거와 사용자 주도 핸들러 설정을 지원합니다.
+샘플은 `Sample` 및 `DefStream` 계층만 출력하며, ProcessPool 자식은 별도 setup 훅으로
+출력을 설정합니다. Worker의 시작 배너는 유지됩니다.
+로거 이름, 선택 수신, 예외 메시지 주의사항과 프로세스 설정은 [로깅 안내](./README.md#로깅)를 참고하세요.
+
 ## Installation
 
 Requires Python **3.9 or newer**. Prepare the broker server you intend to use.
@@ -474,13 +481,14 @@ class Add(
     schema=request_schema,
     validator=request_validator,
     example={'a': 10, 'b': 20},
-    description='Add two integers',
   ),
   response=Specification(
     schema=response_schema,
     validator=response_validator,
     example=30,
   ),
+  name='add',
+  description='Add two integers',
 ):
   def run(
     self,
@@ -497,6 +505,8 @@ class Add(
 - Plain JSON Schema dictionaries and custom validation functions can also be passed as `schema` and `validator`.
 - `example` is documentation data and is not automatically executed or validated.
 - `format` defaults to `application/json`. It changes documented media types, not broker codecs.
+- Run's `name` is used as both the AsyncAPI Operation key and the Metrics task key.
+  When omitted, `module.__qualname__` is used; Run's `description` appears on the AsyncAPI Operation.
 - Execution order: setup hooks → request validation → `run()` → response validation → completion hooks → reply/ACK.
 
 Validation exceptions are task failures and follow error hooks and the `on_error`

{defstream-0.1.8 → defstream-0.1.10}/README.md

@@ -26,9 +26,60 @@ DefStream은 메시지 브로커에서 받은 작업을 일반 Python 함수처
 - [생명주기 훅](#생명주기-훅)
 - [요청·응답 계약과 검증](#요청응답-계약과-검증)
 - [상태 확인과 작업 콘솔](#상태-확인과-작업-콘솔)
+- [로깅](#로깅)
 - [브로커 선택과 운영 주의사항](#브로커-선택과-운영-주의사항)
 - [예제와 라이선스](#예제와-라이선스)
 
+## 로깅
+
+DefStream은 표준 `logging`으로 기록하며 핸들러·포매터·레벨을 설정하지 않습니다.
+애플리케이션에서 필요한 출처만 선택해 출력하세요. 샘플은 `Sample`과 `DefStream`
+이름 및 그 하위 로거만 출력하며, 샘플의 `print()`는 로그로 대체했습니다.
+Worker의 기존 시작 배너는 로깅 설정과 무관하게 그대로 출력됩니다.
+
+```python
+from logging import DEBUG, Filter, Formatter, StreamHandler, getLogger
+
+sources = (Filter('Sample'), Filter('DefStream'))
+handler = StreamHandler()
+handler.setFormatter(Formatter(
+  '%(asctime)s %(processName)s %(name)s %(levelname)s %(message)s'
+))
+handler.addFilter(lambda record: any(source.filter(record) for source in sources))
+root = getLogger()
+root.setLevel(DEBUG)
+root.addHandler(handler)
+
+logger = getLogger('Sample')
+logger.info('Application started')
+```
+
+필터는 루트 로거가 아닌 **핸들러**에 적용합니다. `Filter('DefStream')`은
+`DefStream`과 `DefStream.` 하위 이름을 포함하지만 `DefStreamExtra`는 포함하지 않습니다.
+위 설정은 독립 실행 애플리케이션을 위한 예제이며, 이미 있는 다른 핸들러의 출력은 바꾸지 않습니다.
+브로커만 보고 싶으면 `DefStream` 대신 `DefStream.Broker.Implements.RabbitMQ` 또는
+`DefStream.Broker.Implements.Redis`를 선택할 수 있습니다.
+
+- 클래스 멤버 `logger`에 `DefStream.Worker`, `DefStream.Run`, `DefStream.Executor`,
+  `DefStream.Pool`, `DefStream.ThreadPool`, `DefStream.ProcessPool`을 사용합니다.
+- Pool 공통 메서드도 실제 풀의 로거 멤버를 사용합니다. 사용자 하위 클래스는 기본 이름을
+  상속하며 원하면 `logger`를 명시적으로 재정의할 수 있습니다.
+- Inspector·Server·RequestHandler는 `DefStream.Inspector`를 공유합니다.
+  HTTP 요청 수신은 DEBUG, 응답 상태와 전송 결과는 INFO입니다.
+  확장 고유 로그는 `DefStream.Inspector.Extensions.<확장 이름>`을 사용합니다.
+- 정상 메시지별 처리 흐름은 DEBUG, 생명주기는 INFO, 주의할 사건은 WARNING,
+  처리 실패는 ERROR로 기록합니다. 본문·결과·인증정보는 기본 로그에 포함하지 않습니다.
+- 핸들러가 전혀 없으면 Python의 `lastResort`에 의해 WARNING 이상이 stderr에 나올 수 있습니다.
+  사용자 예외 메시지에는 민감한 값을 넣지 마세요. 실패 traceback에 예외 메시지가 포함됩니다.
+
+ProcessPool은 `spawn` 자식 프로세스를 사용하므로 부모의 핸들러가 자동으로 전달되지 않습니다.
+자식도 로그를 출력하려면 import 가능한 `PoolSetup` 구현에서 같은 설정을 적용하고
+`ProcessPool(..., setups=...)`로 전달하세요. 자식 초기화 훅이 실행되기 전의 DEBUG·INFO는
+그 설정으로 수신할 수 없습니다.
+[RabbitMQ 작업 예제의 LoggingSetup](./sample/Worker/RabbitMQ/Tasks.py)과
+[부모·자식 설정 예제](./sample/Worker/RabbitMQ/Worker.py)를 참고하세요.
+기존 애플리케이션에서는 이미 설정한 핸들러를 반복 추가하지 않도록 초기화 위치를 관리해야 합니다.
+
 ## 설치
 
 Python **3.9 이상**이 필요합니다. 실제 메시지 처리를 위해 사용할 브로커 서버도 준비하세요.
@@ -461,13 +512,14 @@ class Add(
     schema=request_schema,
     validator=request_validator,
     example={'a': 10, 'b': 20},
-    description='Add two integers',
   ),
   response=Specification(
     schema=response_schema,
     validator=response_validator,
     example=30,
   ),
+  name='add',
+  description='Add two integers',
 ):
   def run(
     self,
@@ -484,6 +536,8 @@ class Add(
 - 일반 JSON Schema 딕셔너리와 직접 작성한 검증 함수도 각각 `schema`, `validator`에 전달할 수 있습니다.
 - `example`은 문서용 값이며 자동 실행·검증하지 않습니다.
 - `format`의 기본값은 `application/json`입니다. 문서의 미디어 타입만 바꾸며 브로커 코덱은 별도 설정입니다.
+- Run의 `name`은 AsyncAPI Operation 키와 Metrics 작업 키에 함께 사용합니다.
+  생략하면 `모듈명.__qualname__`을 사용하며, Run의 `description`은 AsyncAPI Operation에 표시됩니다.
 - 실행 순서는 초기화 훅 → 요청 검증 → `run()` → 응답 검증 → 완료 훅 → 응답 발행·ACK입니다.
 
 검증 예외는 작업 실패로 처리되어 오류 훅과 `on_error` 정책을 따릅니다.

defstream-0.1.10/issues/feature/8/IMPLEMENTS.md

@@ -0,0 +1,106 @@
+# 로깅 지원 구현 기록
+
+## 1. 구현 개요
+
+[요구사항](./REQUIREMENTS.md)에 따라 Worker 실행 흐름과 Inspector에 Python 표준
+`logging`을 적용했다. 출력 정책은 애플리케이션에 맡기고 클래스별 명시적 로거로
+관찰 지점을 제공한다.
+
+- 구현·검증일: 2026-10-20
+- 사용자용 안내: [변경 로그](./README.md)
+- 연계 구현: [RabbitMQ](../../../../DefStream-RabbitMQ/issues/feature/5/IMPLEMENTS.md),
+  [Redis](../../../../DefStream-Redis/issues/feature/5/IMPLEMENTS.md)
+
+## 2. 클래스별 로거와 기록 책임
+
+로거는 클래스 멤버 `logger`로 정의하고 공통 메서드는 `self.logger`를 사용한다.
+사용자 하위 클래스의 이름을 자동으로 사용하지 않으며, 명시적으로 재정의할 수 있다.
+
+| 대상 | 로거 이름 | 구현한 관찰 지점 |
+| --- | --- | --- |
+| [Worker](../../../src/Worker/Worker.py) | `DefStream.Worker` | 작업 등록, 연결·구독·훅, 수신·제출, 성공·실패 정책, 종료·미확인 메시지 |
+| [Pool](../../../src/Worker/Pool.py) | `DefStream.Pool` | 제출, 포화, 슬롯 반환, 완료 대기와 종료 |
+| ThreadPool·ProcessPool | `DefStream.ThreadPool`·`DefStream.ProcessPool` | 구체 풀 구성과 상속받은 공통 동작 |
+| [Executor](../../../src/Worker/Executor.py) | `DefStream.Executor` | 실행 환경 시작·종료, 작업·결과 전달과 실행 환경 장애 |
+| [Run](../../../src/Worker/Run.py) | `DefStream.Run` | 작업 전체 이름, 훅·입출력 검증·실행 단계와 소요 시간 |
+| [Inspector·Server·RequestHandler](../../../src/Inspector/Inspector.py) | `DefStream.Inspector` | 확장 등록·시작, 서버 생명주기, HTTP 수신·응답과 내부 오류 |
+| [Inspector 확장](../../../src/Inspector/Extensions) | `DefStream.Inspector.Extensions.<클래스 이름>` | HealthCheck·Console·Metrics·Dashboard·Specifications의 고유 처리 |
+
+ThreadPool·ProcessPool의 공통 처리는 구체 클래스의 로거로 기록한다.
+`Specification`에는 독립 로거를 추가하지 않았다.
+
+## 3. 레벨과 실패 처리
+
+- INFO: Worker·풀·실행 환경·서버의 생명주기와 HTTP 응답 전송 결과.
+- DEBUG: 메시지별 정상 처리, 작업 실행·검증·훅, 풀 포화와 확장 고유 진단.
+- WARNING: 잘못된 메시지, 명시적 완료 대기의 시간 초과와 Console 요청 거부 등.
+- ERROR: 작업·실행 환경·서버·확장 내부 실패와 종료 후 확인 처리 불가.
+
+Worker로 전달되는 작업 실패의 최종 ERROR와 traceback은 Worker가 담당한다.
+Run·Pool·Executor의 일반 작업 실패 추적은 DEBUG로 기록해 중복을 줄였다.
+Mapping이 아닌 메시지의 거부는 WARNING으로 구분하고 기존 실패 정책 호출은 유지했다.
+Run을 직접 호출했을 때의 예외 전파도 유지한다.
+
+## 4. Inspector의 HTTP 기록
+
+기본 WSGI 요청 처리 경계를 확장하여 다음을 기록한다.
+
+- 파싱한 요청 수신: DEBUG, HTTP 메서드와 쿼리를 제외한 경로.
+- 응답 전송 결과: INFO, 메서드·경로·상태 코드·응답 크기·소요 시간.
+- WSGI·연결 처리 실패: ERROR, 예외 타입과 프레임의 파일·줄·함수 위치.
+
+확장에서는 공통 HTTP 접근 로그를 반복하지 않는다. 전송 중단을 정상 전송으로
+기록하지 않으며, 오류 기록에는 예외 문자열과 소스 코드 줄을 포함하지 않는다.
+HealthCheck는 probe 예약·응답·판정과 응답 생성을 DEBUG로 기록하고,
+예약 실패를 ERROR로 기록한다. 상태 변화 전용 INFO·WARNING은 추가하지 않았다.
+
+## 5. 출력 설정과 샘플
+
+- 라이브러리는 핸들러·NullHandler·포매터·필터·레벨을 설정하지 않는다.
+- 루트 로거까지 기본 전파를 유지하며, 미설정 시 표준 `logging.lastResort`가
+  WARNING 이상을 stderr에 출력할 수 있다.
+- 런타임 로그 메시지는 영어로 작성하고 한국어 문서·주석은 유지한다.
+- 본문·결과·인증정보를 기본 문맥에 넣지 않는다. 단, Worker의 작업 실패
+  traceback에는 사용자 예외 메시지가 포함될 수 있으므로 사용자가 주의해야 한다.
+- [Worker 샘플](../../../sample/Worker)과 [Broker 샘플](../../../sample/Broker)은
+  `Sample`과 `DefStream` 계층만 핸들러 필터로 선택한다.
+- 샘플의 `print()`는 로그로 전환하고 라이브러리 시작 배너는 유지했다.
+- [RabbitMQ Worker 샘플](../../../sample/Worker/RabbitMQ/Worker.py)은 부모 진입점과
+  ProcessPool의 `setups`에 [LoggingSetup](../../../sample/Worker/RabbitMQ/Tasks.py)을
+  적용한다. `spawn` 자식이 부모의 핸들러를 자동 상속한다고 가정하지 않는다.
+
+## 6. 검증 결과
+
+Python 3.13.16에서 실제 RabbitMQ·Redis가 실행 중인 환경으로 검증했다.
+
+| 검증 범위 | 결과 |
+| --- | --- |
+| 코어 로깅·Inspector·Worker·풀·훅·프로세스·메시지 관련 테스트 | 151개 통과 |
+| RabbitMQ 연계 테스트 | 52개 통과 |
+| Redis 연계 테스트 | 25개 통과 |
+| 세 프로젝트 소스·샘플의 로그 및 observe 호출 문자열 | 376곳 점검, 한국어 문자열 없음 |
+| 세 프로젝트 소스·샘플 `compileall` 및 `git diff --check` | 통과 |
+
+[로깅 테스트](../../../test/test_logging.py)는 클래스 멤버·상속·사용자 재정의,
+레벨·본문 제외·작업 실패 traceback 중복 방지·배너 유지·샘플 필터·spawn 설정을
+검증한다. [Inspector 로깅 테스트](../../../test/test_inspector_logging.py)는 실제 HTTP
+요청에서 수신·응답 각 1회 기록, 쿼리·본문 제외, WSGI 500과 전송 중단을 검증한다.
+기존 테스트의 이전 모듈 로거 기대값도 새 이름과 레벨에 맞췄다.
+
+위 228개는 선택해 실행한 관련 테스트의 합계이며 코어 전체 테스트 실행을 뜻하지 않는다.
+모든 Python 버전·모든 파일의 정적 타입 검사나 배포 검증을 완료한 것은 아니다.
+
+### 재검증
+
+개발 가상환경과 로컬 브로커가 준비된 작업공간 루트에서 실행한다.
+통합 테스트는 브로커에 테스트 자원을 생성·정리하므로 운영 환경을 사용하지 않는다.
+
+```powershell
+$env:PYTHONIOENCODING = 'utf-8'
+$env:DEFSTREAM_RABBITMQ_TESTS = '1'
+$env:DEFSTREAM_REDIS_TESTS = '1'
+Set-Location .\DefStream\test
+& ..\..\.venv\Scripts\python.exe -m unittest test_logging test_inspector_logging test_worker test_worker_startup test_pool_callbacks test_runner_hooks test_lifecycle_hooks test_process_signals test_inspector test_inspector_console test_dashboard test_specifications test_protocol_contracts test_task_messages
+```
+
+브로커별 재검증 명령은 각 구현 기록을 참고한다.

defstream-0.1.10/issues/feature/8/README.md

@@ -0,0 +1,40 @@
+# 로깅 지원
+
+## 변경 요약
+
+Worker와 Inspector의 동작을 클래스별 표준 로거로 관찰할 수 있습니다.
+라이브러리는 로그를 기록하며, 출력 대상·형식·레벨·필터는 애플리케이션이 정합니다.
+런타임 로그 메시지는 영어입니다.
+
+## 추가한 기록
+
+- `DefStream.Worker`: 등록·시작·수신·완료·실패·종료.
+- `DefStream.Run`: 작업별 훅·입출력 검증·실행 단계.
+- `DefStream.Pool`, `DefStream.ThreadPool`, `DefStream.ProcessPool`,
+  `DefStream.Executor`: 실행 환경·제출·결과 회수·대기·종료.
+- `DefStream.Inspector`: 서버 생명주기, 요청 수신(DEBUG), 응답 상태·크기·시간(INFO).
+- `DefStream.Inspector.Extensions.<클래스 이름>`: 각 확장 고유 진단.
+
+정상 메시지별 상세 흐름은 DEBUG, 주요 생명주기는 INFO로 확인할 수 있습니다.
+잘못된 메시지와 대기 시간 초과는 WARNING, 작업·내부 처리 실패는 ERROR로 구분합니다.
+Pool 공통 동작도 실제 ThreadPool·ProcessPool의 로거 이름으로 기록됩니다.
+
+## 사용자 설정과 호환성
+
+- 기존 `DefStream.Worker.Worker` 등 모듈 경로 기반 이름으로 필터링했다면
+  새 클래스별 이름으로 바꾸세요. `DefStream` 계층 전체 수신도 가능합니다.
+- 클래스 멤버 `logger`를 상속하며 사용자 하위 클래스에서 재정의할 수 있습니다.
+  사용자 작업이 직접 생성한 로거 이름은 프레임워크가 바꾸지 않습니다.
+- 핸들러·NullHandler·레벨을 자동 설정하지 않습니다.
+  핸들러가 없으면 Python의 `lastResort`로 WARNING 이상이 출력될 수 있습니다.
+- 본문·결과·인증정보는 기본 로그 문맥에서 제외합니다. 사용자 예외 메시지는
+  Worker의 실패 traceback에 포함될 수 있으므로 민감정보를 넣지 마세요.
+- 작업 처리·정산·종료 계약과 기존 시작 배너는 유지합니다.
+
+## 샘플 변경
+
+샘플은 `print()` 대신 `Sample` 로거를 사용하며 `Sample`과 `DefStream` 계층만
+출력합니다. [RabbitMQ Worker 샘플](../../../sample/Worker/RabbitMQ/Worker.py)은
+부모와 spawn 자식에 [LoggingSetup](../../../sample/Worker/RabbitMQ/Tasks.py)을 적용합니다.
+실제 애플리케이션도 ProcessPool 자식의 로깅을 별도로 설정해야 합니다.
+설정 예제는 [사용 설명서](../../../README.md#로깅)를 참고하세요.