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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: quapp-common
-Version: 0.0.13.dev9
+Version: 0.0.14.dev2
 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,119 @@ Notes:
 
 ## Recently Changes Highlights
 
-### v0.0.14.dev1 — Error logging & observability (Phase 0)
+### v0.0.14.dev2 — Fix: log lỗi bị nhân đôi
+
+- **Fix**: mỗi lần lỗi phát **hai** dòng ERROR cùng `event=job_failed`, mỗi dòng
+  kèm một traceback riêng. Nguyên nhân: `build_error_job_response()` (thêm ở
+  `0.0.13.dev9`) tự phát một dòng log tập trung, nhưng 10 call-site vẫn giữ
+  `self.logger.exception(...)` của chúng.
+
+  Ngoài việc làm ồn Function Log và nhân đôi lượng traceback, nó **làm sai metric
+  nếu backend đếm `event=job_failed`** để tính tỉ lệ job thất bại.
+
+  Đã gỡ log ở 10 call-site trong `device.py`, `custom_device.py`,
+  `invocation.py` (×3), `job_fetcher.py` (×2), `job_fetching.py` (×2),
+  `post_processing_task.py`. Dòng log tập trung mang nhiều thông tin hơn bản bị
+  gỡ: `event` / `category` / `error_code` / `phase` + full traceback.
+
+  `phase_failed` (WARNING, mốc timeline) là event khác, không bị tính là trùng.
+
+- **Fix (security)**: credential lọt vào log text qua **hai đường** mà
+  `redact()` không chặn được:
+
+  1. `loguru diagnose=True` (default) in giá trị **biến cục bộ** trong traceback
+     dưới dạng `└ 'value'`. Không có tên key nên `redact()` — vốn match
+     `key: value` — không mask. Token provider nằm trong biến cục bộ lọt nguyên.
+     Đã set `diagnose=False` cho sink text (`backtrace=True` vẫn giữ: nó mở rộng
+     call chain nhưng không in giá trị).
+  2. Placeholder `{exception}` được loguru render **trực tiếp từ exception
+     object**, không đi qua filter. Secret nằm trong `str(exception)` — ví dụ
+     response body của provider bị nhét vào `ValueError` — lọt nguyên. Sink text
+     nay append traceback đã redact ở `extra[_exc_text]` thay cho placeholder đó.
+
+  Sink JSON không bị ảnh hưởng: nó đã dùng `_exc_text` và `diagnose=False`.
+
+- **Docs**: ghi rõ trong docstring nên chọn `QUAPP_LOG_FORMAT` nào. Với
+  Grafana/Loki phải dùng `json`: ở chế độ `text`, traceback là các dòng **riêng
+  không có prefix** `[ConsoleJobLog][<job_id>]`, nên filter theo job_id sẽ mất
+  toàn bộ stack. `both` ghi mỗi record hai lần — chỉ dùng khi debug.
+
+- **Test**: thêm `tests/test_log_secret_leak.py` — 5 case, test qua sink THẬT do
+  `configure_logging()` tạo (không introspect internals). Có một case khoá lại
+  hành vi `diagnose=True` của loguru, để nếu upstream đổi thì ta biết.
+
+- **Test**: thêm `tests/test_error_log_dedupe.py` — khoá hồi quy ở hai mức: đếm
+  số dòng `job_failed` khi chạy thật, **và** quét source để bắt trường hợp ai đó
+  thêm lại `logger.exception()` ngay trước `build_error_job_response()`.
+
+  Kèm test cho trường hợp **nhiều job đồng thời**: 4 job qua
+  `run_in_threadpool` + `circuit_running_pool` phải có số dòng log đều nhau,
+  không job nào nhận log của job khác, và `phase` giữ được khi đi vào thread
+  pool.
+
+### 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.dev2}/README.md

@@ -73,7 +73,119 @@ Notes:
 
 ## Recently Changes Highlights
 
-### v0.0.14.dev1 — Error logging & observability (Phase 0)
+### v0.0.14.dev2 — Fix: log lỗi bị nhân đôi
+
+- **Fix**: mỗi lần lỗi phát **hai** dòng ERROR cùng `event=job_failed`, mỗi dòng
+  kèm một traceback riêng. Nguyên nhân: `build_error_job_response()` (thêm ở
+  `0.0.13.dev9`) tự phát một dòng log tập trung, nhưng 10 call-site vẫn giữ
+  `self.logger.exception(...)` của chúng.
+
+  Ngoài việc làm ồn Function Log và nhân đôi lượng traceback, nó **làm sai metric
+  nếu backend đếm `event=job_failed`** để tính tỉ lệ job thất bại.
+
+  Đã gỡ log ở 10 call-site trong `device.py`, `custom_device.py`,
+  `invocation.py` (×3), `job_fetcher.py` (×2), `job_fetching.py` (×2),
+  `post_processing_task.py`. Dòng log tập trung mang nhiều thông tin hơn bản bị
+  gỡ: `event` / `category` / `error_code` / `phase` + full traceback.
+
+  `phase_failed` (WARNING, mốc timeline) là event khác, không bị tính là trùng.
+
+- **Fix (security)**: credential lọt vào log text qua **hai đường** mà
+  `redact()` không chặn được:
+
+  1. `loguru diagnose=True` (default) in giá trị **biến cục bộ** trong traceback
+     dưới dạng `└ 'value'`. Không có tên key nên `redact()` — vốn match
+     `key: value` — không mask. Token provider nằm trong biến cục bộ lọt nguyên.
+     Đã set `diagnose=False` cho sink text (`backtrace=True` vẫn giữ: nó mở rộng
+     call chain nhưng không in giá trị).
+  2. Placeholder `{exception}` được loguru render **trực tiếp từ exception
+     object**, không đi qua filter. Secret nằm trong `str(exception)` — ví dụ
+     response body của provider bị nhét vào `ValueError` — lọt nguyên. Sink text
+     nay append traceback đã redact ở `extra[_exc_text]` thay cho placeholder đó.
+
+  Sink JSON không bị ảnh hưởng: nó đã dùng `_exc_text` và `diagnose=False`.
+
+- **Docs**: ghi rõ trong docstring nên chọn `QUAPP_LOG_FORMAT` nào. Với
+  Grafana/Loki phải dùng `json`: ở chế độ `text`, traceback là các dòng **riêng
+  không có prefix** `[ConsoleJobLog][<job_id>]`, nên filter theo job_id sẽ mất
+  toàn bộ stack. `both` ghi mỗi record hai lần — chỉ dùng khi debug.
+
+- **Test**: thêm `tests/test_log_secret_leak.py` — 5 case, test qua sink THẬT do
+  `configure_logging()` tạo (không introspect internals). Có một case khoá lại
+  hành vi `diagnose=True` của loguru, để nếu upstream đổi thì ta biết.
+
+- **Test**: thêm `tests/test_error_log_dedupe.py` — khoá hồi quy ở hai mức: đếm
+  số dòng `job_failed` khi chạy thật, **và** quét source để bắt trường hợp ai đó
+  thêm lại `logger.exception()` ngay trước `build_error_job_response()`.
+
+  Kèm test cho trường hợp **nhiều job đồng thời**: 4 job qua
+  `run_in_threadpool` + `circuit_running_pool` phải có số dòng log đều nhau,
+  không job nào nhận log của job khác, và `phase` giữ được khi đi vào thread
+  pool.
+
+### 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.dev2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "quapp-common"
-version = "0.0.13.dev9"
+version = "0.0.14.dev2"
 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.dev2}/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
 
@@ -44,13 +45,11 @@ class PostProcessingTask(AsyncTask):
             update_job_metadata(job_response, self.promise.callback_url.on_done)
 
         except Exception as exception:
-            self.logger.bind(event='job_failed').exception(
-                    f"Post-processing failed: {exception}")
-
             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.dev2}/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,19 +84,20 @@ 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}")
 
         except Exception as exception:
-            self.logger.exception(
-                f"Error when prepare backend data: {exception}",
-                exc_info=True)
-
             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,19 +128,21 @@ 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(
-                    f"Exception when create provider or device: {exception}",
-                    exc_info=True)
-
             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 +175,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(
@@ -185,12 +191,10 @@ class Invocation(ABC):
             return circuit
 
         except Exception as exception:
-            self.logger.exception(f'Error when prepare circuit: {exception}',
-                                  exc_info=True)
-
             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.dev2}/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
@@ -127,15 +128,12 @@ class JobFetcher(ABC):
                 job_response.status_code = StatusCode.POLLING
 
         except Exception as exception:
-            self.logger.exception(
-                    f"Exception during job fetch for provider_job_id {self.provider_job_id}: {exception}",
-                    exc_info=True)
-
             job_response = build_error_job_response(
                     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)
 
@@ -207,13 +205,12 @@ class JobFetcher(ABC):
             return job_response
 
         except Exception as exception:
-            self.logger.exception(f"Exception during analysis: {exception}",
-                              exc_info=True)
             from ...util.response_utils import build_error_job_response
             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.dev2}/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
@@ -89,15 +90,12 @@ class JobFetching(ABC):
                 job_response.status_code = StatusCode.POLLING
 
         except Exception as exception:
-            self.logger.bind(event='job_failed').exception(
-                    "Exception when fetch job with provider_job_id {0}: {1}".format(
-                            self.provider_job_id, str(exception)))
-
             job_response = build_error_job_response(
                     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)
@@ -154,15 +152,12 @@ class JobFetching(ABC):
             return job_response
 
         except Exception as exception:
-            self.logger.exception(
-                    "Exception when analyst job result with provider_job_id {0}: {1}".format(
-                            self.provider_job_id, str(exception)))
-
             job_response = build_error_job_response(
                     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.dev2/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)