Metadata-Version: 2.4
Name: yai-loguru-sinks
Version: 0.6.3
Summary: 企业级 Loguru Sink 工厂，基于 loguru-config 的简洁架构，专注于阿里云 SLS 支持
Project-URL: Homepage, https://github.com/your-org/yai-loguru-sinks
Project-URL: Repository, https://github.com/your-org/yai-loguru-sinks
Project-URL: Documentation, https://github.com/your-org/yai-loguru-sinks#readme
Project-URL: Issues, https://github.com/your-org/yai-loguru-sinks/issues
Author-email: Harry Tang <harry@example.com>
License: MIT
Keywords: aliyun,enterprise,logging,loguru,sink,sls
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Logging
Requires-Python: >=3.10
Requires-Dist: aliyun-log-python-sdk>=0.8.0
Requires-Dist: loguru-config>=0.1.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pytest>=8.3.5
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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