liblogging 0.1.13__tar.gz → 0.1.16__tar.gz

liblogging-0.1.16/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: liblogging
+Version: 0.1.16
+Summary: Utilities for logging and sending logs.
+Home-page: https://github.com/XoriieInpottn/liblogging
+Author: xi
+Author-email: gylv@mail.ustc.edu.cn, huangfuyb@163.com
+License: Apache-2.0 license
+Platform: any
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: collector
+Requires-Dist: kafka-python==2.0.2; extra == "collector"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: platform
+Dynamic: provides-extra
+Dynamic: summary
+
+# liblogging
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/XoriieInpottn/liblogging)
+
+Utilities for logging and sending logs.
+```shell
+pip install liblogging
+```
+
+## 🌟Feature
+### 统一日志格式记录
+统一了当前agent的日志记录格式，也可自己基于默认格式进行拓展。
+当前记录的信息和对应的key如下：
+```python
+{
+    "create_time": "时间戳，默认和mysql列datatime(3)保持一致",
+    "level": "like INFO, ERROR, WARNING",
+    # 通过上下文变量保存trace_id
+    "trace_id": "trace_id for 追溯不同服务的调用链路",
+    "line_info": "{record.filename}:{record.lineno}:{record.funcName}",
+    "message": message,
+    # 通过上下文变量区分不同源, 方便接收不同服务源信息, 比如Chat, Welcome, Planning等
+    "message_source": context.get("message_source", "chat_log"),
+    # 控制不同log类型，便于筛选日志数据, 比如tool, llm, turn等
+    "message_type": message_type,
+    # 可以根据自己需求加入其他的字段
+    **extra_message
+}
+```
+上述日志信息均以json字符串的形式记录下来，方便存储及后续处理。
+
+### 配置上下文变量，无须重复传参显示记录
+通过装饰器形式, 指定需要配置的全局上下文变量, 仅需在整个程序/服务入口配置一次即可。
+
+需要注意的是配置的全局上下文变量，根据加入装饰器下的函数入参名称匹配进行更新，推荐函数参数定义使用`BaseModel`。
+
+```python
+主程序/服务: service1.py
+from pydantic import BaseModel
+
+from liblogging import log_request,logger
+
+
+class Request(BaseModel):
+    name: str
+    trace_id: str
+
+#在主程序入口配置了trace_id这一全局上下文变量，会通过函数入参对该字段进行赋值，后续在该服务下的其他程序logger.info时会读取这一变量并记录下来。
+#同时也支持默认参数配置，比如message_source设置了默认值，后续使用logger会记录message_source为"demo"。
+@log_request("trace_id", message_source="demo")
+def your_service_entry(request: Request):
+    logger.info("Processing request")
+```
+
+```python
+该服务下的其他程序: function1.py，可直接logger.info(). trace_id, message_source均会记录下来。
+from liblogging import logger
+
+def test(name):
+    logger.info(f"Testing {name}")
+```
+
+### 重定向并发送到消息队列
+以默认集成的kafka为例，可将上述统一日志格式记录的形式发送至kafka。
+
+kafka 配置文件格式：
+```json
+{
+    "{cluster_name}": {
+        "{env_name}": {
+            "bootstrap_servers": "server1, server2, server3",
+            "username": "username",
+            "password": "******",
+            "topic": "your topic",
+            "...": "..."
+        }
+    }
+}
+```
+
+使用形式:
+```shell
+python -u service 2>&1 | tee {log_file_path} | liblogging_collector --config-path {your_kafka_path}  --ssl-cafile {your_ssl_cafile_path} --send-kafka
+```
+tee {log_file_path} 可以将你的程序记录（输出+错误）重定向到文件中（可选）。
+
+[log_collector.py](liblogging/sending/log_collector.py)为`liblogging_collector`的源代码地址。
+
+`env_name`不指定的话，默认读取`os.environ.get("CHAT_ENV", "dev")`.
+
+## 📋Example
+增加额外记录字段信息，以及搭配[libentry](https://github.com/XoriieInpottn/libentry)使用的样例见 [example](example)。
+
+
+## 💡Tips
+
+1. If using Kafka to send messages, please use `pip install liblogging[collector]`.
+2. 如果需要数据持久化，推荐日志消息都写在message列中，维护一列节省内存空间。需要后续进行查询的，以字典形式记录，比如logger.info({"key": "value"}), 便于后续查找。
+
+3. 当前默认的trace_id，推荐使用[liblogging/util.py](liblogging/util.py)中的`get_trace_id`函数，该函数会根据请求对象的`uid`, `session_id`, `turn`等字段生成trace_id，默认的[liblogging/sending/log_collector.py](liblogging/sending/log_collector.py)也会根据trace_id拆解`uid`, `session_id`, `turn`，根据`create_time`拆解`create_date`，方便后续进行追溯以及数据存储。以下是构建trace_id的在整个服务入口的示例：
+```python
+from liblogging.util import get_trace_id
+
+class Request(BaseModel):
+    uid: str = Field(..., description="用户id")
+    session_id: str = Field(..., description="会话id")
+    turn: int = Field(..., description="轮次")
+    trace_id: str = Field(..., description="trace_id")
+
+@log_request("trace_id", "message_source")
+def set_logger_global_vars(trace_id: str, message_source: str):
+    print(f"setting global vars: trace_id={trace_id}, message_source={message_source}")
+
+def run():
+    trace_id = get_trace_id(request)
+    # 设置全局上下文变量, 这里注意需要以trace_id=xxx, message_source=xxx形式显式传入
+    set_logger_global_vars(trace_id=trace_id, message_source="demo")
+    request.trace_id = trace_id
+    # 可以直接给其他服务传入request对象，后续的logger.info会自动记录trace_id，其他服务需要在服务入口使用@log_request装饰器配置trace_id, message_source等全局上下文变量。可见example/service.py
+    your_service_entry(request)
+
+if __name__ == "__main__":
+    run()
+```
+
+4. liblogging提供了一些常用的，比如logger.tool_start, logger.tool_end, logger.track_start, logger.track_end等。
+
+    (1) 默认message列就是当使用`logger.info(<message>)`时，message的值。
+
+    (2) 从本质上可以理解为当info的内容是字典时，字典的key就是表中的列名，value就是列的值，而使用liblogging默认这一套 `trace_id`, ``create_time`, `create_date`, `uid`, `session_id`, `turn`等字段会自动添加.
+
+    (3) 如果需要统计相应的字段推荐这种方式，方便后续进行查询。
+```python
+logger.info({
+    "message": {"key1": "value1", "key2": "value2"},  # message列的内容，liblogging将json序列化后存储
+    "message_type": "<your message_type>"  # message_type列方便后续进行查询
+})
+```
+
+
+由log_collector.py默认的数据表结构如下（如果有额外的字段，创建表时和log时的key保持一致即可）：
+```sql
+CREATE TABLE `agent_log`.`your_table_name(需要和message_source一致)` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+  `uid` varchar(64) NOT NULL DEFAULT '',
+  `session_id` varchar(128) NOT NULL DEFAULT '',
+  `turn` smallint NOT NULL DEFAULT '0',
+  `trace_id` varchar(255) NOT NULL DEFAULT '',
+  `create_date` date NOT NULL,
+  `create_time` datetime(3) NOT NULL,
+  `insert_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '插入时间',
+  `line_info` varchar(255) NOT NULL DEFAULT '' COMMENT '对应代码行信息',
+  `message_source` varchar(64) NOT NULL DEFAULT '' COMMENT '消息来源：plan, memory, intent, guess question等，对应表名',
+  `message_type` varchar(32) NOT NULL DEFAULT '' COMMENT '消息类型, 可以筛选该key获取相关指标信息',
+  `message` text,
+  `level` varchar(32) NOT NULL DEFAULT '' COMMENT 'info， warning, error等',
+  PRIMARY KEY (`id`,`create_date`),
+  KEY `session_id_index` (`session_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
+PARTITION BY RANGE (TO_DAYS(create_date)) (
+    PARTITION p202507 VALUES LESS THAN (TO_DAYS('2025-08-01')),
+    PARTITION p202508 VALUES LESS THAN (TO_DAYS('2025-09-01')),
+    PARTITION p202509 VALUES LESS THAN (TO_DAYS('2025-10-01')),
+    PARTITION p202510 VALUES LESS THAN (TO_DAYS('2025-11-01')),
+    PARTITION p202511 VALUES LESS THAN (TO_DAYS('2025-12-01')),
+    PARTITION p202512 VALUES LESS THAN (TO_DAYS('2026-01-01')),
+    PARTITION p202601 VALUES LESS THAN (TO_DAYS('2026-02-01')),
+    PARTITION p202602 VALUES LESS THAN (TO_DAYS('2026-03-01')),
+    PARTITION p202603 VALUES LESS THAN (TO_DAYS('2026-04-01')),
+    PARTITION p202604 VALUES LESS THAN (TO_DAYS('2026-05-01')),
+    PARTITION p202605 VALUES LESS THAN (TO_DAYS('2026-06-01')),
+    PARTITION p202606 VALUES LESS THAN (TO_DAYS('2026-07-01')),
+    PARTITION p202607 VALUES LESS THAN (TO_DAYS('2026-08-01')),
+    PARTITION p202608 VALUES LESS THAN (TO_DAYS('2026-09-01')),
+    PARTITION p202609 VALUES LESS THAN (TO_DAYS('2026-10-01')),
+    PARTITION p202610 VALUES LESS THAN (TO_DAYS('2026-11-01')),
+    PARTITION p202611 VALUES LESS THAN (TO_DAYS('2026-12-01')),
+    PARTITION p202612 VALUES LESS THAN (TO_DAYS('2027-01-01')),
+    PARTITION pMaxRange VALUES LESS THAN MAXVALUE
+);
+```

liblogging-0.1.16/README.md

@@ -0,0 +1,180 @@
+# liblogging
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/XoriieInpottn/liblogging)
+
+Utilities for logging and sending logs.
+```shell
+pip install liblogging
+```
+
+## 🌟Feature
+### 统一日志格式记录
+统一了当前agent的日志记录格式，也可自己基于默认格式进行拓展。
+当前记录的信息和对应的key如下：
+```python
+{
+    "create_time": "时间戳，默认和mysql列datatime(3)保持一致",
+    "level": "like INFO, ERROR, WARNING",
+    # 通过上下文变量保存trace_id
+    "trace_id": "trace_id for 追溯不同服务的调用链路",
+    "line_info": "{record.filename}:{record.lineno}:{record.funcName}",
+    "message": message,
+    # 通过上下文变量区分不同源, 方便接收不同服务源信息, 比如Chat, Welcome, Planning等
+    "message_source": context.get("message_source", "chat_log"),
+    # 控制不同log类型，便于筛选日志数据, 比如tool, llm, turn等
+    "message_type": message_type,
+    # 可以根据自己需求加入其他的字段
+    **extra_message
+}
+```
+上述日志信息均以json字符串的形式记录下来，方便存储及后续处理。
+
+### 配置上下文变量，无须重复传参显示记录
+通过装饰器形式, 指定需要配置的全局上下文变量, 仅需在整个程序/服务入口配置一次即可。
+
+需要注意的是配置的全局上下文变量，根据加入装饰器下的函数入参名称匹配进行更新，推荐函数参数定义使用`BaseModel`。
+
+```python
+主程序/服务: service1.py
+from pydantic import BaseModel
+
+from liblogging import log_request,logger
+
+
+class Request(BaseModel):
+    name: str
+    trace_id: str
+
+#在主程序入口配置了trace_id这一全局上下文变量，会通过函数入参对该字段进行赋值，后续在该服务下的其他程序logger.info时会读取这一变量并记录下来。
+#同时也支持默认参数配置，比如message_source设置了默认值，后续使用logger会记录message_source为"demo"。
+@log_request("trace_id", message_source="demo")
+def your_service_entry(request: Request):
+    logger.info("Processing request")
+```
+
+```python
+该服务下的其他程序: function1.py，可直接logger.info(). trace_id, message_source均会记录下来。
+from liblogging import logger
+
+def test(name):
+    logger.info(f"Testing {name}")
+```
+
+### 重定向并发送到消息队列
+以默认集成的kafka为例，可将上述统一日志格式记录的形式发送至kafka。
+
+kafka 配置文件格式：
+```json
+{
+    "{cluster_name}": {
+        "{env_name}": {
+            "bootstrap_servers": "server1, server2, server3",
+            "username": "username",
+            "password": "******",
+            "topic": "your topic",
+            "...": "..."
+        }
+    }
+}
+```
+
+使用形式:
+```shell
+python -u service 2>&1 | tee {log_file_path} | liblogging_collector --config-path {your_kafka_path}  --ssl-cafile {your_ssl_cafile_path} --send-kafka
+```
+tee {log_file_path} 可以将你的程序记录（输出+错误）重定向到文件中（可选）。
+
+[log_collector.py](liblogging/sending/log_collector.py)为`liblogging_collector`的源代码地址。
+
+`env_name`不指定的话，默认读取`os.environ.get("CHAT_ENV", "dev")`.
+
+## 📋Example
+增加额外记录字段信息，以及搭配[libentry](https://github.com/XoriieInpottn/libentry)使用的样例见 [example](example)。
+
+
+## 💡Tips
+
+1. If using Kafka to send messages, please use `pip install liblogging[collector]`.
+2. 如果需要数据持久化，推荐日志消息都写在message列中，维护一列节省内存空间。需要后续进行查询的，以字典形式记录，比如logger.info({"key": "value"}), 便于后续查找。
+
+3. 当前默认的trace_id，推荐使用[liblogging/util.py](liblogging/util.py)中的`get_trace_id`函数，该函数会根据请求对象的`uid`, `session_id`, `turn`等字段生成trace_id，默认的[liblogging/sending/log_collector.py](liblogging/sending/log_collector.py)也会根据trace_id拆解`uid`, `session_id`, `turn`，根据`create_time`拆解`create_date`，方便后续进行追溯以及数据存储。以下是构建trace_id的在整个服务入口的示例：
+```python
+from liblogging.util import get_trace_id
+
+class Request(BaseModel):
+    uid: str = Field(..., description="用户id")
+    session_id: str = Field(..., description="会话id")
+    turn: int = Field(..., description="轮次")
+    trace_id: str = Field(..., description="trace_id")
+
+@log_request("trace_id", "message_source")
+def set_logger_global_vars(trace_id: str, message_source: str):
+    print(f"setting global vars: trace_id={trace_id}, message_source={message_source}")
+
+def run():
+    trace_id = get_trace_id(request)
+    # 设置全局上下文变量, 这里注意需要以trace_id=xxx, message_source=xxx形式显式传入
+    set_logger_global_vars(trace_id=trace_id, message_source="demo")
+    request.trace_id = trace_id
+    # 可以直接给其他服务传入request对象，后续的logger.info会自动记录trace_id，其他服务需要在服务入口使用@log_request装饰器配置trace_id, message_source等全局上下文变量。可见example/service.py
+    your_service_entry(request)
+
+if __name__ == "__main__":
+    run()
+```
+
+4. liblogging提供了一些常用的，比如logger.tool_start, logger.tool_end, logger.track_start, logger.track_end等。
+
+    (1) 默认message列就是当使用`logger.info(<message>)`时，message的值。
+
+    (2) 从本质上可以理解为当info的内容是字典时，字典的key就是表中的列名，value就是列的值，而使用liblogging默认这一套 `trace_id`, ``create_time`, `create_date`, `uid`, `session_id`, `turn`等字段会自动添加.
+
+    (3) 如果需要统计相应的字段推荐这种方式，方便后续进行查询。
+```python
+logger.info({
+    "message": {"key1": "value1", "key2": "value2"},  # message列的内容，liblogging将json序列化后存储
+    "message_type": "<your message_type>"  # message_type列方便后续进行查询
+})
+```
+
+
+由log_collector.py默认的数据表结构如下（如果有额外的字段，创建表时和log时的key保持一致即可）：
+```sql
+CREATE TABLE `agent_log`.`your_table_name(需要和message_source一致)` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+  `uid` varchar(64) NOT NULL DEFAULT '',
+  `session_id` varchar(128) NOT NULL DEFAULT '',
+  `turn` smallint NOT NULL DEFAULT '0',
+  `trace_id` varchar(255) NOT NULL DEFAULT '',
+  `create_date` date NOT NULL,
+  `create_time` datetime(3) NOT NULL,
+  `insert_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '插入时间',
+  `line_info` varchar(255) NOT NULL DEFAULT '' COMMENT '对应代码行信息',
+  `message_source` varchar(64) NOT NULL DEFAULT '' COMMENT '消息来源：plan, memory, intent, guess question等，对应表名',
+  `message_type` varchar(32) NOT NULL DEFAULT '' COMMENT '消息类型, 可以筛选该key获取相关指标信息',
+  `message` text,
+  `level` varchar(32) NOT NULL DEFAULT '' COMMENT 'info， warning, error等',
+  PRIMARY KEY (`id`,`create_date`),
+  KEY `session_id_index` (`session_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
+PARTITION BY RANGE (TO_DAYS(create_date)) (
+    PARTITION p202507 VALUES LESS THAN (TO_DAYS('2025-08-01')),
+    PARTITION p202508 VALUES LESS THAN (TO_DAYS('2025-09-01')),
+    PARTITION p202509 VALUES LESS THAN (TO_DAYS('2025-10-01')),
+    PARTITION p202510 VALUES LESS THAN (TO_DAYS('2025-11-01')),
+    PARTITION p202511 VALUES LESS THAN (TO_DAYS('2025-12-01')),
+    PARTITION p202512 VALUES LESS THAN (TO_DAYS('2026-01-01')),
+    PARTITION p202601 VALUES LESS THAN (TO_DAYS('2026-02-01')),
+    PARTITION p202602 VALUES LESS THAN (TO_DAYS('2026-03-01')),
+    PARTITION p202603 VALUES LESS THAN (TO_DAYS('2026-04-01')),
+    PARTITION p202604 VALUES LESS THAN (TO_DAYS('2026-05-01')),
+    PARTITION p202605 VALUES LESS THAN (TO_DAYS('2026-06-01')),
+    PARTITION p202606 VALUES LESS THAN (TO_DAYS('2026-07-01')),
+    PARTITION p202607 VALUES LESS THAN (TO_DAYS('2026-08-01')),
+    PARTITION p202608 VALUES LESS THAN (TO_DAYS('2026-09-01')),
+    PARTITION p202609 VALUES LESS THAN (TO_DAYS('2026-10-01')),
+    PARTITION p202610 VALUES LESS THAN (TO_DAYS('2026-11-01')),
+    PARTITION p202611 VALUES LESS THAN (TO_DAYS('2026-12-01')),
+    PARTITION p202612 VALUES LESS THAN (TO_DAYS('2027-01-01')),
+    PARTITION pMaxRange VALUES LESS THAN MAXVALUE
+);
+```

{liblogging-0.1.13 → liblogging-0.1.16}/liblogging/logger.py

@@ -48,12 +48,29 @@ except ImportError:
     tqdm = None
     from logging import StreamHandler
 
+_old_thread_init = threading.Thread.__init__
+
+
+def _wrapped_thread_init(self, *args, **kwargs):
+    co_local = thread_local._co_local.get()
+    if co_local is not None:
+        setattr(self, "_dict_for_logging", {**co_local})
+    return _old_thread_init(self, *args, **kwargs)
+
+
+threading.Thread.__init__ = _wrapped_thread_init
+
 
 class ThreadCoroutineLocal(threading.local):
 
     def __init__(self):
         super().__init__()
         self._co_local = ContextVar[Optional[Dict]]("_co_local", default=None)
+        ct = threading.current_thread()
+        if hasattr(ct, "_dict_for_logging"):
+            co_local = self.co_local
+            for k, v in getattr(ct, "_dict_for_logging").items():
+                co_local[k] = v
 
     @property
     def co_local(self):
@@ -133,12 +150,18 @@ class ContextJSONFormatter(Formatter):
             "line_info": f"{record.filename}:{record.lineno}:{record.funcName}",
             # 日志消息
             "message": message,
-            # 通过上下文变量控制不同源, 比如对话，额外算法服务: 历史标题，欢迎语，Planning等
+            # 通过上下文变量控制不同源, 比如Intent，Planning等，写入不同的表
             "message_source": context.get("message_source", "chat_log"),
             # 控制不同log类型，便于筛选日志数据, 比如tool, llm, turn等
             "message_type": message_type,
             **extra_message
         }
+        # 自动将 context 里未出现在 log_data/extra_message 的 key 加入 extra_message
+        for k, v in context.items():
+            if k not in log_data and k not in extra_message:
+                extra_message[k] = v
+        # 重新组装 log_data，确保 extra_message 最新
+        log_data.update(extra_message)
         try:
             output_log = json.dumps(log_data, ensure_ascii=False)
         except TypeError:
@@ -186,14 +209,14 @@ class Logger(logging.Logger):
             self.addHandler(console_handler)
 
     def track_start(
-        self, message: Union[str, Mapping], message_type: str = "on_track_start", stacklevel: int = 2, **kwargs
+            self, message: Union[str, Mapping], message_type: str = "on_track_start", stacklevel: int = 2, **kwargs
     ):
         self._log(
             logging.INFO, {"message": message, "message_type": message_type, **kwargs}, (), stacklevel=stacklevel
         )
 
     def track_end(
-        self, message: Union[str, Mapping], message_type: str = "on_track_end", stacklevel: int = 2, **kwargs
+            self, message: Union[str, Mapping], message_type: str = "on_track_end", stacklevel: int = 2, **kwargs
     ):
         self._log(
             logging.INFO, {"message": message, "message_type": message_type, **kwargs}, (), stacklevel=stacklevel
@@ -228,12 +251,12 @@ class Logger(logging.Logger):
         )
 
     def llm_start(
-        self,
-        llm_chain_name: str,
-        messages: Sequence[Mapping],
-        template_info: Mapping,
-        model_kwargs: Mapping = None,
-        **kwargs
+            self,
+            llm_chain_name: str,
+            messages: Sequence[Mapping],
+            template_info: Mapping,
+            model_kwargs: Mapping = None,
+            **kwargs
     ):
         log_info_dict = {
             "func_name": llm_chain_name,
@@ -249,19 +272,19 @@ class Logger(logging.Logger):
         )
 
     def llm_end(
-        self,
-        llm_name: str,
-        content: str,
-        execute_time: float,
-        completion_tokens: int = None,
-        prompt_tokens: int = None,
-        role: str = "assistant",
-        **kwargs
+            self,
+            llm_name: str,
+            content: str,
+            execute_time: float,
+            completion_tokens: int = None,
+            prompt_tokens: int = None,
+            role: str = "assistant",
+            **kwargs
     ):
         log_info_dict = {
             "func_name": llm_name,
             "response": {"role": role, "content": content},
-            "generated_tokens": completion_tokens,
+            "completion_tokens": completion_tokens,
             "prompt_tokens": prompt_tokens,
             "duration": round(execute_time, 3)
         }

{liblogging-0.1.13 → liblogging-0.1.16}/liblogging/sending/log_collector.py

@@ -53,9 +53,10 @@ class LogCollector:
     ):
         while True:
             try:
-                line = sys.stdin.readline().strip()
+                line = sys.stdin.readline()
                 if not line:
-                    continue
+                    break
+                line = line.strip()
                 try:
                     if use_default_process:
                         trace_id, message = process_message(line)

liblogging-0.1.16/liblogging.egg-info/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: liblogging
+Version: 0.1.16
+Summary: Utilities for logging and sending logs.
+Home-page: https://github.com/XoriieInpottn/liblogging
+Author: xi
+Author-email: gylv@mail.ustc.edu.cn, huangfuyb@163.com
+License: Apache-2.0 license
+Platform: any
+Classifier: Programming Language :: Python :: 3
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: collector
+Requires-Dist: kafka-python==2.0.2; extra == "collector"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license
+Dynamic: license-file
+Dynamic: platform
+Dynamic: provides-extra
+Dynamic: summary
+
+# liblogging
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/XoriieInpottn/liblogging)
+
+Utilities for logging and sending logs.
+```shell
+pip install liblogging
+```
+
+## 🌟Feature
+### 统一日志格式记录
+统一了当前agent的日志记录格式，也可自己基于默认格式进行拓展。
+当前记录的信息和对应的key如下：
+```python
+{
+    "create_time": "时间戳，默认和mysql列datatime(3)保持一致",
+    "level": "like INFO, ERROR, WARNING",
+    # 通过上下文变量保存trace_id
+    "trace_id": "trace_id for 追溯不同服务的调用链路",
+    "line_info": "{record.filename}:{record.lineno}:{record.funcName}",
+    "message": message,
+    # 通过上下文变量区分不同源, 方便接收不同服务源信息, 比如Chat, Welcome, Planning等
+    "message_source": context.get("message_source", "chat_log"),
+    # 控制不同log类型，便于筛选日志数据, 比如tool, llm, turn等
+    "message_type": message_type,
+    # 可以根据自己需求加入其他的字段
+    **extra_message
+}
+```
+上述日志信息均以json字符串的形式记录下来，方便存储及后续处理。
+
+### 配置上下文变量，无须重复传参显示记录
+通过装饰器形式, 指定需要配置的全局上下文变量, 仅需在整个程序/服务入口配置一次即可。
+
+需要注意的是配置的全局上下文变量，根据加入装饰器下的函数入参名称匹配进行更新，推荐函数参数定义使用`BaseModel`。
+
+```python
+主程序/服务: service1.py
+from pydantic import BaseModel
+
+from liblogging import log_request,logger
+
+
+class Request(BaseModel):
+    name: str
+    trace_id: str
+
+#在主程序入口配置了trace_id这一全局上下文变量，会通过函数入参对该字段进行赋值，后续在该服务下的其他程序logger.info时会读取这一变量并记录下来。
+#同时也支持默认参数配置，比如message_source设置了默认值，后续使用logger会记录message_source为"demo"。
+@log_request("trace_id", message_source="demo")
+def your_service_entry(request: Request):
+    logger.info("Processing request")
+```
+
+```python
+该服务下的其他程序: function1.py，可直接logger.info(). trace_id, message_source均会记录下来。
+from liblogging import logger
+
+def test(name):
+    logger.info(f"Testing {name}")
+```
+
+### 重定向并发送到消息队列
+以默认集成的kafka为例，可将上述统一日志格式记录的形式发送至kafka。
+
+kafka 配置文件格式：
+```json
+{
+    "{cluster_name}": {
+        "{env_name}": {
+            "bootstrap_servers": "server1, server2, server3",
+            "username": "username",
+            "password": "******",
+            "topic": "your topic",
+            "...": "..."
+        }
+    }
+}
+```
+
+使用形式:
+```shell
+python -u service 2>&1 | tee {log_file_path} | liblogging_collector --config-path {your_kafka_path}  --ssl-cafile {your_ssl_cafile_path} --send-kafka
+```
+tee {log_file_path} 可以将你的程序记录（输出+错误）重定向到文件中（可选）。
+
+[log_collector.py](liblogging/sending/log_collector.py)为`liblogging_collector`的源代码地址。
+
+`env_name`不指定的话，默认读取`os.environ.get("CHAT_ENV", "dev")`.
+
+## 📋Example
+增加额外记录字段信息，以及搭配[libentry](https://github.com/XoriieInpottn/libentry)使用的样例见 [example](example)。
+
+
+## 💡Tips
+
+1. If using Kafka to send messages, please use `pip install liblogging[collector]`.
+2. 如果需要数据持久化，推荐日志消息都写在message列中，维护一列节省内存空间。需要后续进行查询的，以字典形式记录，比如logger.info({"key": "value"}), 便于后续查找。
+
+3. 当前默认的trace_id，推荐使用[liblogging/util.py](liblogging/util.py)中的`get_trace_id`函数，该函数会根据请求对象的`uid`, `session_id`, `turn`等字段生成trace_id，默认的[liblogging/sending/log_collector.py](liblogging/sending/log_collector.py)也会根据trace_id拆解`uid`, `session_id`, `turn`，根据`create_time`拆解`create_date`，方便后续进行追溯以及数据存储。以下是构建trace_id的在整个服务入口的示例：
+```python
+from liblogging.util import get_trace_id
+
+class Request(BaseModel):
+    uid: str = Field(..., description="用户id")
+    session_id: str = Field(..., description="会话id")
+    turn: int = Field(..., description="轮次")
+    trace_id: str = Field(..., description="trace_id")
+
+@log_request("trace_id", "message_source")
+def set_logger_global_vars(trace_id: str, message_source: str):
+    print(f"setting global vars: trace_id={trace_id}, message_source={message_source}")
+
+def run():
+    trace_id = get_trace_id(request)
+    # 设置全局上下文变量, 这里注意需要以trace_id=xxx, message_source=xxx形式显式传入
+    set_logger_global_vars(trace_id=trace_id, message_source="demo")
+    request.trace_id = trace_id
+    # 可以直接给其他服务传入request对象，后续的logger.info会自动记录trace_id，其他服务需要在服务入口使用@log_request装饰器配置trace_id, message_source等全局上下文变量。可见example/service.py
+    your_service_entry(request)
+
+if __name__ == "__main__":
+    run()
+```
+
+4. liblogging提供了一些常用的，比如logger.tool_start, logger.tool_end, logger.track_start, logger.track_end等。
+
+    (1) 默认message列就是当使用`logger.info(<message>)`时，message的值。
+
+    (2) 从本质上可以理解为当info的内容是字典时，字典的key就是表中的列名，value就是列的值，而使用liblogging默认这一套 `trace_id`, ``create_time`, `create_date`, `uid`, `session_id`, `turn`等字段会自动添加.
+
+    (3) 如果需要统计相应的字段推荐这种方式，方便后续进行查询。
+```python
+logger.info({
+    "message": {"key1": "value1", "key2": "value2"},  # message列的内容，liblogging将json序列化后存储
+    "message_type": "<your message_type>"  # message_type列方便后续进行查询
+})
+```
+
+
+由log_collector.py默认的数据表结构如下（如果有额外的字段，创建表时和log时的key保持一致即可）：
+```sql
+CREATE TABLE `agent_log`.`your_table_name(需要和message_source一致)` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT,
+  `uid` varchar(64) NOT NULL DEFAULT '',
+  `session_id` varchar(128) NOT NULL DEFAULT '',
+  `turn` smallint NOT NULL DEFAULT '0',
+  `trace_id` varchar(255) NOT NULL DEFAULT '',
+  `create_date` date NOT NULL,
+  `create_time` datetime(3) NOT NULL,
+  `insert_time` timestamp NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '插入时间',
+  `line_info` varchar(255) NOT NULL DEFAULT '' COMMENT '对应代码行信息',
+  `message_source` varchar(64) NOT NULL DEFAULT '' COMMENT '消息来源：plan, memory, intent, guess question等，对应表名',
+  `message_type` varchar(32) NOT NULL DEFAULT '' COMMENT '消息类型, 可以筛选该key获取相关指标信息',
+  `message` text,
+  `level` varchar(32) NOT NULL DEFAULT '' COMMENT 'info， warning, error等',
+  PRIMARY KEY (`id`,`create_date`),
+  KEY `session_id_index` (`session_id`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_0900_ai_ci
+PARTITION BY RANGE (TO_DAYS(create_date)) (
+    PARTITION p202507 VALUES LESS THAN (TO_DAYS('2025-08-01')),
+    PARTITION p202508 VALUES LESS THAN (TO_DAYS('2025-09-01')),
+    PARTITION p202509 VALUES LESS THAN (TO_DAYS('2025-10-01')),
+    PARTITION p202510 VALUES LESS THAN (TO_DAYS('2025-11-01')),
+    PARTITION p202511 VALUES LESS THAN (TO_DAYS('2025-12-01')),
+    PARTITION p202512 VALUES LESS THAN (TO_DAYS('2026-01-01')),
+    PARTITION p202601 VALUES LESS THAN (TO_DAYS('2026-02-01')),
+    PARTITION p202602 VALUES LESS THAN (TO_DAYS('2026-03-01')),
+    PARTITION p202603 VALUES LESS THAN (TO_DAYS('2026-04-01')),
+    PARTITION p202604 VALUES LESS THAN (TO_DAYS('2026-05-01')),
+    PARTITION p202605 VALUES LESS THAN (TO_DAYS('2026-06-01')),
+    PARTITION p202606 VALUES LESS THAN (TO_DAYS('2026-07-01')),
+    PARTITION p202607 VALUES LESS THAN (TO_DAYS('2026-08-01')),
+    PARTITION p202608 VALUES LESS THAN (TO_DAYS('2026-09-01')),
+    PARTITION p202609 VALUES LESS THAN (TO_DAYS('2026-10-01')),
+    PARTITION p202610 VALUES LESS THAN (TO_DAYS('2026-11-01')),
+    PARTITION p202611 VALUES LESS THAN (TO_DAYS('2026-12-01')),
+    PARTITION p202612 VALUES LESS THAN (TO_DAYS('2027-01-01')),
+    PARTITION pMaxRange VALUES LESS THAN MAXVALUE
+);
+```

{liblogging-0.1.13 → liblogging-0.1.16}/setup.py

@@ -18,7 +18,7 @@ if __name__ == '__main__':
                 'liblogging_collector = liblogging.sending.log_collector:main'
             ]
         },
-        version='0.1.13',
+        version='0.1.16',
         description='Utilities for logging and sending logs.',
         long_description_content_type='text/markdown',
         long_description=long_description,

liblogging-0.1.13/PKG-INFO

@@ -1,122 +0,0 @@
-Metadata-Version: 2.4
-Name: liblogging
-Version: 0.1.13
-Summary: Utilities for logging and sending logs.
-Home-page: https://github.com/XoriieInpottn/liblogging
-Author: xi
-Author-email: gylv@mail.ustc.edu.cn, huangfuyb@163.com
-License: Apache-2.0 license
-Platform: any
-Classifier: Programming Language :: Python :: 3
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: collector
-Requires-Dist: kafka-python==2.0.2; extra == "collector"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
-Dynamic: license-file
-Dynamic: platform
-Dynamic: provides-extra
-Dynamic: summary
-
-# liblogging
-
-Utilities for logging and sending logs.
-```shell
-pip install liblogging
-```
-
-## 🌟Feature
-### 统一日志格式记录
-统一了当前agent的日志记录格式，也可自己基于默认格式进行拓展。
-当前记录的信息和对应的key如下：
-```python
-{
-    "create_time": "时间戳，默认和mysql列datatime(3)保持一致",
-    "level": "like INFO, ERROR, WARNING",
-    # 通过上下文变量保存trace_id
-    "trace_id": "trace_id for 追溯不同服务的调用链路",
-    "line_info": "{record.filename}:{record.lineno}:{record.funcName}",
-    "message": message,
-    # 通过上下文变量区分不同源, 方便接收不同服务源信息, 比如Chat, Welcome, Planning等
-    "message_source": context.get("message_source", "chat_log"),
-    # 控制不同log类型，便于筛选日志数据, 比如tool, llm, turn等
-    "message_type": message_type,
-    # 可以根据自己需求加入其他的字段
-    **extra_message
-}
-```
-上述日志信息均以json字符串的形式记录下来，方便存储及后续处理。
-
-### 配置上下文变量，无须重复传参显示记录
-通过装饰器形式, 指定需要配置的全局上下文变量, 仅需在整个程序/服务入口配置一次即可。
-
-需要注意的是配置的全局上下文变量，根据加入装饰器下的函数入参名称匹配进行更新，推荐函数参数定义使用`BaseModel`。
-
-```python
-主程序/服务: service1.py
-from pydantic import BaseModel
-
-from liblogging import log_request,logger
-
-
-class Request(BaseModel):
-    name: str
-    trace_id: str
-
-#在主程序入口配置了trace_id这一全局上下文变量，会通过函数入参对该字段进行赋值，后续在该服务下的其他程序logger.info时会读取这一变量并记录下来。
-#同时也支持默认参数配置，比如message_source设置了默认值，后续使用logger会记录message_source为"demo"。
-@log_request("trace_id", message_source="demo")
-def your_service_entry(request: Request):
-    logger.info("Processing request")
-```
-
-```python
-该服务下的其他程序: function1.py，可直接logger.info(). trace_id, message_source均会记录下来。
-from liblogging import logger
-
-def test(name):
-    logger.info(f"Testing {name}")
-```
-
-### 重定向并发送到消息队列
-以默认集成的kafka为例，可将上述统一日志格式记录的形式发送至kafka。
-
-kafka 配置文件格式：
-```json
-{
-    "{cluster_name}": {
-        "{env_name}": {
-            "bootstrap_servers": "server1, server2, server3",
-            "username": "username",
-            "password": "******",
-            "topic": "your topic",
-            "...": "..."
-        }
-    }
-}
-```
-
-使用形式:
-```shell
-python service 2>&1 | tee {log_file_path} | liblogging_collector --config-path {your_kafka_path}  --ssl-cafile {your_ssl_cafile_path} --send-kafka
-```
-tee {log_file_path} 可以将你的程序记录（输出+错误）重定向到文件中（可选）。
-
-[log_collector.py](liblogging/sending/log_collector.py)为`liblogging_collector`的源代码地址。
-
-`env_name`不指定的话，默认读取`os.environ.get("CHAT_ENV", "dev")`.
-
-## 📋Example
-增加额外记录字段信息，以及搭配[libentry](https://github.com/XoriieInpottn/libentry)使用的样例见 [example](example)。
-
-
-## 💡Tips
-
-1. If using Kafka to send messages, please use `pip install liblogging[collector]`.
-2. 如果需要数据持久化，推荐日志消息都写在message列中，维护一列节省内存空间。需要后续进行查询的，以字典形式记录，比如logger.info({"key": "value"}), 便于后续查找。

liblogging-0.1.13/README.md

@@ -1,96 +0,0 @@
-# liblogging
-
-Utilities for logging and sending logs.
-```shell
-pip install liblogging
-```
-
-## 🌟Feature
-### 统一日志格式记录
-统一了当前agent的日志记录格式，也可自己基于默认格式进行拓展。
-当前记录的信息和对应的key如下：
-```python
-{
-    "create_time": "时间戳，默认和mysql列datatime(3)保持一致",
-    "level": "like INFO, ERROR, WARNING",
-    # 通过上下文变量保存trace_id
-    "trace_id": "trace_id for 追溯不同服务的调用链路",
-    "line_info": "{record.filename}:{record.lineno}:{record.funcName}",
-    "message": message,
-    # 通过上下文变量区分不同源, 方便接收不同服务源信息, 比如Chat, Welcome, Planning等
-    "message_source": context.get("message_source", "chat_log"),
-    # 控制不同log类型，便于筛选日志数据, 比如tool, llm, turn等
-    "message_type": message_type,
-    # 可以根据自己需求加入其他的字段
-    **extra_message
-}
-```
-上述日志信息均以json字符串的形式记录下来，方便存储及后续处理。
-
-### 配置上下文变量，无须重复传参显示记录
-通过装饰器形式, 指定需要配置的全局上下文变量, 仅需在整个程序/服务入口配置一次即可。
-
-需要注意的是配置的全局上下文变量，根据加入装饰器下的函数入参名称匹配进行更新，推荐函数参数定义使用`BaseModel`。
-
-```python
-主程序/服务: service1.py
-from pydantic import BaseModel
-
-from liblogging import log_request,logger
-
-
-class Request(BaseModel):
-    name: str
-    trace_id: str
-
-#在主程序入口配置了trace_id这一全局上下文变量，会通过函数入参对该字段进行赋值，后续在该服务下的其他程序logger.info时会读取这一变量并记录下来。
-#同时也支持默认参数配置，比如message_source设置了默认值，后续使用logger会记录message_source为"demo"。
-@log_request("trace_id", message_source="demo")
-def your_service_entry(request: Request):
-    logger.info("Processing request")
-```
-
-```python
-该服务下的其他程序: function1.py，可直接logger.info(). trace_id, message_source均会记录下来。
-from liblogging import logger
-
-def test(name):
-    logger.info(f"Testing {name}")
-```
-
-### 重定向并发送到消息队列
-以默认集成的kafka为例，可将上述统一日志格式记录的形式发送至kafka。
-
-kafka 配置文件格式：
-```json
-{
-    "{cluster_name}": {
-        "{env_name}": {
-            "bootstrap_servers": "server1, server2, server3",
-            "username": "username",
-            "password": "******",
-            "topic": "your topic",
-            "...": "..."
-        }
-    }
-}
-```
-
-使用形式:
-```shell
-python service 2>&1 | tee {log_file_path} | liblogging_collector --config-path {your_kafka_path}  --ssl-cafile {your_ssl_cafile_path} --send-kafka
-```
-tee {log_file_path} 可以将你的程序记录（输出+错误）重定向到文件中（可选）。
-
-[log_collector.py](liblogging/sending/log_collector.py)为`liblogging_collector`的源代码地址。
-
-`env_name`不指定的话，默认读取`os.environ.get("CHAT_ENV", "dev")`.
-
-## 📋Example
-增加额外记录字段信息，以及搭配[libentry](https://github.com/XoriieInpottn/libentry)使用的样例见 [example](example)。
-
-
-## 💡Tips
-
-1. If using Kafka to send messages, please use `pip install liblogging[collector]`.
-2. 如果需要数据持久化，推荐日志消息都写在message列中，维护一列节省内存空间。需要后续进行查询的，以字典形式记录，比如logger.info({"key": "value"}), 便于后续查找。

liblogging-0.1.13/liblogging.egg-info/PKG-INFO

@@ -1,122 +0,0 @@
-Metadata-Version: 2.4
-Name: liblogging
-Version: 0.1.13
-Summary: Utilities for logging and sending logs.
-Home-page: https://github.com/XoriieInpottn/liblogging
-Author: xi
-Author-email: gylv@mail.ustc.edu.cn, huangfuyb@163.com
-License: Apache-2.0 license
-Platform: any
-Classifier: Programming Language :: Python :: 3
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Provides-Extra: collector
-Requires-Dist: kafka-python==2.0.2; extra == "collector"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license
-Dynamic: license-file
-Dynamic: platform
-Dynamic: provides-extra
-Dynamic: summary
-
-# liblogging
-
-Utilities for logging and sending logs.
-```shell
-pip install liblogging
-```
-
-## 🌟Feature
-### 统一日志格式记录
-统一了当前agent的日志记录格式，也可自己基于默认格式进行拓展。
-当前记录的信息和对应的key如下：
-```python
-{
-    "create_time": "时间戳，默认和mysql列datatime(3)保持一致",
-    "level": "like INFO, ERROR, WARNING",
-    # 通过上下文变量保存trace_id
-    "trace_id": "trace_id for 追溯不同服务的调用链路",
-    "line_info": "{record.filename}:{record.lineno}:{record.funcName}",
-    "message": message,
-    # 通过上下文变量区分不同源, 方便接收不同服务源信息, 比如Chat, Welcome, Planning等
-    "message_source": context.get("message_source", "chat_log"),
-    # 控制不同log类型，便于筛选日志数据, 比如tool, llm, turn等
-    "message_type": message_type,
-    # 可以根据自己需求加入其他的字段
-    **extra_message
-}
-```
-上述日志信息均以json字符串的形式记录下来，方便存储及后续处理。
-
-### 配置上下文变量，无须重复传参显示记录
-通过装饰器形式, 指定需要配置的全局上下文变量, 仅需在整个程序/服务入口配置一次即可。
-
-需要注意的是配置的全局上下文变量，根据加入装饰器下的函数入参名称匹配进行更新，推荐函数参数定义使用`BaseModel`。
-
-```python
-主程序/服务: service1.py
-from pydantic import BaseModel
-
-from liblogging import log_request,logger
-
-
-class Request(BaseModel):
-    name: str
-    trace_id: str
-
-#在主程序入口配置了trace_id这一全局上下文变量，会通过函数入参对该字段进行赋值，后续在该服务下的其他程序logger.info时会读取这一变量并记录下来。
-#同时也支持默认参数配置，比如message_source设置了默认值，后续使用logger会记录message_source为"demo"。
-@log_request("trace_id", message_source="demo")
-def your_service_entry(request: Request):
-    logger.info("Processing request")
-```
-
-```python
-该服务下的其他程序: function1.py，可直接logger.info(). trace_id, message_source均会记录下来。
-from liblogging import logger
-
-def test(name):
-    logger.info(f"Testing {name}")
-```
-
-### 重定向并发送到消息队列
-以默认集成的kafka为例，可将上述统一日志格式记录的形式发送至kafka。
-
-kafka 配置文件格式：
-```json
-{
-    "{cluster_name}": {
-        "{env_name}": {
-            "bootstrap_servers": "server1, server2, server3",
-            "username": "username",
-            "password": "******",
-            "topic": "your topic",
-            "...": "..."
-        }
-    }
-}
-```
-
-使用形式:
-```shell
-python service 2>&1 | tee {log_file_path} | liblogging_collector --config-path {your_kafka_path}  --ssl-cafile {your_ssl_cafile_path} --send-kafka
-```
-tee {log_file_path} 可以将你的程序记录（输出+错误）重定向到文件中（可选）。
-
-[log_collector.py](liblogging/sending/log_collector.py)为`liblogging_collector`的源代码地址。
-
-`env_name`不指定的话，默认读取`os.environ.get("CHAT_ENV", "dev")`.
-
-## 📋Example
-增加额外记录字段信息，以及搭配[libentry](https://github.com/XoriieInpottn/libentry)使用的样例见 [example](example)。
-
-
-## 💡Tips
-
-1. If using Kafka to send messages, please use `pip install liblogging[collector]`.
-2. 如果需要数据持久化，推荐日志消息都写在message列中，维护一列节省内存空间。需要后续进行查询的，以字典形式记录，比如logger.info({"key": "value"}), 便于后续查找。