Настройка отладки

Возврат отладочной информации в ответах REST API

По умолчанию сервер не добавляет детали ошибок в тело ответа, чтобы избежать раскрытия специфичной информации экземпляра конечным пользователям.

Вы можете изменить это, установив:

$ export DATA_RENTGEN__SERVER__DEBUG=False
$ # запуск REST API сервера
$ curl -XPOST http://localhost:8000/failing/endpoint ...
{
    "error": {
        "code": "unknown",
        "message": "Получено необработанное исключение. Пожалуйста, обратитесь в службу поддержки",
        "details": null,
    },
}

$ export DATA_RENTGEN__SERVER__DEBUG=True
$ # запуск REST API сервера
$ curl -XPOST http://localhost:8000/failing/endpoint ...
Traceback (most recent call last):
File ".../uvicorn/protocols/http/h11_impl.py", line 408, in run_asgi
    result = await app(  # type: ignore[func-returns-value]
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File ".../site-packages/uvicorn/middleware/proxy_headers.py", line 84, in __call__
    return await self.app(scope, receive, send)

Предупреждение

Это только для среды разработки. НЕ используйте в продакшене!

Вывод отладочных логов в бэкенде

См. Настройка логирования, но замените уровень логирования INFO на DEBUG.

Заполнение заголовка X-Request-ID в бэкенде

Сервер может добавлять заголовок X-Request-ID к ответам, что позволяет сопоставить запрос клиента с ответом бэкенда.

Это делается middleware request_id, который включен по умолчанию и может быть настроен как описано ниже:

Bases: BaseModel

X-Request-ID Middleware Settings.

See asgi-correlation-id <https://github.com/snok/asgi-correlation-id>_ documentation.

Examples

.. code-block:: bash

DATA_RENTGEN__SERVER__REQUEST_ID__ENABLED=True
DATA_RENTGEN__SERVER__REQUEST_ID__UPDATE_REQUEST_HEADER=True

Source code in data_rentgen/server/settings/request_id.py

class RequestIDSettings(BaseModel):
    """X-Request-ID Middleware Settings.

    See `asgi-correlation-id <https://github.com/snok/asgi-correlation-id>`_ documentation.

    Examples
    --------

    .. code-block:: bash

        DATA_RENTGEN__SERVER__REQUEST_ID__ENABLED=True
        DATA_RENTGEN__SERVER__REQUEST_ID__UPDATE_REQUEST_HEADER=True
    """

    enabled: bool = Field(default=True, description="Set to ``True`` to enable middleware")
    header_name: str = Field(
        default="X-Request-ID",
        description="Name of response header which is filled up with request ID value",
    )
    update_request_header: bool = Field(
        default=False,
        description=textwrap.dedent(
            """
            If ``False``, bypass header value from request to response as-is.

            If ``True``, always set new value of specific header.
            """,
        ),
    )

Вывод ID запроса в логи бэкенда

Это делается добавлением специфичного фильтра к обработчику логирования:

logging.yml

Результирующие логи выглядят так:

2023-12-18 17:14:11.711 uvicorn.access:498 [INFO] 018c15e97a068ae09484f8c25e2799dd 127.0.0.1:34884 - "GET /monitoring/ping HTTP/1.1" 200

Использование заголовка X-Request-ID в клиенте

Если клиент получил заголовок X-Request-ID от бэкенда, он выводится в логи с уровнем DEBUG:

>>> import logging
>>> logging.basicConfig(level=logging.DEBUG)
>>> client.ping()
DEBUG:urllib3.connectionpool:http://localhost:8000 "GET /monitoring/ping HTTP/1.1" 200 15
DEBUG:data_rentgen.client.base:Request ID: '018c15e97a068ae09484f8c25e2799dd'

Также, если ответ REST API был неуспешным, Request ID добавляется к сообщению исключения:

>>> client.get_namespace("unknown")
requests.exceptions.HTTPError: 404 Client Error: Not Found for url: http://localhost:8000/v1/namespaces/unknown
Request ID: '018c15eb80fa81a6b38c9eaa519cd322'

Заполнение заголовка X-Application-Version на стороне REST API

Сервер может добавлять заголовок X-Application-Version к ответам, что позволяет определить, какая версия бэкенда развернута.

Это делается middleware application_version, который включен по умолчанию и может быть настроен как описано ниже:

Bases: BaseModel

X-Application-Version Middleware Settings.

Examples

.. code-block:: bash

DATA_RENTGEN__SERVER__APPLICATION_VERSION__ENABLED=True
DATA_RENTGEN__SERVER__APPLICATION_VERSION__HEADER_NAME=X-Application-Version

Source code in data_rentgen/server/settings/application_version.py

class ApplicationVersionSettings(BaseModel):
    """X-Application-Version Middleware Settings.

    Examples
    --------

    .. code-block:: bash

        DATA_RENTGEN__SERVER__APPLICATION_VERSION__ENABLED=True
        DATA_RENTGEN__SERVER__APPLICATION_VERSION__HEADER_NAME=X-Application-Version
    """

    enabled: bool = Field(default=True, description="Set to ``True`` to enable middleware")
    header_name: str = Field(
        default="X-Application-Version",
        description="Name of response header which is filled up with application version number",
    )