tf-logging-sdk 0.1.0__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.
@@ -0,0 +1,15 @@
1
+ """统一日志 SDK 对外导出入口。"""
2
+
3
+ from tf_logging_sdk.config import DEFAULT_MASK_FIELDS, DEFAULT_STANDARD_FIELDS, LoggingConfig
4
+ from tf_logging_sdk.context import bind_log_context, clear_log_context, get_log_context
5
+ from tf_logging_sdk.handlers import setup_logging
6
+
7
+ __all__ = [
8
+ "DEFAULT_MASK_FIELDS",
9
+ "DEFAULT_STANDARD_FIELDS",
10
+ "LoggingConfig",
11
+ "bind_log_context",
12
+ "clear_log_context",
13
+ "get_log_context",
14
+ "setup_logging",
15
+ ]
@@ -0,0 +1,129 @@
1
+ """统一日志 SDK 配置定义。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import dataclass, field
6
+ from typing import Any
7
+
8
+ DEFAULT_STANDARD_FIELDS = [
9
+ "timestamp",
10
+ "level",
11
+ "service",
12
+ "environment",
13
+ "module",
14
+ "message",
15
+ "trace_id",
16
+ "task_id",
17
+ "space_id",
18
+ "message_type",
19
+ "topic",
20
+ "consumer_group",
21
+ "worker_type",
22
+ "region",
23
+ "duration_ms",
24
+ "error_code",
25
+ "error",
26
+ ]
27
+
28
+ DEFAULT_MASK_FIELDS = [
29
+ "password",
30
+ "token",
31
+ "authorization",
32
+ "cookie",
33
+ "secret",
34
+ "access_key",
35
+ "proxy_password",
36
+ "phone",
37
+ "email",
38
+ ]
39
+
40
+ DEFAULT_CONTEXT_FIELDS = [
41
+ "trace_id",
42
+ "task_id",
43
+ "space_id",
44
+ "message_type",
45
+ "topic",
46
+ "consumer_group",
47
+ "worker_type",
48
+ "region",
49
+ ]
50
+
51
+ DEFAULT_EXTRA_FIELDS = [
52
+ "duration_ms",
53
+ "error_code",
54
+ "error",
55
+ ]
56
+
57
+ RESERVED_LOG_RECORD_FIELDS = {
58
+ "args",
59
+ "asctime",
60
+ "created",
61
+ "exc_info",
62
+ "exc_text",
63
+ "filename",
64
+ "funcName",
65
+ "levelname",
66
+ "levelno",
67
+ "lineno",
68
+ "module",
69
+ "msecs",
70
+ "message",
71
+ "msg",
72
+ "name",
73
+ "pathname",
74
+ "process",
75
+ "processName",
76
+ "relativeCreated",
77
+ "stack_info",
78
+ "taskName",
79
+ "thread",
80
+ "threadName",
81
+ }
82
+
83
+
84
+ @dataclass(slots=True)
85
+ class LoggingConfig:
86
+ """统一日志初始化配置。"""
87
+
88
+ service_name: str
89
+ environment: str
90
+ level: str = "INFO"
91
+ enable_stdout: bool = True
92
+ enable_logstash: bool = True
93
+ logstash_host: str | None = None
94
+ logstash_port: int | None = None
95
+ logstash_timeout: float = 1.0
96
+ enable_file: bool = False
97
+ log_file_path: str | None = None
98
+ file_max_bytes: int = 50 * 1024 * 1024
99
+ file_backup_count: int = 5
100
+ standard_fields: list[str] = field(default_factory=lambda: list(DEFAULT_STANDARD_FIELDS))
101
+ mask_fields: list[str] = field(default_factory=lambda: list(DEFAULT_MASK_FIELDS))
102
+ extra_mask_fields: list[str] = field(default_factory=list)
103
+
104
+ def __post_init__(self) -> None:
105
+ """校验并整理配置。"""
106
+ if not self.service_name:
107
+ raise ValueError("service_name is required")
108
+ if not self.environment:
109
+ raise ValueError("environment is required")
110
+ if self.enable_file and not self.log_file_path:
111
+ raise ValueError("log_file_path is required when enable_file is True")
112
+ if self.file_max_bytes <= 0:
113
+ raise ValueError("file_max_bytes must be greater than 0")
114
+ if self.file_backup_count < 0:
115
+ raise ValueError("file_backup_count must be greater than or equal to 0")
116
+ self.level = self.level.upper()
117
+
118
+ @property
119
+ def effective_mask_fields(self) -> list[str]:
120
+ """返回最终生效的脱敏字段列表。"""
121
+ mask_field_map = {field_name.lower(): field_name for field_name in self.mask_fields}
122
+ for field_name in self.extra_mask_fields:
123
+ mask_field_map[field_name.lower()] = field_name
124
+ return list(mask_field_map.values())
125
+
126
+ @classmethod
127
+ def from_kwargs(cls, **kwargs: Any) -> "LoggingConfig":
128
+ """兼容关键字参数初始化。"""
129
+ return cls(**kwargs)
@@ -0,0 +1,52 @@
1
+ """统一日志上下文管理。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ from contextvars import ContextVar
6
+ from typing import Any
7
+
8
+ from tf_logging_sdk.config import DEFAULT_CONTEXT_FIELDS
9
+
10
+ _LOG_CONTEXT: ContextVar[dict[str, Any]] = ContextVar("tf_logging_sdk_context", default={})
11
+
12
+
13
+ def bind_log_context(**kwargs: Any) -> None:
14
+ """绑定当前执行上下文的日志字段。
15
+
16
+ 参数:
17
+ **kwargs: 允许传入标准上下文字段,也允许传入扩展字段。
18
+ """
19
+ current_context = dict(_LOG_CONTEXT.get())
20
+ for field_name, field_value in kwargs.items():
21
+ if field_value is None:
22
+ continue
23
+ current_context[field_name] = field_value
24
+ _LOG_CONTEXT.set(current_context)
25
+
26
+
27
+ def clear_log_context(*field_names: str) -> None:
28
+ """清理当前执行上下文的日志字段。
29
+
30
+ 参数:
31
+ *field_names: 指定要清理的字段;若为空,则清理全部上下文。
32
+ """
33
+ if not field_names:
34
+ _LOG_CONTEXT.set({})
35
+ return
36
+
37
+ current_context = dict(_LOG_CONTEXT.get())
38
+ for field_name in field_names:
39
+ current_context.pop(field_name, None)
40
+ _LOG_CONTEXT.set(current_context)
41
+
42
+
43
+ def get_log_context() -> dict[str, Any]:
44
+ """获取当前执行上下文的日志字段快照。"""
45
+ current_context = dict(_LOG_CONTEXT.get())
46
+ normalized_context: dict[str, Any] = {}
47
+ for field_name in DEFAULT_CONTEXT_FIELDS:
48
+ normalized_context[field_name] = current_context.get(field_name)
49
+ for field_name, field_value in current_context.items():
50
+ if field_name not in normalized_context:
51
+ normalized_context[field_name] = field_value
52
+ return normalized_context
@@ -0,0 +1,114 @@
1
+ """统一日志过滤与标准字段注入。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import traceback
7
+ from datetime import datetime, timezone
8
+ from typing import Any
9
+
10
+ from tf_logging_sdk.config import (
11
+ DEFAULT_EXTRA_FIELDS,
12
+ DEFAULT_STANDARD_FIELDS,
13
+ LoggingConfig,
14
+ RESERVED_LOG_RECORD_FIELDS,
15
+ )
16
+ from tf_logging_sdk.context import get_log_context
17
+ from tf_logging_sdk.masking import LogMasker
18
+
19
+
20
+ class ContextEnrichmentFilter(logging.Filter):
21
+ """为日志记录注入标准字段和上下文。"""
22
+
23
+ def __init__(self, config: LoggingConfig, masker: LogMasker):
24
+ """初始化过滤器。
25
+
26
+ 参数:
27
+ config: 日志初始化配置。
28
+ masker: 脱敏器。
29
+ """
30
+ super().__init__()
31
+ self._config = config
32
+ self._masker = masker
33
+
34
+ def filter(self, record: logging.LogRecord) -> bool:
35
+ """将标准字段写回日志记录,供 formatter 和 handler 使用。"""
36
+ context = get_log_context()
37
+ message = record.getMessage()
38
+ masked_message = self._masker.mask_text(str(message))
39
+ record.msg = masked_message
40
+ record.args = ()
41
+
42
+ extra_payload = self._collect_extra_payload(record)
43
+ masked_extra_payload = self._masker.mask(extra_payload)
44
+
45
+ timestamp = datetime.fromtimestamp(record.created, tz=timezone.utc).isoformat()
46
+ standard_payload: dict[str, Any] = {
47
+ "timestamp": timestamp,
48
+ "level": record.levelname,
49
+ "service": self._config.service_name,
50
+ "environment": self._config.environment,
51
+ "module": record.name,
52
+ "message": masked_message,
53
+ "trace_id": context.get("trace_id"),
54
+ "task_id": context.get("task_id"),
55
+ "space_id": context.get("space_id"),
56
+ "message_type": context.get("message_type"),
57
+ "topic": context.get("topic"),
58
+ "consumer_group": context.get("consumer_group"),
59
+ "worker_type": context.get("worker_type"),
60
+ "region": context.get("region"),
61
+ "duration_ms": masked_extra_payload.get("duration_ms"),
62
+ "error_code": masked_extra_payload.get("error_code"),
63
+ "error": self._build_error_field(record, masked_extra_payload),
64
+ }
65
+
66
+ for field_name, field_value in context.items():
67
+ standard_payload.setdefault(field_name, field_value)
68
+ for field_name, field_value in masked_extra_payload.items():
69
+ standard_payload.setdefault(field_name, field_value)
70
+
71
+ standard_payload["standard_fields"] = list(DEFAULT_STANDARD_FIELDS)
72
+
73
+ for field_name, field_value in standard_payload.items():
74
+ setattr(record, field_name, field_value)
75
+ record.structured_payload = {
76
+ field_name: getattr(record, field_name, None)
77
+ for field_name in self._config.standard_fields
78
+ }
79
+ record.structured_payload["extra"] = {
80
+ field_name: field_value
81
+ for field_name, field_value in standard_payload.items()
82
+ if field_name not in self._config.standard_fields
83
+ and field_name != "standard_fields"
84
+ }
85
+ return True
86
+
87
+ def _collect_extra_payload(self, record: logging.LogRecord) -> dict[str, Any]:
88
+ """提取调用方通过 extra 注入的字段。"""
89
+ extra_payload: dict[str, Any] = {}
90
+ for field_name, field_value in record.__dict__.items():
91
+ if field_name in RESERVED_LOG_RECORD_FIELDS:
92
+ continue
93
+ if field_name in DEFAULT_STANDARD_FIELDS and field_name not in DEFAULT_EXTRA_FIELDS:
94
+ continue
95
+ if field_name == "structured_payload":
96
+ continue
97
+ extra_payload[field_name] = field_value
98
+
99
+ for field_name in DEFAULT_EXTRA_FIELDS:
100
+ extra_payload.setdefault(field_name, None)
101
+ return extra_payload
102
+
103
+ def _build_error_field(
104
+ self,
105
+ record: logging.LogRecord,
106
+ masked_extra_payload: dict[str, Any],
107
+ ) -> str | None:
108
+ """统一构建错误字段。"""
109
+ if masked_extra_payload.get("error"):
110
+ return str(masked_extra_payload["error"])
111
+ if not record.exc_info:
112
+ return None
113
+ formatted_exception = "".join(traceback.format_exception(*record.exc_info)).strip()
114
+ return self._masker.mask_text(formatted_exception)
@@ -0,0 +1,76 @@
1
+ """统一日志格式化器。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import json
6
+ import logging
7
+ from typing import Any
8
+
9
+
10
+ class ConsoleFormatter(logging.Formatter):
11
+ """控制台可读格式化器。"""
12
+
13
+ def format(self, record: logging.LogRecord) -> str:
14
+ """输出便于人工排查的单行文本。"""
15
+ payload = getattr(record, "structured_payload", {})
16
+ parts = [
17
+ str(payload.get("timestamp", "")),
18
+ f"[{payload.get('level', '')}]",
19
+ f"[{payload.get('service', '')}]",
20
+ f"[{payload.get('environment', '')}]",
21
+ f"[{payload.get('module', '')}]",
22
+ str(payload.get("message", "")),
23
+ ]
24
+
25
+ optional_fields = [
26
+ "trace_id",
27
+ "task_id",
28
+ "space_id",
29
+ "message_type",
30
+ "topic",
31
+ "consumer_group",
32
+ "worker_type",
33
+ "region",
34
+ "duration_ms",
35
+ "error_code",
36
+ ]
37
+ for field_name in optional_fields:
38
+ field_value = payload.get(field_name)
39
+ if field_value is not None and field_value != "":
40
+ parts.append(f"{field_name}={field_value}")
41
+
42
+ error_value = payload.get("error")
43
+ if error_value:
44
+ parts.append(f"error={error_value}")
45
+ return " ".join(parts)
46
+
47
+
48
+ class JsonFormatter(logging.Formatter):
49
+ """结构化 JSON 格式化器。"""
50
+
51
+ def format(self, record: logging.LogRecord) -> str:
52
+ """输出 JSON 文本,供文件和网络日志消费。"""
53
+ payload = dict(getattr(record, "structured_payload", {}))
54
+ return json.dumps(self._normalize_payload(payload), ensure_ascii=False, separators=(",", ":"))
55
+
56
+ def _normalize_payload(self, payload: dict[str, Any]) -> dict[str, Any]:
57
+ """清理不可序列化值,保证日志不会因格式问题丢失。"""
58
+ normalized_payload: dict[str, Any] = {}
59
+ for field_name, field_value in payload.items():
60
+ normalized_payload[field_name] = self._normalize_value(field_value)
61
+ return normalized_payload
62
+
63
+ def _normalize_value(self, field_value: Any) -> Any:
64
+ """递归归一化 JSON 值。"""
65
+ if field_value is None or isinstance(field_value, (bool, int, float, str)):
66
+ return field_value
67
+ if isinstance(field_value, list):
68
+ return [self._normalize_value(item) for item in field_value]
69
+ if isinstance(field_value, tuple):
70
+ return [self._normalize_value(item) for item in field_value]
71
+ if isinstance(field_value, dict):
72
+ return {
73
+ str(key): self._normalize_value(value)
74
+ for key, value in field_value.items()
75
+ }
76
+ return str(field_value)
@@ -0,0 +1,170 @@
1
+ """统一日志 handler 与初始化入口。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import logging.handlers
7
+ import os
8
+ import socket
9
+ import sys
10
+
11
+ from tf_logging_sdk.config import LoggingConfig
12
+ from tf_logging_sdk.filters import ContextEnrichmentFilter
13
+ from tf_logging_sdk.formatter import ConsoleFormatter, JsonFormatter
14
+ from tf_logging_sdk.masking import LogMasker
15
+
16
+
17
+ class TcpJsonLogstashHandler(logging.Handler):
18
+ """基于 TCP 的简易 JSON Logstash handler。"""
19
+
20
+ def __init__(self, host: str, port: int, timeout: float = 1.0):
21
+ """初始化 TCP 输出 handler。
22
+
23
+ 参数:
24
+ host: Logstash 主机。
25
+ port: Logstash 端口。
26
+ timeout: 连接和发送超时时间,单位秒。
27
+ """
28
+ super().__init__()
29
+ self._host = host
30
+ self._port = port
31
+ self._timeout = timeout
32
+
33
+ def emit(self, record: logging.LogRecord) -> None:
34
+ """发送结构化日志,失败时静默降级。"""
35
+ try:
36
+ message = self.format(record) + "\n"
37
+ with socket.create_connection((self._host, self._port), timeout=self._timeout) as client:
38
+ client.sendall(message.encode("utf-8"))
39
+ except Exception:
40
+ self.handleError(record)
41
+
42
+ def handleError(self, record: logging.LogRecord) -> None:
43
+ """网络日志失败时不打断主流程。"""
44
+ return
45
+
46
+
47
+ def setup_logging(
48
+ service_name: str,
49
+ environment: str,
50
+ level: str = "INFO",
51
+ enable_stdout: bool = True,
52
+ enable_logstash: bool = True,
53
+ logstash_host: str | None = None,
54
+ logstash_port: int | None = None,
55
+ logstash_timeout: float = 1.0,
56
+ enable_file: bool = False,
57
+ log_file_path: str | None = None,
58
+ file_max_bytes: int = 50 * 1024 * 1024,
59
+ file_backup_count: int = 5,
60
+ mask_fields: list[str] | None = None,
61
+ extra_mask_fields: list[str] | None = None,
62
+ ) -> LoggingConfig:
63
+ """初始化项目统一日志配置。
64
+
65
+ 参数:
66
+ service_name: 服务名称。
67
+ environment: 环境名称,例如 dev、test、prod。
68
+ level: 根日志级别。
69
+ enable_stdout: 是否输出到标准输出。
70
+ enable_logstash: 是否启用 Logstash TCP 输出。
71
+ logstash_host: Logstash 主机。
72
+ logstash_port: Logstash 端口。
73
+ logstash_timeout: Logstash 连接超时。
74
+ enable_file: 是否开启文件日志。
75
+ log_file_path: 文件日志路径。
76
+ file_max_bytes: 文件滚动大小上限。
77
+ file_backup_count: 文件备份数量。
78
+ mask_fields: 自定义完整脱敏字段列表。
79
+ extra_mask_fields: 在默认脱敏字段基础上追加的字段。
80
+
81
+ 返回:
82
+ LoggingConfig: 生效配置对象。
83
+ """
84
+ config = LoggingConfig(
85
+ service_name=service_name,
86
+ environment=environment,
87
+ level=level,
88
+ enable_stdout=enable_stdout,
89
+ enable_logstash=enable_logstash,
90
+ logstash_host=logstash_host,
91
+ logstash_port=logstash_port,
92
+ logstash_timeout=logstash_timeout,
93
+ enable_file=enable_file,
94
+ log_file_path=log_file_path,
95
+ file_max_bytes=file_max_bytes,
96
+ file_backup_count=file_backup_count,
97
+ mask_fields=mask_fields if mask_fields is not None else LoggingConfig(service_name, environment).mask_fields,
98
+ extra_mask_fields=extra_mask_fields or [],
99
+ )
100
+ return _apply_logging_config(config)
101
+
102
+
103
+ def _apply_logging_config(config: LoggingConfig) -> LoggingConfig:
104
+ """将日志配置应用到根 logger。"""
105
+ masker = LogMasker(config.effective_mask_fields)
106
+ root_logger = logging.getLogger()
107
+ root_logger.setLevel(_get_level_value(config.level))
108
+ root_logger.handlers.clear()
109
+ root_logger.filters.clear()
110
+
111
+ enrichment_filter = ContextEnrichmentFilter(config=config, masker=masker)
112
+
113
+ for handler in _build_handlers(config):
114
+ handler.setLevel(_get_level_value(config.level))
115
+ handler.addFilter(enrichment_filter)
116
+ root_logger.addHandler(handler)
117
+
118
+ return config
119
+
120
+
121
+ def _build_handlers(config: LoggingConfig) -> list[logging.Handler]:
122
+ """按配置构建 handler 列表。"""
123
+ handlers: list[logging.Handler] = []
124
+
125
+ if config.enable_stdout:
126
+ stdout_handler = logging.StreamHandler(stream=sys.stdout)
127
+ stdout_handler.setFormatter(ConsoleFormatter())
128
+ handlers.append(stdout_handler)
129
+
130
+ if config.enable_file and config.log_file_path:
131
+ _ensure_log_directory_exists(config.log_file_path)
132
+ file_handler = logging.handlers.RotatingFileHandler(
133
+ filename=config.log_file_path,
134
+ maxBytes=config.file_max_bytes,
135
+ backupCount=config.file_backup_count,
136
+ encoding="utf-8",
137
+ )
138
+ file_handler.setFormatter(JsonFormatter())
139
+ handlers.append(file_handler)
140
+
141
+ if config.enable_logstash and config.logstash_host and config.logstash_port:
142
+ logstash_handler = TcpJsonLogstashHandler(
143
+ host=config.logstash_host,
144
+ port=config.logstash_port,
145
+ timeout=config.logstash_timeout,
146
+ )
147
+ logstash_handler.setFormatter(JsonFormatter())
148
+ handlers.append(logstash_handler)
149
+
150
+ if not handlers:
151
+ fallback_handler = logging.StreamHandler(stream=sys.stdout)
152
+ fallback_handler.setFormatter(ConsoleFormatter())
153
+ handlers.append(fallback_handler)
154
+
155
+ return handlers
156
+
157
+
158
+ def _ensure_log_directory_exists(log_file_path: str) -> None:
159
+ """确保文件日志目录存在。"""
160
+ directory_path = os.path.dirname(os.path.abspath(log_file_path))
161
+ if directory_path:
162
+ os.makedirs(directory_path, exist_ok=True)
163
+
164
+
165
+ def _get_level_value(level_name: str) -> int:
166
+ """将级别名称转换为 logging 级别值。"""
167
+ level_value = logging.getLevelName(level_name.upper())
168
+ if isinstance(level_value, str):
169
+ raise ValueError("invalid log level")
170
+ return level_value
@@ -0,0 +1,112 @@
1
+ """统一日志脱敏能力。"""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Mapping, Sequence
6
+ from typing import Any
7
+
8
+ MASK_PLACEHOLDER = "***"
9
+
10
+
11
+ class LogMasker:
12
+ """日志脱敏器。"""
13
+
14
+ def __init__(self, mask_fields: list[str]):
15
+ """初始化脱敏器。
16
+
17
+ 参数:
18
+ mask_fields: 需要按字段名脱敏的字段列表。
19
+ """
20
+ self._mask_fields = {field_name.lower() for field_name in mask_fields}
21
+
22
+ def mask(self, value: Any, field_name: str | None = None) -> Any:
23
+ """对任意对象进行递归脱敏。
24
+
25
+ 参数:
26
+ value: 待脱敏对象。
27
+ field_name: 当前对象对应的字段名。
28
+
29
+ 返回:
30
+ Any: 脱敏后的对象。
31
+ """
32
+ if field_name and field_name.lower() in self._mask_fields:
33
+ return self._mask_scalar(value)
34
+ if isinstance(value, Mapping):
35
+ return {
36
+ key: self.mask(item, field_name=str(key))
37
+ for key, item in value.items()
38
+ }
39
+ if isinstance(value, tuple):
40
+ return tuple(self.mask(item) for item in value)
41
+ if isinstance(value, Sequence) and not isinstance(value, (str, bytes, bytearray)):
42
+ return [self.mask(item) for item in value]
43
+ return value
44
+
45
+ def mask_text(self, text: str) -> str:
46
+ """对纯文本执行轻量脱敏。
47
+
48
+ 参数:
49
+ text: 待处理文本。
50
+
51
+ 返回:
52
+ str: 脱敏后的文本。
53
+ """
54
+ masked_text = text
55
+ for field_name in self._mask_fields:
56
+ lower_text = masked_text.lower()
57
+ if field_name not in lower_text:
58
+ continue
59
+
60
+ token_patterns = [
61
+ f"{field_name}=",
62
+ f"{field_name}:",
63
+ f"'{field_name}':",
64
+ f'"{field_name}":',
65
+ ]
66
+ for token_pattern in token_patterns:
67
+ masked_text = self._mask_text_pattern(masked_text, token_pattern)
68
+ return masked_text
69
+
70
+ def _mask_text_pattern(self, text: str, marker: str) -> str:
71
+ """按标记符号对文本片段脱敏。"""
72
+ search_start = 0
73
+ masked_text = text
74
+ marker_length = len(marker)
75
+ while True:
76
+ match_index = masked_text.lower().find(marker.lower(), search_start)
77
+ if match_index < 0:
78
+ break
79
+ value_start = match_index + marker_length
80
+ value_end = self._locate_value_end(masked_text, value_start)
81
+ original_value = masked_text[value_start:value_end].strip().strip("'\"")
82
+ if original_value:
83
+ masked_value = self._mask_scalar(original_value)
84
+ masked_text = (
85
+ masked_text[:value_start]
86
+ + f" {masked_value}"
87
+ + masked_text[value_end:]
88
+ )
89
+ search_start = value_start + len(str(masked_value)) + 1
90
+ else:
91
+ search_start = value_end
92
+ return masked_text
93
+
94
+ @staticmethod
95
+ def _locate_value_end(text: str, value_start: int) -> int:
96
+ """定位文本值的结束位置。"""
97
+ separators = [",", ";", "&", " ", "\n", "\r", "\t", "}"]
98
+ positions = [text.find(separator, value_start) for separator in separators]
99
+ valid_positions = [position for position in positions if position >= 0]
100
+ if not valid_positions:
101
+ return len(text)
102
+ return min(valid_positions)
103
+
104
+ @staticmethod
105
+ def _mask_scalar(value: Any) -> str:
106
+ """对标量值脱敏,仅保留少量首尾信息。"""
107
+ value_text = str(value)
108
+ if not value_text:
109
+ return MASK_PLACEHOLDER
110
+ if len(value_text) <= 6:
111
+ return MASK_PLACEHOLDER
112
+ return f"{value_text[:2]}{MASK_PLACEHOLDER}{value_text[-2:]}"
@@ -0,0 +1,234 @@
1
+ Metadata-Version: 2.4
2
+ Name: tf-logging-sdk
3
+ Version: 0.1.0
4
+ Summary: 项目级统一日志 SDK,提供标准字段、上下文注入、脱敏和多通道输出能力
5
+ Project-URL: Homepage, https://github.com/tfkxsx/tf-logging-sdk
6
+ Project-URL: Repository, https://github.com/tfkxsx/tf-logging-sdk
7
+ Project-URL: Issues, https://github.com/tfkxsx/tf-logging-sdk/issues
8
+ Project-URL: Source, https://github.com/tfkxsx/tf-logging-sdk.git
9
+ Author-email: tfkxsx <tfkxsx@gmail.com>
10
+ License: MIT
11
+ License-File: LICENSE
12
+ Keywords: logging,logstash,observability,sdk,structured-logging
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Operating System :: OS Independent
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
+ Classifier: Topic :: System :: Logging
23
+ Requires-Python: >=3.10
24
+ Provides-Extra: dev
25
+ Requires-Dist: build>=1.2.1; extra == 'dev'
26
+ Requires-Dist: pytest>=8.0.0; extra == 'dev'
27
+ Requires-Dist: twine>=5.0.0; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # tf-logging-sdk
31
+
32
+ 项目级统一日志 SDK,提供统一初始化入口、标准字段、上下文注入、敏感信息脱敏,以及 `stdout / file / Logstash TCP` 多通道输出能力。
33
+
34
+ 仓库地址:
35
+
36
+ - GitHub: [https://github.com/tfkxsx/tf-logging-sdk](https://github.com/tfkxsx/tf-logging-sdk)
37
+ - Git: `git@github.com:tfkxsx/tf-logging-sdk.git`
38
+
39
+ ## 功能特性
40
+
41
+ 1. 提供统一入口 `setup_logging`
42
+ 2. 提供 `bind_log_context` 和 `clear_log_context`
43
+ 3. 统一输出标准字段,便于检索和排障
44
+ 4. 默认脱敏 `password`、`token`、`authorization`、`cookie`、`secret` 等敏感字段
45
+ 5. 支持控制台可读输出
46
+ 6. 支持 JSON 文件滚动日志
47
+ 7. 支持 TCP Logstash 结构化输出
48
+ 8. 未配置 Logstash 时自动降级,不影响本地启动
49
+
50
+ ## 安装
51
+
52
+ ```bash
53
+ pip install tf-logging-sdk
54
+ ```
55
+
56
+ 本地开发安装:
57
+
58
+ ```bash
59
+ pip install -e .[dev]
60
+ ```
61
+
62
+ ## 快速开始
63
+
64
+ ```python
65
+ import logging
66
+
67
+ from tf_logging_sdk import bind_log_context, clear_log_context, setup_logging
68
+
69
+ setup_logging(
70
+ service_name="kafka-task",
71
+ environment="dev",
72
+ enable_file=True,
73
+ log_file_path="logs/kafka-task.log",
74
+ enable_logstash=False,
75
+ )
76
+
77
+ logger = logging.getLogger(__name__)
78
+
79
+ bind_log_context(
80
+ trace_id="trace-demo-001",
81
+ task_id="task-demo-001",
82
+ space_id="space-demo-001",
83
+ topic="task.dispatch",
84
+ message_type="task.created",
85
+ )
86
+
87
+ logger.info(
88
+ "开始处理任务",
89
+ extra={
90
+ "duration_ms": 12,
91
+ "request_payload": {
92
+ "token": "abcd1234567890",
93
+ "email": "demo@example.com",
94
+ },
95
+ },
96
+ )
97
+
98
+ clear_log_context()
99
+ ```
100
+
101
+ ## 标准字段
102
+
103
+ SDK 默认统一输出以下字段:
104
+
105
+ 1. `timestamp`
106
+ 2. `level`
107
+ 3. `service`
108
+ 4. `environment`
109
+ 5. `module`
110
+ 6. `message`
111
+ 7. `trace_id`
112
+ 8. `task_id`
113
+ 9. `space_id`
114
+ 10. `message_type`
115
+ 11. `topic`
116
+ 12. `consumer_group`
117
+ 13. `worker_type`
118
+ 14. `region`
119
+ 15. `duration_ms`
120
+ 16. `error_code`
121
+ 17. `error`
122
+
123
+ ## 输出方式
124
+
125
+ ### 1. 控制台输出
126
+
127
+ ```python
128
+ setup_logging(
129
+ service_name="schedule-task",
130
+ environment="dev",
131
+ )
132
+ ```
133
+
134
+ ### 2. 文件日志
135
+
136
+ ```python
137
+ setup_logging(
138
+ service_name="extractors",
139
+ environment="dev",
140
+ enable_file=True,
141
+ log_file_path="logs/extractors.log",
142
+ file_max_bytes=50 * 1024 * 1024,
143
+ file_backup_count=5,
144
+ )
145
+ ```
146
+
147
+ ### 3. Logstash 输出
148
+
149
+ ```python
150
+ setup_logging(
151
+ service_name="tf-data",
152
+ environment="prod",
153
+ enable_logstash=True,
154
+ logstash_host="127.0.0.1",
155
+ logstash_port=5959,
156
+ )
157
+ ```
158
+
159
+ ## 上下文注入
160
+
161
+ ```python
162
+ from tf_logging_sdk import bind_log_context, clear_log_context
163
+
164
+ bind_log_context(
165
+ trace_id="trace-001",
166
+ task_id="task-001",
167
+ topic="task.dispatch",
168
+ message_type="task.created",
169
+ consumer_group="group-task",
170
+ worker_type="consumer",
171
+ )
172
+
173
+ clear_log_context()
174
+ ```
175
+
176
+ SDK 基于 `contextvars` 管理上下文,避免不同线程或异步任务串线。
177
+
178
+ ## 脱敏说明
179
+
180
+ 默认脱敏字段:
181
+
182
+ 1. `password`
183
+ 2. `token`
184
+ 3. `authorization`
185
+ 4. `cookie`
186
+ 5. `secret`
187
+ 6. `access_key`
188
+ 7. `proxy_password`
189
+ 8. `phone`
190
+ 9. `email`
191
+
192
+ 扩展示例:
193
+
194
+ ```python
195
+ setup_logging(
196
+ service_name="demo-service",
197
+ environment="test",
198
+ extra_mask_fields=["session_id", "private_key"],
199
+ )
200
+ ```
201
+
202
+ ## 项目结构
203
+
204
+ ```text
205
+ tf_logging_sdk/
206
+ ├── examples/
207
+ ├── src/
208
+ │ └── tf_logging_sdk/
209
+ ├── LICENSE
210
+ ├── MANIFEST.in
211
+ ├── README.md
212
+ ├── pyproject.toml
213
+ ├── 统一日志SDK设计说明.md
214
+ ├── 统一日志SDK接入指南.md
215
+ └── 统一日志SDK验收记录.md
216
+ ```
217
+
218
+ ## 文档
219
+
220
+ 1. [统一日志SDK设计说明.md](./统一日志SDK设计说明.md)
221
+ 2. [统一日志SDK接入指南.md](./统一日志SDK接入指南.md)
222
+ 3. [统一日志SDK验收记录.md](./统一日志SDK验收记录.md)
223
+
224
+ ## 本地验证
225
+
226
+ ```bash
227
+ python -m compileall src/tf_logging_sdk
228
+ python -m tf_logging_sdk.examples.self_check
229
+ ```
230
+
231
+ 说明:
232
+
233
+ 1. `self_check.py` 用于验证标准字段、上下文注入、文件输出与脱敏结果
234
+ 2. 若按 `src` 布局直接执行模块,建议先执行 `pip install -e .`
@@ -0,0 +1,11 @@
1
+ tf_logging_sdk/__init__.py,sha256=HVL_VC9X92W7ZKPNewzgb23aaswjqi-Qy1twQPDwgaU,465
2
+ tf_logging_sdk/config.py,sha256=7N32YrIGGQ9caKGgmphcF7SaxwOj2_IB-4MwY7RvnBU,3156
3
+ tf_logging_sdk/context.py,sha256=pQO-u7NohjnjkPMK_ZQxp9dNSlbQY3kiEwfgtvb8hZ8,1689
4
+ tf_logging_sdk/filters.py,sha256=jfSEmzJtMzcVpWxN-1tjz8EVVs_d3spjfbf_jTlLhIc,4421
5
+ tf_logging_sdk/formatter.py,sha256=KsIv64X3ozrWJEZSZdNZ1TM0TnuxZX8lFMPtcdR46O4,2766
6
+ tf_logging_sdk/handlers.py,sha256=p7fY82g1KvPFGLwX6gkyhQZBBzlfJIlVBbxuj9vkUY8,5953
7
+ tf_logging_sdk/masking.py,sha256=2O7jmSJ1yhXXvnVzJ8ke-64sRoMNtFEA14pUlEeF0Zc,3896
8
+ tf_logging_sdk-0.1.0.dist-info/METADATA,sha256=uGz3zOZ20JpfNi1eDJffYuh1AuA7BGyaJ9GcwfsWcG4,5321
9
+ tf_logging_sdk-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
10
+ tf_logging_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=s_9fH4NLv8u3__w4WywNaIPLI8OD3gKIJ7Zjc35Bjac,1063
11
+ tf_logging_sdk-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.29.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 tfkxsx
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.