# yai-loguru-sinks
企业级 Loguru Sink 工厂库，基于 `loguru-config` 提供统一的配置驱动体验。
## 核心理念
- **简洁架构**：移除复杂的插件抽象，直接提供 sink 工厂函数
- **配置驱动**：基于 `loguru-config` 的统一配置体验
- **企业级**：专注于阿里云 SLS 日志服务，未来扩展更多云服务
- **原生兼容**：完全兼容 Loguru 的 sink 机制
## 快速开始
### 安装
```bash
uv add yai-loguru-sinks
```
### 基本使用
```python
from yai_loguru_sinks import register_protocol_parsers, create_config_from_file
# 注册企业级协议解析器
register_protocol_parsers()
# 配置驱动，一行搞定
create_config_from_file('logging.yaml')
```
### 配置文件示例
```yaml
# logging.yaml
handlers:
# 阿里云 SLS
- sink: sls://my-project/my-logstore?region=cn-hangzhou&access_key_id=${SLS_ACCESS_KEY}&access_key_secret=${SLS_SECRET}
level: WARNING
format: '{time} | {level} | {message}'
# 本地文件（Loguru 原生）
- sink: logs/app.log
rotation: "1 day"
retention: "30 days"
compression: "gz"
```
## 支持的协议
### 阿里云 SLS
```yaml
sink: sls://project/logstore?region=cn-hangzhou&access_key_id=xxx&access_key_secret=xxx
```
**参数说明：**
- `project`: SLS 项目名称
- `logstore`: SLS 日志库名称
- `region`: 阿里云地域（如 cn-hangzhou）
- `access_key_id`: 阿里云访问密钥 ID
- `access_key_secret`: 阿里云访问密钥 Secret
**环境变量支持：**
```yaml
sink: sls://my-project/my-logstore?region=cn-hangzhou&access_key_id=${SLS_ACCESS_KEY}&access_key_secret=${SLS_SECRET}
```
## API 参考
### 核心函数
#### `register_protocol_parsers()`
注册所有支持的协议解析器（SLS、CloudWatch、Elasticsearch、Kafka 等）。
```python
from yai_loguru_sinks import register_protocol_parsers
# 注册协议解析器
register_protocol_parsers()
```
#### `create_config_from_file(config_path: str)`
从 YAML/JSON 配置文件加载日志配置。
```python
from yai_loguru_sinks import create_config_from_file
# 从文件加载配置
create_config_from_file('logging.yaml')
```
#### `create_config_from_dict(config_dict: dict)`
从字典对象加载日志配置。
```python
from yai_loguru_sinks import create_config_from_dict
config = {
"handlers": [
{
"sink": "sls://my-project/my-logstore?region=cn-hangzhou",
"level": "INFO"
}
]
}
create_config_from_dict(config)
```
## 直接使用 Sink 工厂
如果不使用配置文件，也可以直接调用内部的 sink 工厂：
```python
from loguru import logger
from yai_loguru_sinks.internal.factory import create_sls_sink
# 创建 SLS sink
sls_sink = create_sls_sink(
project="my-project",
logstore="my-logstore",
region="cn-hangzhou",
access_key_id="xxx",
access_key_secret="xxx"
)
# 添加到 logger
logger.add(sls_sink, level="WARNING")
```
## 特性功能
### PackId 支持
自动为每个日志记录生成唯一的 PackId，便于日志关联和追踪。
### 异步处理
高性能异步日志发送，不阻塞主线程。
### 优雅降级
当云服务不可用时，自动降级到本地文件日志。
### 环境变量支持
配置文件中可以使用 `${VAR_NAME}` 语法引用环境变量。
## 架构优势
### 相比传统插件系统
- ✅ **移除冗余抽象**：不再需要 `LoguruPlugin` 基类
- ✅ **简化使用方式**：统一的配置文件格式
- ✅ **利用成熟生态**：基于 `loguru-config` 的稳定基础
- ✅ **保持功能完整**：所有企业级功能都保留
### 设计原则
1. **职责分离**：`loguru` 负责基础功能，`yai-loguru-sinks` 负责企业级扩展
2. **配置驱动**：通过 YAML/JSON 配置，而非代码硬编码
3. **协议扩展**：利用 `loguru-config` 的协议解析机制
4. **工厂模式**：提供灵活的 sink 创建函数
## 许可证
MIT License
Raw data
{
"_id": null,
"home_page": null,
"name": "yai-loguru-sinks",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "aliyun, enterprise, logging, loguru, sink, sls",
"author": null,
"author_email": "Harry Tang <harry@example.com>",
"download_url": "https://files.pythonhosted.org/packages/37/f7/08d11db050dbc3b8f9adde5327462734aeb2fdb56d37e702b367ec4e151f/yai_loguru_sinks-0.6.2.tar.gz",
"platform": null,
"description": "# yai-loguru-sinks\n\n\u4f01\u4e1a\u7ea7 Loguru Sink \u5de5\u5382\u5e93\uff0c\u57fa\u4e8e `loguru-config` \u63d0\u4f9b\u7edf\u4e00\u7684\u914d\u7f6e\u9a71\u52a8\u4f53\u9a8c\u3002\n\n## \u6838\u5fc3\u7406\u5ff5\n\n- **\u7b80\u6d01\u67b6\u6784**\uff1a\u79fb\u9664\u590d\u6742\u7684\u63d2\u4ef6\u62bd\u8c61\uff0c\u76f4\u63a5\u63d0\u4f9b sink \u5de5\u5382\u51fd\u6570\n- **\u914d\u7f6e\u9a71\u52a8**\uff1a\u57fa\u4e8e `loguru-config` \u7684\u7edf\u4e00\u914d\u7f6e\u4f53\u9a8c\n- **\u4f01\u4e1a\u7ea7**\uff1a\u4e13\u6ce8\u4e8e\u963f\u91cc\u4e91 SLS \u65e5\u5fd7\u670d\u52a1\uff0c\u672a\u6765\u6269\u5c55\u66f4\u591a\u4e91\u670d\u52a1\n- **\u539f\u751f\u517c\u5bb9**\uff1a\u5b8c\u5168\u517c\u5bb9 Loguru \u7684 sink \u673a\u5236\n\n## \u5feb\u901f\u5f00\u59cb\n\n### \u5b89\u88c5\n\n```bash\nuv add yai-loguru-sinks\n```\n\n### \u57fa\u672c\u4f7f\u7528\n\n```python\nfrom yai_loguru_sinks import register_protocol_parsers, create_config_from_file\n\n# \u6ce8\u518c\u4f01\u4e1a\u7ea7\u534f\u8bae\u89e3\u6790\u5668\nregister_protocol_parsers()\n\n# \u914d\u7f6e\u9a71\u52a8\uff0c\u4e00\u884c\u641e\u5b9a\ncreate_config_from_file('logging.yaml')\n```\n\n### \u914d\u7f6e\u6587\u4ef6\u793a\u4f8b\n\n```yaml\n# logging.yaml\nhandlers:\n # \u963f\u91cc\u4e91 SLS\n - sink: sls://my-project/my-logstore?region=cn-hangzhou&access_key_id=${SLS_ACCESS_KEY}&access_key_secret=${SLS_SECRET}\n level: WARNING\n format: '{time} | {level} | {message}'\n \n # \u672c\u5730\u6587\u4ef6\uff08Loguru \u539f\u751f\uff09\n - sink: logs/app.log\n rotation: \"1 day\"\n retention: \"30 days\"\n compression: \"gz\"\n```\n\n## \u652f\u6301\u7684\u534f\u8bae\n\n### \u963f\u91cc\u4e91 SLS\n```yaml\nsink: sls://project/logstore?region=cn-hangzhou&access_key_id=xxx&access_key_secret=xxx\n```\n\n**\u53c2\u6570\u8bf4\u660e\uff1a**\n- `project`: SLS \u9879\u76ee\u540d\u79f0\n- `logstore`: SLS \u65e5\u5fd7\u5e93\u540d\u79f0 \n- `region`: \u963f\u91cc\u4e91\u5730\u57df\uff08\u5982 cn-hangzhou\uff09\n- `access_key_id`: \u963f\u91cc\u4e91\u8bbf\u95ee\u5bc6\u94a5 ID\n- `access_key_secret`: \u963f\u91cc\u4e91\u8bbf\u95ee\u5bc6\u94a5 Secret\n\n**\u73af\u5883\u53d8\u91cf\u652f\u6301\uff1a**\n```yaml\nsink: sls://my-project/my-logstore?region=cn-hangzhou&access_key_id=${SLS_ACCESS_KEY}&access_key_secret=${SLS_SECRET}\n```\n\n## API \u53c2\u8003\n\n### \u6838\u5fc3\u51fd\u6570\n\n#### `register_protocol_parsers()`\n\u6ce8\u518c\u6240\u6709\u652f\u6301\u7684\u534f\u8bae\u89e3\u6790\u5668\uff08SLS\u3001CloudWatch\u3001Elasticsearch\u3001Kafka \u7b49\uff09\u3002\n\n```python\nfrom yai_loguru_sinks import register_protocol_parsers\n\n# \u6ce8\u518c\u534f\u8bae\u89e3\u6790\u5668\nregister_protocol_parsers()\n```\n\n#### `create_config_from_file(config_path: str)`\n\u4ece YAML/JSON \u914d\u7f6e\u6587\u4ef6\u52a0\u8f7d\u65e5\u5fd7\u914d\u7f6e\u3002\n\n```python\nfrom yai_loguru_sinks import create_config_from_file\n\n# \u4ece\u6587\u4ef6\u52a0\u8f7d\u914d\u7f6e\ncreate_config_from_file('logging.yaml')\n```\n\n#### `create_config_from_dict(config_dict: dict)`\n\u4ece\u5b57\u5178\u5bf9\u8c61\u52a0\u8f7d\u65e5\u5fd7\u914d\u7f6e\u3002\n\n```python\nfrom yai_loguru_sinks import create_config_from_dict\n\nconfig = {\n \"handlers\": [\n {\n \"sink\": \"sls://my-project/my-logstore?region=cn-hangzhou\",\n \"level\": \"INFO\"\n }\n ]\n}\ncreate_config_from_dict(config)\n```\n\n## \u76f4\u63a5\u4f7f\u7528 Sink \u5de5\u5382\n\n\u5982\u679c\u4e0d\u4f7f\u7528\u914d\u7f6e\u6587\u4ef6\uff0c\u4e5f\u53ef\u4ee5\u76f4\u63a5\u8c03\u7528\u5185\u90e8\u7684 sink \u5de5\u5382\uff1a\n\n```python\nfrom loguru import logger\nfrom yai_loguru_sinks.internal.factory import create_sls_sink\n\n# \u521b\u5efa SLS sink\nsls_sink = create_sls_sink(\n project=\"my-project\",\n logstore=\"my-logstore\",\n region=\"cn-hangzhou\",\n access_key_id=\"xxx\",\n access_key_secret=\"xxx\"\n)\n\n# \u6dfb\u52a0\u5230 logger\nlogger.add(sls_sink, level=\"WARNING\")\n```\n\n## \u7279\u6027\u529f\u80fd\n\n### PackId \u652f\u6301\n\u81ea\u52a8\u4e3a\u6bcf\u4e2a\u65e5\u5fd7\u8bb0\u5f55\u751f\u6210\u552f\u4e00\u7684 PackId\uff0c\u4fbf\u4e8e\u65e5\u5fd7\u5173\u8054\u548c\u8ffd\u8e2a\u3002\n\n### \u5f02\u6b65\u5904\u7406\n\u9ad8\u6027\u80fd\u5f02\u6b65\u65e5\u5fd7\u53d1\u9001\uff0c\u4e0d\u963b\u585e\u4e3b\u7ebf\u7a0b\u3002\n\n### \u4f18\u96c5\u964d\u7ea7\n\u5f53\u4e91\u670d\u52a1\u4e0d\u53ef\u7528\u65f6\uff0c\u81ea\u52a8\u964d\u7ea7\u5230\u672c\u5730\u6587\u4ef6\u65e5\u5fd7\u3002\n\n### \u73af\u5883\u53d8\u91cf\u652f\u6301\n\u914d\u7f6e\u6587\u4ef6\u4e2d\u53ef\u4ee5\u4f7f\u7528 `${VAR_NAME}` \u8bed\u6cd5\u5f15\u7528\u73af\u5883\u53d8\u91cf\u3002\n\n## \u67b6\u6784\u4f18\u52bf\n\n### \u76f8\u6bd4\u4f20\u7edf\u63d2\u4ef6\u7cfb\u7edf\n- \u2705 **\u79fb\u9664\u5197\u4f59\u62bd\u8c61**\uff1a\u4e0d\u518d\u9700\u8981 `LoguruPlugin` \u57fa\u7c7b\n- \u2705 **\u7b80\u5316\u4f7f\u7528\u65b9\u5f0f**\uff1a\u7edf\u4e00\u7684\u914d\u7f6e\u6587\u4ef6\u683c\u5f0f\n- \u2705 **\u5229\u7528\u6210\u719f\u751f\u6001**\uff1a\u57fa\u4e8e `loguru-config` \u7684\u7a33\u5b9a\u57fa\u7840\n- \u2705 **\u4fdd\u6301\u529f\u80fd\u5b8c\u6574**\uff1a\u6240\u6709\u4f01\u4e1a\u7ea7\u529f\u80fd\u90fd\u4fdd\u7559\n\n### \u8bbe\u8ba1\u539f\u5219\n1. **\u804c\u8d23\u5206\u79bb**\uff1a`loguru` \u8d1f\u8d23\u57fa\u7840\u529f\u80fd\uff0c`yai-loguru-sinks` \u8d1f\u8d23\u4f01\u4e1a\u7ea7\u6269\u5c55\n2. **\u914d\u7f6e\u9a71\u52a8**\uff1a\u901a\u8fc7 YAML/JSON \u914d\u7f6e\uff0c\u800c\u975e\u4ee3\u7801\u786c\u7f16\u7801\n3. **\u534f\u8bae\u6269\u5c55**\uff1a\u5229\u7528 `loguru-config` \u7684\u534f\u8bae\u89e3\u6790\u673a\u5236\n4. **\u5de5\u5382\u6a21\u5f0f**\uff1a\u63d0\u4f9b\u7075\u6d3b\u7684 sink \u521b\u5efa\u51fd\u6570\n\n## \u8bb8\u53ef\u8bc1\n\nMIT License",
"bugtrack_url": null,
"license": "MIT",
"summary": "\u4f01\u4e1a\u7ea7 Loguru Sink \u5de5\u5382\uff0c\u57fa\u4e8e loguru-config \u7684\u7b80\u6d01\u67b6\u6784\uff0c\u4e13\u6ce8\u4e8e\u963f\u91cc\u4e91 SLS \u652f\u6301",
"version": "0.6.2",
"project_urls": {
"Documentation": "https://github.com/your-org/yai-loguru-sinks#readme",
"Homepage": "https://github.com/your-org/yai-loguru-sinks",
"Issues": "https://github.com/your-org/yai-loguru-sinks/issues",
"Repository": "https://github.com/your-org/yai-loguru-sinks"
},
"split_keywords": [
"aliyun",
" enterprise",
" logging",
" loguru",
" sink",
" sls"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "fd2d03bc3c91c84e7aefa216b4236e62aea32ec58a4202681230e03a218be51e",
"md5": "77c961a6796204c1b18a0d2d98ab64b7",
"sha256": "65a847a13f2517e89104b87fd9b75fdf7c22b83b1c79ccc6349019633e89e336"
},
"downloads": -1,
"filename": "yai_loguru_sinks-0.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "77c961a6796204c1b18a0d2d98ab64b7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 15327,
"upload_time": "2025-07-26T09:08:36",
"upload_time_iso_8601": "2025-07-26T09:08:36.493699Z",
"url": "https://files.pythonhosted.org/packages/fd/2d/03bc3c91c84e7aefa216b4236e62aea32ec58a4202681230e03a218be51e/yai_loguru_sinks-0.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "37f708d11db050dbc3b8f9adde5327462734aeb2fdb56d37e702b367ec4e151f",
"md5": "0fb41bf3ff4021f911c0eb1ae3255f1b",
"sha256": "a2278bb69dc130d7f8d81c3b304e98db87f7c69799b5f37da1b8dc6c0f130c95"
},
"downloads": -1,
"filename": "yai_loguru_sinks-0.6.2.tar.gz",
"has_sig": false,
"md5_digest": "0fb41bf3ff4021f911c0eb1ae3255f1b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 103963,
"upload_time": "2025-07-26T09:08:37",
"upload_time_iso_8601": "2025-07-26T09:08:37.598933Z",
"url": "https://files.pythonhosted.org/packages/37/f7/08d11db050dbc3b8f9adde5327462734aeb2fdb56d37e702b367ec4e151f/yai_loguru_sinks-0.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-26 09:08:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-org",
"github_project": "yai-loguru-sinks#readme",
"github_not_found": true,
"lcname": "yai-loguru-sinks"
}
JSON
