aa-toolkit-log 0.1.0a1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- aa_log/__init__.py +5 -0
- aa_log/_format.py +107 -0
- aa_log/_redact.py +133 -0
- aa_log/_setup.py +178 -0
- aa_log/py.typed +0 -0
- aa_toolkit_log-0.1.0a1.dist-info/METADATA +128 -0
- aa_toolkit_log-0.1.0a1.dist-info/RECORD +9 -0
- aa_toolkit_log-0.1.0a1.dist-info/WHEEL +4 -0
- aa_toolkit_log-0.1.0a1.dist-info/licenses/LICENSE +21 -0
aa_log/__init__.py
ADDED
aa_log/_format.py
ADDED
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
"""How a log record looks on the way out."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import logging
|
|
5
|
+
from datetime import datetime
|
|
6
|
+
|
|
7
|
+
_LABELS = {
|
|
8
|
+
logging.DEBUG: "DEBUG",
|
|
9
|
+
logging.INFO: "INFO",
|
|
10
|
+
logging.WARNING: "WARN",
|
|
11
|
+
logging.ERROR: "ERROR",
|
|
12
|
+
logging.CRITICAL: "CRIT",
|
|
13
|
+
}
|
|
14
|
+
_LEVEL_WIDTH = 5
|
|
15
|
+
_LOGGER_WIDTH = 24
|
|
16
|
+
|
|
17
|
+
_YELLOW = "\x1b[33m"
|
|
18
|
+
_RED = "\x1b[31m"
|
|
19
|
+
_RESET = "\x1b[0m"
|
|
20
|
+
|
|
21
|
+
_ESCAPED_LINE_BREAKS = str.maketrans({0x85: r"\u0085", 0x2028: r"\u2028", 0x2029: r"\u2029"})
|
|
22
|
+
|
|
23
|
+
STANDARD_FIELDS = frozenset(vars(logging.makeLogRecord({}))) | {"message", "asctime"}
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _label(record: logging.LogRecord) -> str:
|
|
27
|
+
return _LABELS.get(record.levelno, record.levelname)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def extra(record: logging.LogRecord) -> dict[str, object]:
|
|
31
|
+
return {key: value for key, value in vars(record).items() if key not in STANDARD_FIELDS}
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def _text(value: object) -> str:
|
|
35
|
+
"""Turn a value into text, even one whose own ``__str__`` fails."""
|
|
36
|
+
try:
|
|
37
|
+
return str(value)
|
|
38
|
+
except Exception:
|
|
39
|
+
return f"<unprintable {type(value).__name__}>"
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _json_value(value: object) -> object:
|
|
43
|
+
"""Keep a value JSON can hold, and turn any other into text."""
|
|
44
|
+
try:
|
|
45
|
+
json.dumps(value, default=str, allow_nan=False)
|
|
46
|
+
except Exception:
|
|
47
|
+
return _text(value)
|
|
48
|
+
return value
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class _Formatter(logging.Formatter):
|
|
52
|
+
def _details(self, record: logging.LogRecord) -> str | None:
|
|
53
|
+
"""Return the error details and stack of a record, if it has any."""
|
|
54
|
+
parts = []
|
|
55
|
+
if record.exc_info:
|
|
56
|
+
parts.append(self.formatException(record.exc_info))
|
|
57
|
+
elif record.exc_text:
|
|
58
|
+
parts.append(record.exc_text)
|
|
59
|
+
if record.stack_info:
|
|
60
|
+
parts.append(self.formatStack(record.stack_info))
|
|
61
|
+
return "\n".join(parts) or None
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
class TextFormatter(_Formatter):
|
|
65
|
+
"""Lined-up columns of time, level, logger name and message, for a person."""
|
|
66
|
+
|
|
67
|
+
def __init__(self, *, color: bool) -> None:
|
|
68
|
+
super().__init__()
|
|
69
|
+
self._color = color
|
|
70
|
+
|
|
71
|
+
def _level(self, record: logging.LogRecord) -> str:
|
|
72
|
+
label = _label(record)
|
|
73
|
+
padding = " " * (_LEVEL_WIDTH - len(label))
|
|
74
|
+
if self._color and record.levelno >= logging.ERROR:
|
|
75
|
+
return f"{_RED}{label}{_RESET}{padding}"
|
|
76
|
+
if self._color and record.levelno >= logging.WARNING:
|
|
77
|
+
return f"{_YELLOW}{label}{_RESET}{padding}"
|
|
78
|
+
return f"{label}{padding}"
|
|
79
|
+
|
|
80
|
+
def format(self, record: logging.LogRecord) -> str:
|
|
81
|
+
pairs = [f"{key}={_text(value)}" for key, value in extra(record).items()]
|
|
82
|
+
text = " ".join([record.getMessage(), *pairs])
|
|
83
|
+
time = self.formatTime(record, "%H:%M:%S")
|
|
84
|
+
line = f"{time} {self._level(record)} {record.name:<{_LOGGER_WIDTH}} {text}"
|
|
85
|
+
details = self._details(record)
|
|
86
|
+
return f"{line}\n{details}" if details else line
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
class JsonFormatter(_Formatter):
|
|
90
|
+
"""One complete JSON object per record, on one line."""
|
|
91
|
+
|
|
92
|
+
def format(self, record: logging.LogRecord) -> str:
|
|
93
|
+
when = datetime.fromtimestamp(record.created).astimezone()
|
|
94
|
+
payload: dict[str, object] = {
|
|
95
|
+
"time": when.isoformat(timespec="milliseconds"),
|
|
96
|
+
"level": _label(record).lower(),
|
|
97
|
+
"logger": record.name,
|
|
98
|
+
"message": record.getMessage(),
|
|
99
|
+
}
|
|
100
|
+
details = self._details(record)
|
|
101
|
+
if details:
|
|
102
|
+
payload["exception"] = details
|
|
103
|
+
for key, value in extra(record).items():
|
|
104
|
+
payload.setdefault(key, _json_value(value))
|
|
105
|
+
return json.dumps(payload, ensure_ascii=False, default=_text).translate(
|
|
106
|
+
_ESCAPED_LINE_BREAKS
|
|
107
|
+
)
|
aa_log/_redact.py
ADDED
|
@@ -0,0 +1,133 @@
|
|
|
1
|
+
"""Cleaning each log record with the app's own function before it's formatted (ADR 0005)."""
|
|
2
|
+
|
|
3
|
+
import copy
|
|
4
|
+
import logging
|
|
5
|
+
from collections.abc import Callable, Mapping
|
|
6
|
+
|
|
7
|
+
from aa_log._format import STANDARD_FIELDS, extra
|
|
8
|
+
|
|
9
|
+
Redact = Callable[[dict[str, object]], object]
|
|
10
|
+
|
|
11
|
+
FAILED = "[REDACTION FAILED]"
|
|
12
|
+
_FIELDS = frozenset({"message", "exception", "stack", "extra"})
|
|
13
|
+
_TRACEBACKS = logging.Formatter()
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
class _WrongShape(Exception):
|
|
17
|
+
"""The redact function returned something other than the mapping it was given."""
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
def _exception(record: logging.LogRecord) -> str | None:
|
|
21
|
+
if record.exc_info:
|
|
22
|
+
return _TRACEBACKS.formatException(record.exc_info)
|
|
23
|
+
return record.exc_text
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def _text_or_none(value: object) -> str | None:
|
|
27
|
+
if value is None or isinstance(value, str):
|
|
28
|
+
return value
|
|
29
|
+
raise _WrongShape
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _detached(value: object, copies: dict[int, object]) -> object:
|
|
33
|
+
"""Copy the dicts, lists, sets and tuples in a value, and keep every other object as it is.
|
|
34
|
+
|
|
35
|
+
`copies` maps each container already copied to its copy, so shared and circular parts
|
|
36
|
+
stay that way.
|
|
37
|
+
"""
|
|
38
|
+
if id(value) in copies:
|
|
39
|
+
return copies[id(value)]
|
|
40
|
+
if isinstance(value, dict):
|
|
41
|
+
copied_dict = copies[id(value)] = copy.copy(value)
|
|
42
|
+
for key, item in value.items():
|
|
43
|
+
copied_dict[key] = _detached(item, copies)
|
|
44
|
+
return copied_dict
|
|
45
|
+
if isinstance(value, list):
|
|
46
|
+
copied_list = copies[id(value)] = copy.copy(value)
|
|
47
|
+
copied_list[:] = [_detached(item, copies) for item in value]
|
|
48
|
+
return copied_list
|
|
49
|
+
if isinstance(value, set):
|
|
50
|
+
copied_set = copies[id(value)] = copy.copy(value)
|
|
51
|
+
return copied_set
|
|
52
|
+
if isinstance(value, tuple):
|
|
53
|
+
items = [_detached(item, copies) for item in value]
|
|
54
|
+
if id(value) in copies:
|
|
55
|
+
return copies[id(value)]
|
|
56
|
+
unchanged = all(new is old for new, old in zip(items, value, strict=True))
|
|
57
|
+
copied_tuple = copies[id(value)] = value if unchanged else tuple.__new__(type(value), items)
|
|
58
|
+
return copied_tuple
|
|
59
|
+
return value
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def _checked(result: object) -> tuple[str, str | None, str | None, dict[str, object]]:
|
|
63
|
+
"""Return the fields of a redact result, or raise when it isn't the shape it was given."""
|
|
64
|
+
if not isinstance(result, Mapping) or set(result) != _FIELDS:
|
|
65
|
+
raise _WrongShape
|
|
66
|
+
message, extras = result["message"], result["extra"]
|
|
67
|
+
if not isinstance(message, str) or not isinstance(extras, Mapping):
|
|
68
|
+
raise _WrongShape
|
|
69
|
+
cleaned_extras: dict[str, object] = {}
|
|
70
|
+
for key, value in extras.items():
|
|
71
|
+
if not isinstance(key, str) or key in STANDARD_FIELDS:
|
|
72
|
+
raise _WrongShape
|
|
73
|
+
cleaned_extras[key] = value
|
|
74
|
+
return (
|
|
75
|
+
message,
|
|
76
|
+
_text_or_none(result["exception"]),
|
|
77
|
+
_text_or_none(result["stack"]),
|
|
78
|
+
cleaned_extras,
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _failed(record: logging.LogRecord) -> logging.LogRecord:
|
|
83
|
+
"""A record with only the time, level and logger of `record`, and FAILED as its message."""
|
|
84
|
+
failed = logging.makeLogRecord(
|
|
85
|
+
{"name": record.name, "levelno": record.levelno, "levelname": record.levelname}
|
|
86
|
+
)
|
|
87
|
+
failed.created, failed.msecs = record.created, record.msecs
|
|
88
|
+
failed.relativeCreated = record.relativeCreated
|
|
89
|
+
failed.msg = FAILED
|
|
90
|
+
return failed
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
class Redaction(logging.Filter):
|
|
94
|
+
"""A handler filter that passes on a redacted copy of each record, and never raises."""
|
|
95
|
+
|
|
96
|
+
def __init__(self, redact: Redact) -> None:
|
|
97
|
+
super().__init__()
|
|
98
|
+
self._redact = redact
|
|
99
|
+
self.let_through: list[logging.LogRecord] = []
|
|
100
|
+
|
|
101
|
+
def filter(self, record: logging.LogRecord) -> logging.LogRecord | bool:
|
|
102
|
+
if any(record is allowed for allowed in self.let_through):
|
|
103
|
+
return True
|
|
104
|
+
try:
|
|
105
|
+
return self._clean(record)
|
|
106
|
+
except Exception:
|
|
107
|
+
try:
|
|
108
|
+
return _failed(record)
|
|
109
|
+
except Exception:
|
|
110
|
+
return False
|
|
111
|
+
|
|
112
|
+
def _clean(self, record: logging.LogRecord) -> logging.LogRecord:
|
|
113
|
+
raw_extras = extra(record)
|
|
114
|
+
message, exception, stack, cleaned_extras = _checked(
|
|
115
|
+
self._redact(
|
|
116
|
+
{
|
|
117
|
+
"message": record.getMessage(),
|
|
118
|
+
"exception": _exception(record),
|
|
119
|
+
"stack": record.stack_info,
|
|
120
|
+
"extra": _detached(raw_extras, {}),
|
|
121
|
+
}
|
|
122
|
+
)
|
|
123
|
+
)
|
|
124
|
+
clean = copy.copy(record)
|
|
125
|
+
for key in raw_extras:
|
|
126
|
+
delattr(clean, key)
|
|
127
|
+
clean.msg = clean.message = message
|
|
128
|
+
clean.args = ()
|
|
129
|
+
clean.exc_info = None
|
|
130
|
+
clean.exc_text = exception
|
|
131
|
+
clean.stack_info = stack
|
|
132
|
+
vars(clean).update(cleaned_extras)
|
|
133
|
+
return clean
|
aa_log/_setup.py
ADDED
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
"""Turning logging on for an app."""
|
|
2
|
+
|
|
3
|
+
import contextlib
|
|
4
|
+
import logging
|
|
5
|
+
import os
|
|
6
|
+
import sys
|
|
7
|
+
from logging.handlers import RotatingFileHandler
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import TextIO
|
|
10
|
+
|
|
11
|
+
from aa_log._format import JsonFormatter, TextFormatter
|
|
12
|
+
from aa_log._redact import FAILED, Redact, Redaction
|
|
13
|
+
|
|
14
|
+
_LEVELS = {
|
|
15
|
+
"DEBUG": logging.DEBUG,
|
|
16
|
+
"INFO": logging.INFO,
|
|
17
|
+
"WARN": logging.WARNING,
|
|
18
|
+
"WARNING": logging.WARNING,
|
|
19
|
+
"ERROR": logging.ERROR,
|
|
20
|
+
"CRIT": logging.CRITICAL,
|
|
21
|
+
"CRITICAL": logging.CRITICAL,
|
|
22
|
+
}
|
|
23
|
+
_MAX_FILE_BYTES = 10 * 1024 * 1024
|
|
24
|
+
_OLD_FILES_KEPT = 3
|
|
25
|
+
_ENABLE_VIRTUAL_TERMINAL_PROCESSING = 0x0004
|
|
26
|
+
|
|
27
|
+
_installed: list[logging.Handler] = []
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def _env(name: str) -> str | None:
|
|
31
|
+
"""Return an environment variable, counting an empty one as not set."""
|
|
32
|
+
return os.environ.get(name, "").strip() or None
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _parse_level(value: int | str) -> int | None:
|
|
36
|
+
if isinstance(value, int):
|
|
37
|
+
return value
|
|
38
|
+
return _LEVELS.get(str(value).strip().upper())
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def _choose_level(level: int | str, problems: list[str]) -> int:
|
|
42
|
+
chosen = _parse_level(level)
|
|
43
|
+
if chosen is None:
|
|
44
|
+
problems.append(f"level={level!r} is not a log level, using INFO")
|
|
45
|
+
chosen = logging.INFO
|
|
46
|
+
value = _env("AA_LOG_LEVEL")
|
|
47
|
+
if value is None:
|
|
48
|
+
return chosen
|
|
49
|
+
from_env = _parse_level(value)
|
|
50
|
+
if from_env is None:
|
|
51
|
+
name = logging.getLevelName(chosen)
|
|
52
|
+
problems.append(f"AA_LOG_LEVEL is {value!r}, which is not a log level, using {name}")
|
|
53
|
+
return chosen
|
|
54
|
+
return from_env
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def _is_terminal(stream: TextIO) -> bool:
|
|
58
|
+
try:
|
|
59
|
+
return stream.isatty()
|
|
60
|
+
except AttributeError, ValueError: # no stderr at all, or a closed one
|
|
61
|
+
return False
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def _enable_color(stream: TextIO) -> None:
|
|
65
|
+
"""Make a Windows console act on color codes instead of printing them as text."""
|
|
66
|
+
if sys.platform != "win32":
|
|
67
|
+
return
|
|
68
|
+
import ctypes
|
|
69
|
+
import msvcrt
|
|
70
|
+
from ctypes import wintypes
|
|
71
|
+
|
|
72
|
+
try:
|
|
73
|
+
handle = wintypes.HANDLE(msvcrt.get_osfhandle(stream.fileno()))
|
|
74
|
+
except AttributeError, OSError, ValueError: # a stream that only acts like a terminal
|
|
75
|
+
return
|
|
76
|
+
kernel32 = ctypes.windll.kernel32
|
|
77
|
+
mode = wintypes.DWORD()
|
|
78
|
+
if kernel32.GetConsoleMode(handle, ctypes.byref(mode)):
|
|
79
|
+
kernel32.SetConsoleMode(handle, mode.value | _ENABLE_VIRTUAL_TERMINAL_PROCESSING)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
def _screen_formatter(stream: TextIO, problems: list[str]) -> logging.Formatter:
|
|
83
|
+
terminal = _is_terminal(stream)
|
|
84
|
+
automatic = "text" if terminal else "json"
|
|
85
|
+
style = _env("AA_LOG_FORMAT") or automatic
|
|
86
|
+
if style.lower() not in ("text", "json"):
|
|
87
|
+
problems.append(f"AA_LOG_FORMAT is {style!r}, which is not text or json, using {automatic}")
|
|
88
|
+
style = automatic
|
|
89
|
+
if style.lower() == "json":
|
|
90
|
+
return JsonFormatter()
|
|
91
|
+
if terminal:
|
|
92
|
+
_enable_color(stream)
|
|
93
|
+
return TextFormatter(color=terminal)
|
|
94
|
+
|
|
95
|
+
|
|
96
|
+
def _file_handler(path: str | os.PathLike[str]) -> logging.Handler:
|
|
97
|
+
Path(path).parent.mkdir(parents=True, exist_ok=True)
|
|
98
|
+
handler = RotatingFileHandler(
|
|
99
|
+
path,
|
|
100
|
+
maxBytes=_MAX_FILE_BYTES,
|
|
101
|
+
backupCount=_OLD_FILES_KEPT,
|
|
102
|
+
encoding="utf-8",
|
|
103
|
+
errors="backslashreplace",
|
|
104
|
+
)
|
|
105
|
+
handler.setFormatter(JsonFormatter())
|
|
106
|
+
return handler
|
|
107
|
+
|
|
108
|
+
|
|
109
|
+
def _attach(handler: logging.Handler, redaction: Redaction | None) -> None:
|
|
110
|
+
if redaction is not None:
|
|
111
|
+
handler.addFilter(redaction)
|
|
112
|
+
logging.getLogger().addHandler(handler)
|
|
113
|
+
_installed.append(handler)
|
|
114
|
+
|
|
115
|
+
|
|
116
|
+
def get_logger(name: str) -> logging.Logger:
|
|
117
|
+
"""Return the standard Python logger for ``name``. Safe at the top of a file."""
|
|
118
|
+
return logging.getLogger(name)
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
def configure_logging(
|
|
122
|
+
level: int | str = logging.INFO,
|
|
123
|
+
file: str | os.PathLike[str] | None = None,
|
|
124
|
+
redact: Redact | None = None,
|
|
125
|
+
) -> None:
|
|
126
|
+
"""Set up logging for the whole app. Call it once when the app starts.
|
|
127
|
+
|
|
128
|
+
``AA_LOG_LEVEL`` and ``AA_LOG_FILE`` override the arguments, and ``AA_LOG_FORMAT``
|
|
129
|
+
forces the screen style. ``redact`` cleans every line written by these handlers: it gets
|
|
130
|
+
a dict of ``message``, ``exception``, ``stack`` and ``extra`` and returns the same shape.
|
|
131
|
+
Calling it again replaces the earlier settings. A problem with any setting is reported
|
|
132
|
+
as a warning and never stops the app.
|
|
133
|
+
"""
|
|
134
|
+
root = logging.getLogger()
|
|
135
|
+
problems: list[str] = []
|
|
136
|
+
for handler in _installed:
|
|
137
|
+
root.removeHandler(handler)
|
|
138
|
+
try:
|
|
139
|
+
handler.close()
|
|
140
|
+
except (OSError, ValueError) as error:
|
|
141
|
+
problems.append(f"could not close the earlier log file: {error}")
|
|
142
|
+
_installed.clear()
|
|
143
|
+
|
|
144
|
+
redaction = None if redact is None else Redaction(redact)
|
|
145
|
+
|
|
146
|
+
screen = logging.StreamHandler(sys.stderr)
|
|
147
|
+
screen.setFormatter(_screen_formatter(sys.stderr, problems))
|
|
148
|
+
_attach(screen, redaction)
|
|
149
|
+
path = _env("AA_LOG_FILE") or file
|
|
150
|
+
if path is not None:
|
|
151
|
+
try:
|
|
152
|
+
_attach(_file_handler(path), redaction)
|
|
153
|
+
except (OSError, TypeError, ValueError) as error:
|
|
154
|
+
problems.append(f"could not open the log file {path}, logging to screen only: {error}")
|
|
155
|
+
root.setLevel(_choose_level(level, problems))
|
|
156
|
+
|
|
157
|
+
# Straight to the handlers, so the warnings still show when the app's level would hide them.
|
|
158
|
+
setup_log = logging.getLogger("aa_log")
|
|
159
|
+
|
|
160
|
+
def warning(problem: str) -> logging.LogRecord:
|
|
161
|
+
message = " ".join(problem.splitlines())
|
|
162
|
+
return setup_log.makeRecord(setup_log.name, logging.WARNING, __file__, 0, message, (), None)
|
|
163
|
+
|
|
164
|
+
warnings = [warning(problem) for problem in problems]
|
|
165
|
+
if redaction is not None and not callable(redact):
|
|
166
|
+
uncallable = warning(
|
|
167
|
+
f"redact= takes a function, and a {type(redact).__name__} can't be called,"
|
|
168
|
+
f" so every log line shows {FAILED}"
|
|
169
|
+
)
|
|
170
|
+
warnings.insert(0, uncallable)
|
|
171
|
+
redaction.let_through = [uncallable]
|
|
172
|
+
try:
|
|
173
|
+
with contextlib.suppress(ValueError):
|
|
174
|
+
for record in warnings:
|
|
175
|
+
setup_log.handle(record)
|
|
176
|
+
finally:
|
|
177
|
+
if redaction is not None:
|
|
178
|
+
redaction.let_through = []
|
aa_log/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,128 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: aa-toolkit-log
|
|
3
|
+
Version: 0.1.0a1
|
|
4
|
+
Summary: Ready-made logging for apps, on top of Python's logging.
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Python: >=3.14
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
|
|
10
|
+
# aa-toolkit-log
|
|
11
|
+
|
|
12
|
+
Ready-made logging for apps, on top of Python's built-in logging. It has no dependencies.
|
|
13
|
+
|
|
14
|
+
An app gets clean, lined-up columns in a terminal and JSON lines when a tool or an agent runs it, and it can save its logs to a file that can't fill the disk.
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
Install it from the toolkit's GitHub repo, pinned to a version tag:
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
uv add "aa-toolkit-log @ git+https://github.com/aaronaco/aa-toolkit@log-v0.1.0#subdirectory=packages/aa-toolkit-log"
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
## Use
|
|
25
|
+
|
|
26
|
+
Call `configure_logging()` once when the app starts. Every file gets its logger from `get_logger(__name__)` and logs with the usual methods, because it's a standard Python logger.
|
|
27
|
+
|
|
28
|
+
```python
|
|
29
|
+
from aa_log import configure_logging, get_logger
|
|
30
|
+
|
|
31
|
+
log = get_logger(__name__)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def main() -> None:
|
|
35
|
+
configure_logging()
|
|
36
|
+
log.info("fetched", extra={"url": "https://example.com", "code": 200})
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
In a terminal that prints:
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
14:03:21 INFO __main__ fetched url=https://example.com code=200
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
When stderr isn't a terminal, it prints:
|
|
46
|
+
|
|
47
|
+
```json
|
|
48
|
+
{"time": "2026-11-09T14:03:21.482+08:00", "level": "info", "logger": "__main__", "message": "fetched", "url": "https://example.com", "code": 200}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Logs go to stderr, so stdout stays free for the app's own output. Logs from installed packages appear in the same format. Calling `configure_logging()` again replaces the earlier settings, and handlers it didn't add stay attached. If you never call it, Python's normal behavior applies, and warnings and errors still show.
|
|
52
|
+
|
|
53
|
+
Only an app calls `configure_logging()`. A library should log through Python's `logging` and leave the setup to the app.
|
|
54
|
+
|
|
55
|
+
### Arguments
|
|
56
|
+
|
|
57
|
+
`configure_logging(level=..., file=..., redact=...)` takes three optional arguments:
|
|
58
|
+
|
|
59
|
+
- `level`: the lowest level to show, as a name like `"DEBUG"` or a number like `logging.DEBUG`. The default is `INFO`.
|
|
60
|
+
- `file`: a path to save logs to. A relative path is relative to the current folder. By default no file is written.
|
|
61
|
+
- `redact`: a function that cleans every log line before it's written, see [Hiding secrets](#hiding-secrets). By default nothing is cleaned.
|
|
62
|
+
|
|
63
|
+
### Environment variables
|
|
64
|
+
|
|
65
|
+
A variable that is set wins over the matching argument. An empty one counts as not set.
|
|
66
|
+
|
|
67
|
+
| Variable | Values | What it does |
|
|
68
|
+
|---|---|---|
|
|
69
|
+
| `AA_LOG_LEVEL` | `DEBUG`, `INFO`, `WARN`, `ERROR`, `CRIT` | Sets the lowest level to show. |
|
|
70
|
+
| `AA_LOG_FORMAT` | `text`, `json` | Forces the style on screen. Without it, a terminal gets `text` and anything else gets `json`. |
|
|
71
|
+
| `AA_LOG_FILE` | a path | Saves logs to that file. |
|
|
72
|
+
|
|
73
|
+
A bad `AA_LOG_LEVEL` gives a warning and the `level` argument is used, which is `INFO` unless the app passes another level. A bad `AA_LOG_FORMAT` gives a warning and the style is chosen as if it weren't set. A log file that can't be opened gives a warning and logs stay on screen. Neither stops the app.
|
|
74
|
+
|
|
75
|
+
## Saving to a file
|
|
76
|
+
|
|
77
|
+
The file always holds JSON lines in UTF-8, with the same messages as the screen. Its folder is created when it's missing. At 10 MB a new file starts and the last 3 old ones are kept. Only one copy of an app should write to a log file at a time: on Windows, starting a new file can fail when two copies share one, and some lines can be lost.
|
|
78
|
+
|
|
79
|
+
Add `*.log` and `*.log.[1-3]` to your `.gitignore`, so a log file and its old copies aren't committed by accident.
|
|
80
|
+
|
|
81
|
+
## Hiding secrets
|
|
82
|
+
|
|
83
|
+
By default, logs don't hide secrets: whatever you log is shown on screen and saved to the file as it is. The best fix is not to log passwords, tokens or keys at all. For the ones you don't see coming, such as a token in an error message from another package, pass a function as `redact`.
|
|
84
|
+
|
|
85
|
+
The redaction library, [`aa-toolkit-redact`](../aa-toolkit-redact/README.md), gives you one. Install it as its README shows, then pass a `Redactor`:
|
|
86
|
+
|
|
87
|
+
```python
|
|
88
|
+
from aa_log import configure_logging, get_logger
|
|
89
|
+
from aa_redact import Redactor
|
|
90
|
+
|
|
91
|
+
log = get_logger(__name__)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def main() -> None:
|
|
95
|
+
configure_logging(redact=Redactor())
|
|
96
|
+
log.info("signed up %s", "ann@example.com", extra={"password": "hunter2"})
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
That prints:
|
|
100
|
+
|
|
101
|
+
```text
|
|
102
|
+
14:03:21 INFO __main__ signed up [EMAIL] password=[REDACTED]
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
Every line is cleaned the same way on screen and in the file: the message after its values are filled in, tracebacks, stack information and every `extra` value. Logs from installed packages are cleaned too. The time, level and logger name are left alone. There is no environment variable for it, so a stray setting can't turn it on or off.
|
|
106
|
+
|
|
107
|
+
If the function fails, the line shows only the time, level, logger and `[REDACTION FAILED]`, and the app carries on. The same happens when a log call's values don't fit its message, such as `log.info("%d", "text")`. A `redact` that can't be called gives a warning, and every line after it shows `[REDACTION FAILED]`.
|
|
108
|
+
|
|
109
|
+
Only the handlers `configure_logging()` adds are cleaned. A handler your app adds itself gets the raw lines.
|
|
110
|
+
|
|
111
|
+
`redact` can be any function. It gets one dictionary and returns one of the same shape:
|
|
112
|
+
|
|
113
|
+
```python
|
|
114
|
+
{
|
|
115
|
+
"message": "signed up ann@example.com",
|
|
116
|
+
"exception": None,
|
|
117
|
+
"stack": None,
|
|
118
|
+
"extra": {"password": "hunter2"},
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
`exception` and `stack` are text or `None`, and `extra` holds the `extra` values by name. The dictionaries, lists, sets and tuples it gets are copies, so changing them leaves the app's own record alone. It shouldn't change any other object it gets.
|
|
123
|
+
|
|
124
|
+
## Names you can't use in `extra`
|
|
125
|
+
|
|
126
|
+
Python raises an error when `extra` uses a name it reserves: `args`, `asctime`, `created`, `exc_info`, `exc_text`, `filename`, `funcName`, `levelname`, `levelno`, `lineno`, `message`, `module`, `msecs`, `msg`, `name`, `pathname`, `process`, `processName`, `relativeCreated`, `stack_info`, `taskName`, `thread` and `threadName`.
|
|
127
|
+
|
|
128
|
+
`extra` can use `time`, `level` and `logger`, but in JSON the real values keep those fields and the `extra` values are dropped.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
aa_log/__init__.py,sha256=WvsrizN09ykCrGHebUrt04qAlpBrmQVRIVfAnRXPM8o,172
|
|
2
|
+
aa_log/_format.py,sha256=X8Ij_cQMNQIeuZa3WCbWhwMHmZaG3oav1cgWAMr2Hk8,3703
|
|
3
|
+
aa_log/_redact.py,sha256=0fhk1xlcJTPakUd8FJJ7Ea2CmRI_1i0iM4dE6x-mZM0,4879
|
|
4
|
+
aa_log/_setup.py,sha256=hMxteb8tmpehkLb0_FCB7J8C3NqhxhT8LjgzUnZQUeM,6281
|
|
5
|
+
aa_log/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
6
|
+
aa_toolkit_log-0.1.0a1.dist-info/licenses/LICENSE,sha256=S6eMY2C8HjBm-nve9yHJM84hWaY7wRNNbdNgjCf5jUQ,1087
|
|
7
|
+
aa_toolkit_log-0.1.0a1.dist-info/WHEEL,sha256=MWx7psoF7KNST9G72pGtiBYuaXRXQXBk9pw5R6FzYko,80
|
|
8
|
+
aa_toolkit_log-0.1.0a1.dist-info/METADATA,sha256=uEYykYhY1WefKmP1Vf38JuysQSBm3dLprVIigPck29g,6296
|
|
9
|
+
aa_toolkit_log-0.1.0a1.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aaron Aco
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|