# slogx

**Repository Path**: kingdix10/slogx

## Basic Information

- **Project Name**: slogx
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-26
- **Last Updated**: 2026-06-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# slogx

工业级结构化日志库，面向多层架构、多交互方式的 Python 应用。零强制依赖。

## 安装

```bash
pip install slogx
```

## 使用

### 三步接入

```python
from slogx import init_logging, get_logger, LogContext

# 1. 入口初始化（零参数 = DEBUG → stderr）
init_logging()

# 2. 各模块获取 logger
logger = get_logger(__name__)
logger.info("app started")

# 3. 交互层入口设置上下文，trace_id 自动贯穿全链路
with LogContext.scope(channel="rest", user_id="u_123"):
    logger.info("request received")       # 日志自动带 trace_id
```

### 配置选择

```python
# 零配置：读 SLOGX_ENV 环境变量（默认 "dev"）
init_logging()

# 环境名：加载 config/logging_prod.yaml，找不到用内置默认
init_logging("prod")

# YAML 文件路径
init_logging("/etc/myapp/logging.yaml")

# 自定义配置目录和环境变量
init_logging("prod", config_dir="/etc/myapp", env_var="MY_ENV")

# Python dict
init_logging({"version": 1, "handlers": {...}, "loggers": {...}})
```

### 预设组合

不写 YAML，用预设拼出配置：

```python
from slogx.presets import (
    dev, prod, file_rotating, error_log, as_json, as_color, mask_pii_cn, quiet_3rd,
)

# 开发 + 脱敏 + 彩色
init_logging(dev() + as_color() + mask_pii_cn())

# 生产：JSON + 文件轮转 + 错误分离
init_logging(
    prod()
    + as_json()
    + file_rotating("/var/log/app.log")
    + error_log("/var/log/error.log")
    + quiet_3rd()
)

# YAML 底座 + 预设覆盖
init_logging("prod", extras=file_rotating("/data/logs/app.log") + quiet_3rd("boto3"))
```

### LogContext：请求追踪

`LogContext.set()` 将上下文存入当前协程/线程（`contextvars`），`ContextFilter` 自动注入每条日志。推荐 `scope()` 上下文管理器，退出自动清理，异常安全：

```python
# 同步
with LogContext.scope(channel="rest", user_id="u_123"):
    handle_request()

# 异步
async with LogContext.scope(channel="ws"):
    await handle_message()

# 自定义字段
LogContext.register_field("tenant_id")
with LogContext.scope(channel="cli", tenant_id="acme"):
    ...
```

`set()` / `clear()` 手动管理依然可用。

### 日志输出

```python
logger = get_logger(__name__)

logger.debug("variable x=%s", x)       # 仅开发环境
logger.info("order created")           # 关键业务节点
logger.warning("cache miss")           # 预期异常
logger.error("db timeout")             # 单次失败
logger.exception("unhandled")          # 自动带完整堆栈
```

### 终端彩色输出

`AnsiStyle` + `Styler` 同时支持日志着色和 CLI `print`，零依赖：

```python
from slogx.presets import dev, as_color
from slogx import AnsiStyle, Styler

# 日志着色
init_logging(dev() + as_color())

# CLI print 着色
ok   = Styler(AnsiStyle.FG_GREEN, AnsiStyle.BOLD)
warn = Styler(AnsiStyle.FG_YELLOW)
err  = Styler(AnsiStyle.FG_RED)

print(ok("success"))
print(err("failure"))
```

非 TTY 或设置 `NO_COLOR` 环境变量自动回退纯文本。

### 调试工具

```python
from slogx import dump_stack, dump_exc

def tricky():
    dump_stack("why am I here?")     # 打印当前调用栈 + 日志
    dump_exc("unexpected")           # 打印异常信息 + 日志
```

### structlog 集成（可选）

安装 `pip install slogx[structlog]`，参数顺序与 `init_logging` 一致：

```python
from slogx.structlog import init_structlog, get_structlog
from slogx.presets import dev, mask_sensitive

init_structlog(dev() + mask_sensitive())
log = get_structlog("myapp")

# 关键字参数 = 结构化字段
log.info("order created", order_id="001")

# 绑定上下文
log = log.bind(user_id="u_1")
log.info("step 1")
```

兼容：预设组合、YAML 配置、`extras` 叠加、`LogContext.scope()`、`mask_sensitive`、`limit_rate`、`quiet_3rd`、`by_module`、`test_quiet`、文件轮转、syslog、ring_buffer——全部可用。

不兼容：`as_color()` 和 `fmt_text()` 无效（structlog 自行控制颜色和格式）。`get_logger` 不可混用，用 `get_structlog`。

**标准 logging 下兼容 structlog 代码**：调用 `enable_structlog_compat()` 给 `logging.Logger` 加上空的 `bind()`/`unbind()`，使 structlog 链式调用在标准模式下不报错：

```python
from slogx import enable_structlog_compat, init_logging, get_logger

enable_structlog_compat()
init_logging()
get_logger(__name__).bind(user_id="123").info("hello")  # OK
```

## 预设列表

| 预设 | 场景 | 说明 |
|------|------|------|
| `dev()` | 本地开发 | DEBUG → stderr |
| `prod()` | 生产环境 | INFO → stderr |
| `to_stdout()` | Docker / K8s / systemd | 控制台从 stderr 切到 stdout |
| `file_rotating(path)` | 生产持久化 | 按大小轮转（~50MB），path 必传 |
| `file_daily(path)` | 按天归档 | 按天轮转，path 必传 |
| `error_log(path)` | 告警链路 | ERROR 级别独立文件，path 必传 |
| `to_syslog(address)` | Linux 服务器 | 接入系统 syslog |
| `ring_buffer(maxlen)` | GUI 桌面应用 | 内存环形缓冲，供日志面板轮询 |
| `as_color()` | CLI / TUI | ANSI 彩色控制台输出 |
| `as_json()` | 日志采集 | 控制台切 JSON Lines（文件类默认 JSON） |
| `fmt_text("compact")` | 调试排查 | 格式预设：default / simple / compact / trace |
| `mask_sensitive(keys, patterns, marker)` | 合规 | 自定义脱敏字段和正则 |
| `mask_pii_cn()` | 中国合规 | 手机号+身份证号脱敏 |
| `limit_rate(window, max)` | 高频防刷 | 按窗口限流，丢弃并定期报告 |
| `quiet_3rd(*names)` | 减少噪音 | 第三方库日志升至 WARNING |
| `by_module(app__logic="DEBUG")` | 局部调试 | 按模块调级别，`__` 映射 `.` |
| `test_quiet()` | CI / pytest | 根 logger 升至 ERROR，测试输出干净 |

## 示例

```bash
cd slogx
python examples/basic.py              # 零配置 + 彩色 + CLI print 着色
python examples/cli_color.py          # CLI 工具彩色输出完整示例
python examples/layered_app.py        # 多层架构 trace_id 串联 + 自定义字段
python examples/proxy_tracing.py      # 跨进程 trace_id 传递模拟
python examples/pii_masking.py        # 敏感数据脱敏（内置 + 中国 PII + 自定义）
python examples/production.py         # 生产：JSON + 文件轮转 + 错误分离
python examples/fastapi_app.py        # FastAPI 集成（需 fastapi uvicorn）
python examples/advanced_task.py      # 高级：任务管线 + 脱敏 + 限流 + 调试
python examples/structlog_demo.py     # structlog 模式（需 pip install slogx[structlog]）
```