Различия

Показаны различия между двумя версиями страницы.

--- start [2025/05/27 20:15] – admin
+++ start [2025/05/28 19:15] (текущий) – admin
@@ Строка 4: / Строка 4: @@
 Его можно найти в интерфейсе редактирования проекта в поле **Токен**.
 API_URL = https://err-scout.ru/api
+====== Рекомендуемый способ передачи ошибок ======
-===== Передаваемые поля =====
+В этом разделе представлен рекомендуемый способ автоматической отправки ошибок в API `https://err-scout.ru/api` для внешних Python-приложений.
-Для отправки ошибки необходимо передать следующие поля в параметре `params` метода `Error.create`:
+Используется декоратор `@detailed_exception_logger`, который автоматически:
+  * перехватывает исключения,
+  * извлекает стек вызовов и контекст исполнения,
+  * подготавливает структуру ошибки по формату `Error.create`,
+  * и отправляет её в API с авторизацией через токен проекта.
-  * **error_type** — тип исключения (например, `ValueError`)
+При возникновении исключения, декоратор автоматически формирует объект `error_data`, содержащий:
+  * **error_type** — тип исключения
   * **error_message** — текст ошибки
-  * **timestamp** — время возникновения ошибки в формате ISO 8601 (UTC)
+  * **timestamp** — время в формате ISO 8601
-  * **environment** — окружение (например, `production`, `local`)
+  * **environment** — окружение (по умолчанию: `local`)
-  * **release** — версия релиза (например, `v1.2.3`)
+  * **release** — версия приложения (по умолчанию: `unversioned`)
-  * **platform** — операционная система (например, `linux`, `windows`)
+  * **platform** — ОС
-  * **language_version** — версия языка (например, `3.12`)
+  * **language_version** — версия Python
-  * **user_id** — идентификатор пользователя (опционально)
+  * **user_id** — идентификатор пользователя (можно настроить)
   * **user_email** — email пользователя (опционально)
-  * **request_data** — данные запроса, если доступны (например, параметры запроса, путь и т.д.)
+  * **request_data** — информация о контексте вызова
-  * **stack_trace** — список фреймов трассировки, где каждый элемент содержит:
+  * **stack_trace** — список фреймов с переменными
-    * **file** — путь к файлу
+  * **tags** — теги в виде пар ключ/значение
-    * **line** — номер строки
-    * **function** — имя функции
-    * **code** — строка кода
-    * **index** — индекс фрейма в стеке
-  * **tags** — список тегов в формате: `{ "key": "ключ", "value": "значение" }`
-===== Пример передачи ошибки =====
+===== Пример использования =====
 <code python>
-stack = traceback.extract_tb(e.__traceback__)
+@detailed_exception_logger
-stack_trace = [
+def divide(a, b):
-    {
+    return a / b
-        "file": frame.filename,
-        "line": frame.lineno,
-        "function": frame.name,
-        "code": frame.line,
-        "index": i
-    } for i, frame in enumerate(stack)
-]
-error_data = {
+divide(10, 0)
-    "error_type": type(e).__name__,
+</code>
-    "error_message": str(e),
-    "timestamp": datetime.utcnow().isoformat(),
+===== Код декоратора =====
-    "environment": "local",
-    "release": "test-1.0",
+<code python>
-    "platform": "linux",
+import json
-    "language_version": "3.12",
+import traceback
-    "user_id": "global-handler",
+import sys
-    "user_email": "handler@example.com",
+import os
-    "request_data": {},
+import inspect
-    "stack_trace": stack_trace,
+from datetime import datetime
-    "tags": [{"key": "source", "value": "global-handler"}]
+from functools import wraps
-}
+import requests
+from config import API_URL, AUTH_TOKEN, ENVIRONMENT, RELEASE
 def send_error_to_api(error_data: dict):
     headers = {
         'Content-Type': 'application/json',
-        'Authorization': 'Ваш токен проекта'
+        'Authorization': AUTH_TOKEN
     }
     payload = {
@@ Строка 70: / Строка 67: @@
     response.raise_for_status()
     return response.json()
+def detailed_exception_logger(func):
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        try:
+            return func(*args, **kwargs)
+        except Exception as e:
+            exc_type, exc_value, exc_tb = sys.exc_info()
+            timestamp = datetime.utcnow().isoformat()
+            stack_trace = []
+            tb = exc_tb
+            index = 0
+            while tb:
+                frame = tb.tb_frame
+                lineno = tb.tb_lineno
+                filename = frame.f_code.co_filename
+                func_name = frame.f_code.co_name
+                try:
+                    with open(filename, 'r', encoding='utf-8') as f:
+                        lines = f.readlines()
+                        code_line = lines[lineno - 1].strip() if lineno <= len(lines) else ""
+                except Exception:
+                    code_line = ""
+                stack_trace.append({
+                    "file": filename,
+                    "line": lineno,
+                    "function": func_name,
+                    "code": code_line,
+                    "index": index
+                })
+                tb = tb.tb_next
+                index += 1
+            error_data = {
+                "error_type": exc_type.__name__,
+                "error_message": str(exc_value),
+                "timestamp": timestamp,
+                "environment": ENVIRONMENT,
+                "release": RELEASE,
+                "platform": sys.platform,
+                "language_version": sys.version.split()[0],
+                "user_id": "auto-reporter",
+                "user_email": "",
+                "request_data": {
+                    "function": func.__name__,
+                    "args": [repr(a) for a in args],
+                    "kwargs": {k: repr(v) for k, v in kwargs.items()}
+                },
+                "stack_trace": stack_trace,
+                "tags": [
+                    {"key": "module", "value": func.__module__},
+                    {"key": "pid", "value": str(os.getpid())},
+                    {"key": "cwd", "value": os.getcwd()}
+                ]
+            }
+            try:
+                send_error_to_api(error_data)
+            except Exception as api_error:
+                print(f"[error-scout] Failed to send error: {api_error}")
+                print(json.dumps(error_data, indent=2))
+            raise
+    return wrapper
 </code>
+===== Дополнительно =====
+  * При необходимости можно расширить `request_data` или `tags` дополнительными параметрами