quapp-common 0.0.13.dev9__tar.gz → 0.0.14.dev1__tar.gz

{quapp_common-0.0.13.dev9/quapp_common.egg-info → quapp_common-0.0.14.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-common
-Version: 0.0.13.dev9
+Version: 0.0.14.dev1
 Summary: Quapp common library supporting Quapp Platform for Quantum Computing
 Author-email: "CITYNOW Co. Ltd. " <corp@citynow.vn>
 License: The MIT License (MIT)
@@ -114,7 +114,69 @@ Notes:
 
 ## Recently Changes Highlights
 
-### v0.0.14.dev1 — Error logging & observability (Phase 0)
+### v0.0.14.dev1 — Error taxonomy & error envelope (Phase 1)
+
+Tiếp nối Phase 0. Bổ sung phân loại lỗi có ngữ nghĩa và envelope dùng chung cho
+Function Log lẫn Job Log. **Additive**: `job_result` chỉ thêm field `error`,
+`message` và `exception` giữ nguyên; contract callback URL không đổi.
+
+**Taxonomy — hai chiều phân loại độc lập**
+- `enum/error_category.py`: `ErrorCategory` 13 giá trị, nhóm theo *ai xử lý
+  được* (`owner_of()` → USER / WORKSPACE_ADMIN / PROVIDER / PLATFORM).
+- `enum/runtime_phase.py`: `RuntimePhase` 9 giá trị. Tách được
+  `PROVIDER_INVOCATION` / `COMPILATION` / `EXECUTION` — trước đây auth sai,
+  transpile fail và provider từ chối job đều ra chung nhãn `EXECUTION`.
+  `PHASE_TO_STEP` giữ nguyên contract `InvocationStep` của callback URL.
+
+**Classifier (`util/error_classifier.py`)** — tổ hợp 5 tín hiệu theo độ tin cậy:
+1. `phase` — biết chắc từ context manager, không suy đoán;
+2. `frame_owner()` — code của ai, dựa vào đường dẫn frame sâu nhất
+   (`function/` = user, `quapp_*` = platform, `site-packages/` = SDK);
+3. tên class exception, đi hết **cause chain** qua cả `__cause__` *và*
+   `__context__` — cần thiết vì nhiều provider lib bọc lỗi bằng
+   `raise ValueError(...)` trong khối `except` mà không có `from`;
+4. attribute đọc được: HTTP status, AWS error code, exit code, signal;
+5. message pattern (dùng cuối cùng).
+
+`register_rules()` cho phép lib provider đăng ký rule đặc thù SDK khi import,
+nên `qapp-common` không phải import qiskit/braket. Batch đăng ký sau được xét
+trước; trong cùng batch giữ nguyên thứ tự. Rule ném lỗi bị bỏ qua chứ không làm
+hỏng đường báo lỗi. 20 rule generic sẵn có.
+
+Fallback nhiều tầng nên **không bao giờ trả `UNKNOWN` một cách mù**: không rule
+nào khớp thì suy từ frame ownership, rồi tới phase.
+
+**Envelope (`data/response/error_report.py`)** — `job_result['error']` gồm
+`code`, `category`, `phase`, `owner`, `retryable`, `rootCause` (type + detail +
+file:line), `causeChain`, `stackTrace` (full, đã redact),
+`handlerStackTrace` (stack JS/.NET cho handler không phải Python),
+`context`, `resolution` (summary + steps + docUrl), `retry`, `traceId`.
+`log_fields()` bind cùng vocabulary vào Function Log.
+
+**Timeline (`config/log_context.py`)** — context manager `phase()` phát
+`phase_start` / `phase_end` / `phase_failed` kèm `duration_ms`. Đây là dữ liệu
+để UI vẽ timeline và chỉ ra job chết ở bước nào. `phase_failed` ở mức WARNING để
+thấy được khi chạy `LOG_LEVEL=INFO`.
+
+`_FAILED_PHASE` ghi lại phase mà exception thoát ra: khối `except` xử lý lỗi gần
+như luôn nằm **ngoài** `with phase(...)`, lúc đó phase đang mở đã bị reset trong
+`finally`. Không có nó thì mọi `ErrorReport` đều `phase=None` và fallback theo
+phase không bao giờ chạy. Dùng `effective_phase()` ở đường báo lỗi.
+
+**`config/thread_config.py`** — `ContextAwareThreadPoolExecutor` copy contextvars
+khi submit. `ThreadPoolExecutor` thuần không làm việc này (khác
+`asyncio.to_thread`), nên analysis + finalization chạy trong
+`circuit_running_pool` sẽ mất `job_id` / `trace_id` / `phase`.
+
+**Call-site** — `phase()` bọc PREPROCESSING / DEVICE_SELECTION /
+PROVIDER_INVOCATION / COMPILATION / EXECUTION / ANALYSIS; toàn bộ 13 call-site
+của `build_error_job_response()` truyền `phase=`.
+
+**Test** — `tests/test_error_classifier.py` (52 case: cause chain, HTTP/AWS
+code, frame ownership, phase fallback, rule ordering) và
+`tests/test_error_report.py` (44 case: envelope, timeline, thread pool).
+
+### v0.0.13.dev9 — Error logging & observability (Phase 0)
 
 Mục tiêu: Function Log và Job Log phải chỉ ra được nguyên nhân lỗi. Toàn bộ thay
 đổi trong bản này là **additive hoặc bug fix** — không đổi contract callback,

{quapp_common-0.0.13.dev9 → quapp_common-0.0.14.dev1}/README.md

@@ -73,7 +73,69 @@ Notes:
 
 ## Recently Changes Highlights
 
-### v0.0.14.dev1 — Error logging & observability (Phase 0)
+### v0.0.14.dev1 — Error taxonomy & error envelope (Phase 1)
+
+Tiếp nối Phase 0. Bổ sung phân loại lỗi có ngữ nghĩa và envelope dùng chung cho
+Function Log lẫn Job Log. **Additive**: `job_result` chỉ thêm field `error`,
+`message` và `exception` giữ nguyên; contract callback URL không đổi.
+
+**Taxonomy — hai chiều phân loại độc lập**
+- `enum/error_category.py`: `ErrorCategory` 13 giá trị, nhóm theo *ai xử lý
+  được* (`owner_of()` → USER / WORKSPACE_ADMIN / PROVIDER / PLATFORM).
+- `enum/runtime_phase.py`: `RuntimePhase` 9 giá trị. Tách được
+  `PROVIDER_INVOCATION` / `COMPILATION` / `EXECUTION` — trước đây auth sai,
+  transpile fail và provider từ chối job đều ra chung nhãn `EXECUTION`.
+  `PHASE_TO_STEP` giữ nguyên contract `InvocationStep` của callback URL.
+
+**Classifier (`util/error_classifier.py`)** — tổ hợp 5 tín hiệu theo độ tin cậy:
+1. `phase` — biết chắc từ context manager, không suy đoán;
+2. `frame_owner()` — code của ai, dựa vào đường dẫn frame sâu nhất
+   (`function/` = user, `quapp_*` = platform, `site-packages/` = SDK);
+3. tên class exception, đi hết **cause chain** qua cả `__cause__` *và*
+   `__context__` — cần thiết vì nhiều provider lib bọc lỗi bằng
+   `raise ValueError(...)` trong khối `except` mà không có `from`;
+4. attribute đọc được: HTTP status, AWS error code, exit code, signal;
+5. message pattern (dùng cuối cùng).
+
+`register_rules()` cho phép lib provider đăng ký rule đặc thù SDK khi import,
+nên `qapp-common` không phải import qiskit/braket. Batch đăng ký sau được xét
+trước; trong cùng batch giữ nguyên thứ tự. Rule ném lỗi bị bỏ qua chứ không làm
+hỏng đường báo lỗi. 20 rule generic sẵn có.
+
+Fallback nhiều tầng nên **không bao giờ trả `UNKNOWN` một cách mù**: không rule
+nào khớp thì suy từ frame ownership, rồi tới phase.
+
+**Envelope (`data/response/error_report.py`)** — `job_result['error']` gồm
+`code`, `category`, `phase`, `owner`, `retryable`, `rootCause` (type + detail +
+file:line), `causeChain`, `stackTrace` (full, đã redact),
+`handlerStackTrace` (stack JS/.NET cho handler không phải Python),
+`context`, `resolution` (summary + steps + docUrl), `retry`, `traceId`.
+`log_fields()` bind cùng vocabulary vào Function Log.
+
+**Timeline (`config/log_context.py`)** — context manager `phase()` phát
+`phase_start` / `phase_end` / `phase_failed` kèm `duration_ms`. Đây là dữ liệu
+để UI vẽ timeline và chỉ ra job chết ở bước nào. `phase_failed` ở mức WARNING để
+thấy được khi chạy `LOG_LEVEL=INFO`.
+
+`_FAILED_PHASE` ghi lại phase mà exception thoát ra: khối `except` xử lý lỗi gần
+như luôn nằm **ngoài** `with phase(...)`, lúc đó phase đang mở đã bị reset trong
+`finally`. Không có nó thì mọi `ErrorReport` đều `phase=None` và fallback theo
+phase không bao giờ chạy. Dùng `effective_phase()` ở đường báo lỗi.
+
+**`config/thread_config.py`** — `ContextAwareThreadPoolExecutor` copy contextvars
+khi submit. `ThreadPoolExecutor` thuần không làm việc này (khác
+`asyncio.to_thread`), nên analysis + finalization chạy trong
+`circuit_running_pool` sẽ mất `job_id` / `trace_id` / `phase`.
+
+**Call-site** — `phase()` bọc PREPROCESSING / DEVICE_SELECTION /
+PROVIDER_INVOCATION / COMPILATION / EXECUTION / ANALYSIS; toàn bộ 13 call-site
+của `build_error_job_response()` truyền `phase=`.
+
+**Test** — `tests/test_error_classifier.py` (52 case: cause chain, HTTP/AWS
+code, frame ownership, phase fallback, rule ordering) và
+`tests/test_error_report.py` (44 case: envelope, timeline, thread pool).
+
+### v0.0.13.dev9 — Error logging & observability (Phase 0)
 
 Mục tiêu: Function Log và Job Log phải chỉ ra được nguyên nhân lỗi. Toàn bộ thay
 đổi trong bản này là **additive hoặc bug fix** — không đổi contract callback,

{quapp_common-0.0.13.dev9 → quapp_common-0.0.14.dev1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quapp-common"
-version = "0.0.13.dev9"
+version = "0.0.14.dev1"
 description = "Quapp common library supporting Quapp Platform for Quantum Computing"
 readme = "README.md"
 authors = [{ name = "CITYNOW Co. Ltd. ", email = "corp@citynow.vn" }]

{quapp_common-0.0.13.dev9 → quapp_common-0.0.14.dev1}/quapp_common/async_tasks/post_processing_task.py

@@ -5,6 +5,7 @@ from .async_task import AsyncTask
 from ..config.logging_config import job_logger
 from ..data.promise.post_processing_promise import PostProcessingPromise
 from ..enum.media_type import MediaType
+from ..enum.runtime_phase import RuntimePhase
 from ..util.http_utils import get_job_id_from_url
 from ..util.json_parser_utils import parse
 
@@ -50,7 +51,8 @@ class PostProcessingTask(AsyncTask):
             job_response = build_error_job_response(
                     exception, job_response,
                     message='Error when post processing job result',
-                    stage='while post-processing the job result')
+                    stage='while post-processing the job result',
+                    phase=RuntimePhase.POST_PROCESSING)
 
             update_job_metadata(job_response,
                                 self.promise.callback_url.on_error)

{quapp_common-0.0.13.dev9 → quapp_common-0.0.14.dev1}/quapp_common/component/backend/invocation.py

@@ -6,6 +6,7 @@ from abc import ABC, abstractmethod
 
 from ..callback.update_job_metadata import update_job_metadata
 from ...component.device.device_selection import DeviceSelection
+from ...config.log_context import bind_job, enrich_job_context, phase
 from ...config.logging_config import job_logger
 from ...config.thread_config import circuit_running_pool
 from ...data.backend.backend_information import BackendInformation
@@ -15,6 +16,7 @@ from ...data.response.authentication import Authentication
 from ...data.response.custom_header import CustomHeader
 from ...data.response.job_response import JobResponse
 from ...enum.invocation_step import InvocationStep
+from ...enum.runtime_phase import RuntimePhase
 from ...enum.sdk import Sdk
 from ...enum.status.status_code import StatusCode
 from ...model.provider.provider import Provider
@@ -82,8 +84,12 @@ class Invocation(ABC):
             return None
 
         try:
-            self.logger.debug("Preparing backend data")
-            self.__prepare_backend_data(circuit)
+            with phase(RuntimePhase.DEVICE_SELECTION):
+                self.__prepare_backend_data(circuit)
+
+            enrich_job_context(
+                    device=self.backend_information.device_name,
+                    provider=self.backend_information.provider_tag.value)
             self.logger.info(
                     f"Backend data prepared: device {self.backend_information.device_name}, provider {self.backend_information.provider_tag.value}")
 
@@ -94,7 +100,8 @@ class Invocation(ABC):
 
             job_response = build_error_job_response(exception,
                                                     message='Error when prepare backend data',
-                                                    stage='while preparing the backend')
+                                                    stage='while preparing the backend',
+                                                    phase=RuntimePhase.DEVICE_SELECTION)
             job_response.authentication = self.authentication
             update_job_metadata(job_response, self.callback_dict.get(
                     InvocationStep.PREPARATION).on_error)
@@ -125,10 +132,15 @@ class Invocation(ABC):
             self.logger.debug(
                     f"Executing job with provider tag: {provider_tag.value}")
 
-            provider = self._create_provider()
+            # PROVIDER_INVOCATION tách riêng khỏi EXECUTION: lỗi authenticate
+            # với provider và lỗi provider từ chối circuit là hai chuyện khác
+            # nhau, trước đây cùng ra nhãn EXECUTION.
+            with phase(RuntimePhase.PROVIDER_INVOCATION):
+                provider = self._create_provider()
 
-            self.logger.debug(f"Executing job with device name: {device_name}")
-            device = self._create_device(provider)
+                self.logger.debug(
+                        f"Executing job with device name: {device_name}")
+                device = self._create_device(provider)
 
         except Exception as exception:
             self.logger.exception(
@@ -137,7 +149,8 @@ class Invocation(ABC):
 
             job_response = build_error_job_response(exception,
                                                     message='Error when create provider or device',
-                                                    stage='while running the circuit on the device')
+                                                    stage='while running the circuit on the device',
+                                                    phase=RuntimePhase.PROVIDER_INVOCATION)
             update_job_metadata(job_response, self.callback_dict.get(
                     InvocationStep.EXECUTION).on_error, )
 
@@ -170,7 +183,8 @@ class Invocation(ABC):
                 InvocationStep.PREPARATION).on_start)
 
         try:
-            circuit = circuit_preparation_fn(self.input)
+            with phase(RuntimePhase.PREPROCESSING):
+                circuit = circuit_preparation_fn(self.input)
 
             if circuit is None:
                 self.logger.warning(
@@ -190,7 +204,8 @@ class Invocation(ABC):
 
             job_response = build_error_job_response(exception, job_response,
                                                     message='Error when prepare circuit',
-                                                    stage='while preparing the circuit')
+                                                    stage='while preparing the circuit',
+                                                    phase=RuntimePhase.PREPROCESSING)
 
             update_job_metadata(job_response, self.callback_dict.get(
                     InvocationStep.PREPARATION).on_error)

{quapp_common-0.0.13.dev9 → quapp_common-0.0.14.dev1}/quapp_common/component/backend/job_fetcher.py

@@ -16,6 +16,7 @@ from ...data.response.custom_header import CustomHeader
 from ...data.response.job_response import JobResponse
 from ...enum.invocation_step import InvocationStep
 from ...enum.media_type import MediaType
+from ...enum.runtime_phase import RuntimePhase
 from ...enum.status.job_status import JobStatus
 from ...enum.status.status_code import StatusCode
 from ...util.json_parser_utils import parse
@@ -135,7 +136,8 @@ class JobFetcher(ABC):
                     exception, job_response,
                     message='Error when fetching job with provider_job_id {0}'.format(
                             self.provider_job_id),
-                    stage='while fetching the job result from the provider')
+                    stage='while fetching the job result from the provider',
+                    phase=RuntimePhase.POLLING)
             update_job_metadata(job_response, self.callback_urls[
                 InvocationStep.EXECUTION].on_error)
 
@@ -213,7 +215,8 @@ class JobFetcher(ABC):
             job_response = build_error_job_response(
                     exception, job_response,
                     message='Error when analyzing job result',
-                    stage='while analysing the job result')
+                    stage='while analysing the job result',
+                    phase=RuntimePhase.ANALYSIS)
 
             update_job_metadata(job_response, callback_url.on_error)
             return None

{quapp_common-0.0.13.dev9 → quapp_common-0.0.14.dev1}/quapp_common/component/backend/job_fetching.py

@@ -17,6 +17,7 @@ from ...data.response.custom_header import CustomHeader
 from ...data.response.job_response import JobResponse
 from ...enum.invocation_step import InvocationStep
 from ...enum.media_type import MediaType
+from ...enum.runtime_phase import RuntimePhase
 from ...enum.status.job_status import JobStatus
 from ...enum.status.status_code import StatusCode
 from ...util.json_parser_utils import parse
@@ -97,7 +98,8 @@ class JobFetching(ABC):
                     exception, job_response,
                     message='Exception when fetch job with provider_job_id {0}'.format(
                             self.provider_job_id),
-                    stage='while fetching the job result from the provider')
+                    stage='while fetching the job result from the provider',
+                    phase=RuntimePhase.POLLING)
 
             update_job_metadata(job_response, self.callback_dict.get(
                     InvocationStep.EXECUTION).on_error)
@@ -162,7 +164,8 @@ class JobFetching(ABC):
                     exception, job_response,
                     message='Exception when analyst job result with provider_job_id {0}'.format(
                             self.provider_job_id),
-                    stage='while analysing the job result')
+                    stage='while analysing the job result',
+                    phase=RuntimePhase.ANALYSIS)
 
             update_job_metadata(job_response, callback_url.on_error)
 

quapp_common-0.0.14.dev1/quapp_common/config/log_context.py

@@ -0,0 +1,186 @@
+#  Quapp Platform Project
+#  log_context.py
+#  Copyright © CITYNOW Co. Ltd. All rights reserved.
+
+"""Per-job logging context.
+
+Vì sao cần: hiện tại mỗi nơi phải tự truyền ``job_id`` vào ``job_logger()``, và
+rất nhiều nơi quên -- ``Device.__init__``, ``Provider``, ``DeviceSelection``,
+các ``*Factory`` đều dùng ``logger.bind(context='...')`` hoặc gọi
+``job_logger()`` không tham số, nên log của chúng rơi vào context
+``"QuappLibs"`` và không gắn được vào job nào trong Job Log UI.
+
+Cách xử lý: bind context MỘT lần ở đầu request vào ``contextvars``. Mọi log sau
+đó -- kể cả log của thư viện bên thứ ba đi qua ``InterceptHandler`` -- tự có đủ
+field ``job_id`` / ``trace_id`` / ``sdk`` / ``provider`` / ``device``.
+
+Lưu ý về thread: ``contextvars`` KHÔNG tự propagate qua
+``ThreadPoolExecutor.submit()``. ``circuit_running_pool`` được dùng cho analysis
+và finalization, nên hai phase đó sẽ mất context nếu pool không copy context --
+xem ``thread_config.ContextAwareThreadPoolExecutor`` (Phase 1).
+"""
+
+import contextvars
+import time
+import uuid
+from contextlib import contextmanager
+
+from loguru import logger
+
+from ..enum.runtime_phase import RuntimePhase
+
+JOB_ID = 'job_id'
+TRACE_ID = 'trace_id'
+
+_CONTEXT_KEYS = (JOB_ID, TRACE_ID, 'sdk', 'provider', 'device',
+                 'provider_job_id')
+
+_JOB_CONTEXT: contextvars.ContextVar[dict] = contextvars.ContextVar(
+        'quapp_job_context', default={})
+
+_PHASE: contextvars.ContextVar['RuntimePhase | None'] = contextvars.ContextVar(
+        'quapp_phase', default=None)
+
+# Phase mà exception thoát ra gần nhất.
+#
+# Cần biến riêng vì `phase()` reset _PHASE trong `finally`, mà khối `except` xử
+# lý lỗi hầu như luôn nằm NGOÀI khối `with phase(...)`:
+#
+#     try:
+#         with phase(RuntimePhase.COMPILATION):
+#             transpile(...)
+#     except Exception:            # <- _PHASE đã là None ở đây
+#         build_error_job_response(...)
+#
+# Không có biến này thì mọi ErrorReport đều có phase=None và fallback theo phase
+# không bao giờ chạy.
+_FAILED_PHASE: contextvars.ContextVar[
+    'RuntimePhase | None'] = contextvars.ContextVar(
+        'quapp_failed_phase', default=None)
+
+
+def bind_job(job_id: str = None, *, sdk=None, provider=None, device=None,
+             provider_job_id=None, trace_id=None):
+    """Khởi tạo context cho một job và trả về logger đã bind.
+
+    Gọi một lần càng sớm càng tốt -- ``Handler.__init__`` hoặc ``index.py``.
+
+    @param job_id: id job phía Quapp backend
+    @param trace_id: tự sinh nếu không truyền; dùng để join Function Log <-> Job Log
+    @return: logger đã bind toàn bộ context
+    """
+    context = {JOB_ID          : job_id,
+               TRACE_ID        : trace_id or uuid.uuid4().hex[:16],
+               'sdk'           : sdk,
+               'provider'      : provider,
+               'device'        : device,
+               'provider_job_id': provider_job_id}
+    _JOB_CONTEXT.set(context)
+    _FAILED_PHASE.set(None)
+    return logger.bind(**context)
+
+
+def enrich_job_context(**fields):
+    """Bổ sung field khi biết thêm thông tin (device_name sau device selection,
+    provider_job_id sau khi submit...). Chỉ nhận các key trong _CONTEXT_KEYS.
+
+    @return: logger đã bind context mới
+    """
+    context = dict(_JOB_CONTEXT.get())
+    context.update(
+            {key: value for key, value in fields.items() if key in _CONTEXT_KEYS})
+    _JOB_CONTEXT.set(context)
+    return logger.bind(**context)
+
+
+def job_context() -> dict:
+    """Snapshot context hiện tại. Trả về dict rỗng nếu chưa bind."""
+    return dict(_JOB_CONTEXT.get())
+
+
+def current_job_id() -> str | None:
+    return _JOB_CONTEXT.get().get(JOB_ID)
+
+
+def trace_id() -> str | None:
+    return _JOB_CONTEXT.get().get(TRACE_ID)
+
+
+def current_phase():
+    """RuntimePhase đang mở, hoặc None."""
+    return _PHASE.get()
+
+
+def failed_phase():
+    """Phase mà exception thoát ra gần nhất trong job này, hoặc None."""
+    return _FAILED_PHASE.get()
+
+
+def effective_phase():
+    """Phase dùng để phân loại lỗi: phase đang mở, nếu không thì phase vừa fail.
+
+    Đây là hàm mà đường báo lỗi nên gọi -- khối `except` gần như luôn nằm ngoài
+    `with phase(...)`, nên `current_phase()` một mình sẽ trả None.
+    """
+    return _PHASE.get() or _FAILED_PHASE.get()
+
+
+def current_phase_value():
+    """Giá trị str của phase đang mở, để bind vào log."""
+    phase = _PHASE.get()
+    return phase.value if phase is not None else None
+
+
+@contextmanager
+def phase(runtime_phase: RuntimePhase):
+    """Đánh dấu một runtime phase.
+
+    Làm ba việc cùng lúc:
+
+    1. gán ``phase`` cho mọi log bên trong, kể cả log của thư viện bên thứ ba đi
+       qua ``InterceptHandler``;
+    2. phát event ``phase_start`` / ``phase_end`` / ``phase_failed`` kèm
+       ``duration_ms`` -- đây chính là dữ liệu để UI vẽ timeline và chỉ ra job
+       chết ở bước nào;
+    3. cung cấp phase cho classifier khi exception bay ra, mà không nơi nào phải
+       truyền tay.
+
+    Phase lồng nhau được: phase con khôi phục lại phase cha khi thoát.
+
+    @return: logger đã bind context + phase
+    """
+    token = _PHASE.set(runtime_phase)
+    bound = logger.bind(**_JOB_CONTEXT.get(), phase=runtime_phase.value)
+    started = time.perf_counter()
+    bound.bind(event='phase_start').info(f'{runtime_phase.value} started')
+
+    try:
+        yield bound
+    except BaseException:
+        # Ghi lại để khối except bên ngoài -- nơi _PHASE đã bị reset -- vẫn biết
+        # lỗi thoát ra từ phase nào.
+        _FAILED_PHASE.set(runtime_phase)
+        elapsed = _elapsed_ms(started)
+        # WARNING chứ không phải DEBUG: đây là mốc timeline, phải thấy được khi
+        # chạy ở LOG_LEVEL=INFO. Không kèm traceback vì build_error_job_response
+        # sẽ log exception đầy đủ ngay sau đó -- tránh in stack hai lần.
+        bound.bind(event='phase_failed', duration_ms=elapsed).warning(
+                f'{runtime_phase.value} failed after {elapsed} ms')
+        raise
+    else:
+        elapsed = _elapsed_ms(started)
+        bound.bind(event='phase_end', duration_ms=elapsed).info(
+                f'{runtime_phase.value} completed in {elapsed} ms')
+    finally:
+        _PHASE.reset(token)
+
+
+def _elapsed_ms(started: float) -> float:
+    return round((time.perf_counter() - started) * 1000, 2)
+
+
+def reset() -> None:
+    """Xoá context. Chủ yếu dùng trong test."""
+    _JOB_CONTEXT.set({})
+    _PHASE.set(None)
+    _FAILED_PHASE.set(None)

{quapp_common-0.0.13.dev9 → quapp_common-0.0.14.dev1}/quapp_common/config/logging_config.py

@@ -90,8 +90,35 @@ def redact(text) -> str:
 EXC_TEXT = '_exc_text'
 
 
+def _inject_job_context(record) -> None:
+    """Bổ sung job context vào record nếu chưa có.
+
+    Cần thiết vì không phải log nào cũng đi qua ``job_logger()``. Có ba đường
+    vào và cả ba phải có context:
+
+    - ``job_logger()`` -- đã bind sẵn, không đụng tới;
+    - stdlib ``logging`` qua ``InterceptHandler`` -- handler tự bind;
+    - **raw loguru** ``from quapp_common.config.logging_config import logger`` --
+      đường này 10 template và nhiều module trong lib đang dùng
+      (``logger.bind(context='Provider')``, ``dispatcher``, ``bridge``...), và
+      ``extra`` của nó không có job_id.
+
+    Đọc contextvars ở đây (thời điểm emit) thay vì lúc lấy logger, nên đúng cả
+    khi logger là biến module-level được tạo một lần lúc import.
+    """
+    from .log_context import current_phase_value, job_context
+
+    extra = record['extra']
+    for key, value in job_context().items():
+        if value is not None and extra.get(key) is None:
+            extra[key] = value
+
+    if extra.get('phase') is None:
+        extra['phase'] = current_phase_value()
+
+
 def _prepare_record(record) -> bool:
-    """loguru filter: mask message và pre-format traceback.
+    """loguru filter: bổ sung context, mask message và pre-format traceback.
 
     Filter chạy ở process gọi log, TRƯỚC khi record được đưa vào queue của
     ``enqueue=True``. Đây là chỗ duy nhất còn nhìn thấy traceback object thật --
@@ -100,6 +127,7 @@ def _prepare_record(record) -> bool:
 
     Trả True để giữ record.
     """
+    _inject_job_context(record)
     record['message'] = redact(record['message'])
 
     exception = record['exception']
@@ -191,7 +219,7 @@ class InterceptHandler(logging.Handler):
     """
 
     def emit(self, record: logging.LogRecord) -> None:
-        from .log_context import current_phase, job_context
+        from .log_context import current_phase_value, job_context
 
         try:
             level = logger.level(record.levelname).name
@@ -209,7 +237,7 @@ class InterceptHandler(logging.Handler):
             depth += 1
 
         logger.opt(depth=depth, exception=record.exc_info).bind(
-                **job_context(), phase=current_phase(),
+                **job_context(), phase=current_phase_value(),
                 stdlib_logger=record.name).log(level, record.getMessage())
 
 
@@ -264,13 +292,13 @@ def job_logger(job_id: str = None):
     Khác biệt so với trước: khi không truyền ``job_id``, lấy context đã bind bởi
     ``bind_job()`` thay vì rơi về ``"QuappLibs"``.
     """
-    from .log_context import current_phase, job_context
+    from .log_context import current_phase_value, job_context
 
     context = job_context()
     if job_id:
         context = {**context, 'job_id': job_id}
 
-    return logger.bind(**context, phase=current_phase())
+    return logger.bind(**context, phase=current_phase_value())
 
 
 configure_logging()

quapp_common-0.0.14.dev1/quapp_common/config/thread_config.py

@@ -0,0 +1,28 @@
+"""
+    QApp Platform Project thread_config.py Copyright © CITYNOW Co. Ltd. All rights reserved.
+"""
+import contextvars
+from concurrent.futures import ThreadPoolExecutor
+
+
+class ContextAwareThreadPoolExecutor(ThreadPoolExecutor):
+    """ThreadPoolExecutor giữ lại contextvars của caller.
+
+    ``ThreadPoolExecutor.submit()`` KHÔNG copy context (khác ``asyncio.to_thread``
+    và ``starlette.run_in_threadpool``). Cả ``JobFetcher._handle_successful_job``
+    lẫn ``JobFetching.fetch`` đều submit phần analysis + finalization vào
+    ``circuit_running_pool``, nên nếu không copy context thì toàn bộ log của hai
+    phase đó mất ``job_id`` / ``trace_id`` / ``phase`` và rơi về bucket
+    "QuappLibs".
+    """
+
+    def submit(self, fn, /, *args, **kwargs):
+        return super().submit(contextvars.copy_context().run, fn, *args,
+                              **kwargs)
+
+
+circuit_exporting_pool = ContextAwareThreadPoolExecutor(
+        max_workers=10, thread_name_prefix='circuit-exporting-pool-')
+
+circuit_running_pool = ContextAwareThreadPoolExecutor(
+        max_workers=20, thread_name_prefix='circuit-running-pool-')