diff --git a/docs/api-usage.rst b/docs/api-usage.rst index 2e7f5c681..a77b4e744 100644 --- a/docs/api-usage.rst +++ b/docs/api-usage.rst @@ -406,6 +406,27 @@ user. For example: p = gl.projects.create({'name': 'awesome_project'}, sudo='user1') +Logging +======= + +To enable debug logging from the underlying ``requests`` and ``http.client`` calls, +you can use ``enable_debug()`` on your ``Gitlab`` instance. For example: + +.. code-block:: python + + import os + import gitlab + + gl = gitlab.Gitlab(private_token=os.getenv("GITLAB_TOKEN")) + gl.enable_debug() + +By default, python-gitlab will mask the token used for authentication in logging output. +If you'd like to debug credentials sent to the API, you can disable masking explicitly: + +.. code-block:: python + + gl.enable_debug(mask_credentials=False) + .. _object_attributes: Attributes in updated objects diff --git a/gitlab/client.py b/gitlab/client.py index 7493e380c..e2586ad80 100644 --- a/gitlab/client.py +++ b/gitlab/client.py @@ -517,18 +517,39 @@ def _set_auth_info(self) -> None: self.http_username, self.http_password ) - @staticmethod - def enable_debug() -> None: + def enable_debug(self, mask_credentials: bool = True) -> None: import logging - from http.client import HTTPConnection # noqa + from http import client - HTTPConnection.debuglevel = 1 + client.HTTPConnection.debuglevel = 1 logging.basicConfig() - logging.getLogger().setLevel(logging.DEBUG) + logger = logging.getLogger() + logger.setLevel(logging.DEBUG) + + httpclient_log = logging.getLogger("http.client") + httpclient_log.propagate = True + httpclient_log.setLevel(logging.DEBUG) + requests_log = logging.getLogger("requests.packages.urllib3") requests_log.setLevel(logging.DEBUG) requests_log.propagate = True + # shadow http.client prints to log() + # https://stackoverflow.com/a/16337639 + def print_as_log(*args: Any) -> None: + httpclient_log.log(logging.DEBUG, " ".join(args)) + + setattr(client, "print", print_as_log) + + if not mask_credentials: + return + + token = self.private_token or self.oauth_token or self.job_token + handler = logging.StreamHandler() + handler.setFormatter(utils.MaskingFormatter(masked=token)) + logger.handlers.clear() + logger.addHandler(handler) + def _get_session_opts(self) -> Dict[str, Any]: return { "headers": self.headers.copy(), diff --git a/gitlab/utils.py b/gitlab/utils.py index 5170b18d7..51c2a3585 100644 --- a/gitlab/utils.py +++ b/gitlab/utils.py @@ -1,9 +1,10 @@ import email.message +import logging import pathlib import traceback import urllib.parse import warnings -from typing import Any, Callable, Dict, Iterator, Optional, Tuple, Type, Union +from typing import Any, Callable, Dict, Iterator, Literal, Optional, Tuple, Type, Union import requests @@ -22,6 +23,31 @@ def get_content_type(content_type: Optional[str]) -> str: return message.get_content_type() +class MaskingFormatter(logging.Formatter): + """A logging formatter that can mask credentials""" + + def __init__( + self, + fmt: Optional[str] = logging.BASIC_FORMAT, + datefmt: Optional[str] = None, + style: Literal["%", "{", "$"] = "%", + validate: bool = True, + masked: Optional[str] = None, + ) -> None: + super().__init__(fmt, datefmt, style, validate) + self.masked = masked + + def _filter(self, entry: str) -> str: + if not self.masked: + return entry + + return entry.replace(self.masked, "[MASKED]") + + def format(self, record: logging.LogRecord) -> str: + original = logging.Formatter.format(self, record) + return self._filter(original) + + def response_content( response: requests.Response, streamed: bool,