DB 日志推送插件和日志收集服务

DB 日志推送插件 (db-log-pusher) 和日志收集服务 (db-log-collector)

源码仓库：

• 主仓库：https://github.com/higress-group/db-log-pusher - 包含完整的插件和收集器源码
• Higress 集成方式：需要手动将源码克隆并集成到 Higress 仓库 的 plugins/wasm-go/extensions 目录
• 独立插件仓库：https://github.com/higress-group/db-log-pusher

db-log-pusher 是一个 WASM 插件，用于收集 HTTP 请求/响应日志，并将这些日志推送到外部收集器服务 (db-log-collector) 进行存储和分析。这两个组件共同构成了完整的日志收集解决方案。该插件能够捕获完整的请求/响应生命周期信息，并将其发送到指定的目标服务。

一、db-log-pusher 功能特性

• 全面的日志收集: 捕获请求/响应的完整信息，包括基础信息、流量统计、连接信息等
• AI 日志支持: 特别针对 AI 应用场景，支持收集模型调用日志和 token 统计
• 灵活的配置: 支持自定义收集器服务地址和路径
• 实时推送: 异步将日志实时推送到外部收集器
• 性能优化: 采用非阻塞方式发送日志，不影响主业务流程
• 智能客户端: 自动创建内部集群客户端，使用 collector_service_name 和 collector_port 配置建立连接
• 超时处理: 包含 5 秒超时设置，防止长时间阻塞
• 错误处理: 记录发送失败和异常情况，不影响主业务流程
• 数据库存储: 内置数据库存储机制，用于持久化日志管理

配置参数

参数	类型	必填	默认值	描述
collector_service_name	string	是	-	收集器服务名称，格式为 FQDN，例如 “log-collector.higress-system.svc.cluster.local”
collector_port	int	是	-	收集器端口，例如 8080
collector_path	string	否	”/“	接收日志的 API 路径，例如 “/api/log”

收集的数据字段

插件会收集以下类型的详细信息：

基础请求信息

• start_time: 请求开始时间
• authority: Host/Authority
• method: HTTP 方法
• path: 请求路径
• protocol: HTTP 协议版本
• request_id: X-Request-ID
• trace_id: X-B3-TraceID
• user_agent: User-Agent
• x_forwarded_for: X-Forwarded-For

响应信息

• response_code: 响应状态码
• response_flags: Envoy 响应标志
• response_code_details: 响应码详情

流量信息

• bytes_received: 接收字节数
• bytes_sent: 发送字节数
• duration: 请求总耗时(毫秒)

上游信息

• upstream_cluster: 上游集群名
• upstream_host: 上游主机
• upstream_service_time: 上游服务耗时
• upstream_transport_failure_reason: 上游传输失败原因

连接信息

• downstream_local_address: 下游本地地址
• downstream_remote_address: 下游远程地址
• upstream_local_address: 上游本地地址

路由信息

• route_name: 路由名称
• requested_server_name: SNI

AI 相关信息

• ai_log: WASM AI 日志
• input_tokens: 输入 token 数量
• output_tokens: 输出 token 数量
• total_tokens: 总 token 数量
• model: 模型名称
• api: API 名称
• consumer: 消费者信息

监控元数据

• instance_id: 实例 ID
• route: 路由
• service: 服务
• mcp_server: MCP Server
• mcp_tool: MCP Tool

配置方式

方式一：通过 Higress Console 配置（推荐）

这是最简单直接的配置方式，通过 Higress Console 的图形化界面即可完成插件安装和配置。

操作步骤

1. 访问 Higress Console

   • 登录 Higress Console 管理页面
   • 导航到 插件配置 -> 添加插件

2. 填写插件信息

   • 插件名称: db-log-pusher-plugin
   • 插件描述: Collect HTTP request logs to database
   • 镜像地址: https://pysrc-test.oss-cn-beijing.aliyuncs.com/higress-plugin/plugin-20260323-101235.wasm
   • 插件执行阶段: 选择 认证阶段 (AUTHN)
   • 插件执行优先级: 1010 (范围 1~1000，值越大优先级越高)
   • 插件拉取策略: 选择 总是拉取 (Always)

3. 配置路由和策略

   • 在插件配置页面，点击”添加匹配规则”
   • 在 ingress 列表中选择或输入需要应用此插件的服务名称，例如：
     • model-api-qwen3-plus-0
     • travel-assistant

4. 配置插件参数

   • 在 自定义插件配置 区域，选择刚才创建的 db-log-pusher 插件
   • 在参数配置表单中，逐行填写以下参数（每行一个参数，格式为 key: value）：

   log_level: info
   collector_service_name: log-collector.higress-system.svc.cluster.local
   collector_port: 80
   collector_path: /ingest

   • 确保 configDisable 设置为 false（启用配置）

5. 保存配置

   • 点击”保存”按钮完成配置
   • Higress 会自动部署插件到网关

配置说明

• 执行阶段: 选择认证阶段（AUTHN），用于统计和日志收集
• 优先级: 设置为 1010，确保高于 ai-statistics 插件的优先级
• 拉取策略: 总是拉取最新版本，确保使用最新的插件功能

验证配置

配置保存后，可以通过以下方式验证：

• 查看 Higress Console 插件列表，确认插件状态正常
• 访问配置的服务，检查日志是否正常发送到收集器

---

方式二：通过 Kubernetes YAML 配置

如果您更喜欢使用 Kubernetes 原生配置方式，可以通过创建 WasmPlugin 资源来部署插件。

apiVersion: extensions.higress.io/v1alpha1
kind: WasmPlugin
metadata:
  name: db-log-pusher-plugin
  namespace: higress-system
  annotations:
    higress.io/redeploy-timestamp: "20260309-122804"
    higress.io/comment: "DB Log Pusher Plugin for collecting request logs"
    higress.io/wasm-plugin-title: "DB Log Pusher"
    higress.io/wasm-plugin-description: "Collect HTTP request logs to database"
  labels:
    higress.io/wasm-plugin-name: db-log-pusher
    higress.io/wasm-plugin-category: logging
spec:
  url: https://pysrc-test.oss-cn-beijing.aliyuncs.com/higress-plugin/plugin-20260323-101235.wasm
  sha256: ""  # 建议填入 WASM 文件的 SHA256 校验和
  defaultConfigDisable: true  # 默认关闭全局配置
  failStrategy: FAIL_OPEN      # 失败时放行，避免影响业务
  imagePullPolicy: Always  # 总是拉取最新版本
  phase: AUTHN           # 插件执行阶段，用于统计和日志收集
  priority: 1010           # 优先级
  # 匹配规则：应用到所有服务
  matchRules:
    - configDisable: false
      ingress:
        - model-api-qwen3-plus-0
        - travel-assistant
      config:
        log_level: info  # 必须在这里配置 log_level
        collector_service_name: "log-collector.higress-system.svc.cluster.local"
        collector_port: 80
        collector_path: "/ingest"

应用配置：

kubectl apply -f db-log-pusher.yaml

---

二、配套组件：Log Collector 部署

db-log-pusher 插件需要配合日志收集服务一起使用。以下是一个简单的日志收集器部署示例。

1. 准备数据库

首先创建一个 MySQL 数据库用于存储日志数据。执行以下 SQL 创建表结构：

CREATE DATABASE IF NOT EXISTS higress_poc DEFAULT CHARACTER SET utf8mb4;

USE higress_poc;

CREATE TABLE access_logs (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    start_time DATETIME NOT NULL COMMENT '请求开始时间',
    trace_id VARCHAR(255) COMMENT 'X-B3-TraceID',
    authority VARCHAR(255) COMMENT 'Host/Authority',
    method VARCHAR(10) COMMENT 'HTTP 方法',
    path TEXT COMMENT '请求路径',
    protocol VARCHAR(20) COMMENT 'HTTP 协议版本',
    request_id VARCHAR(255) COMMENT 'X-Request-ID',
    user_agent TEXT COMMENT 'User-Agent',
    x_forwarded_for TEXT COMMENT 'X-Forwarded-For',
    response_code INT COMMENT '响应状态码',
    response_flags VARCHAR(100) COMMENT 'Envoy 响应标志',
    response_code_details TEXT COMMENT '响应码详情',
    bytes_received BIGINT COMMENT '接收字节数',
    bytes_sent BIGINT COMMENT '发送字节数',
    duration BIGINT COMMENT '请求总耗时 (ms)',
    upstream_cluster VARCHAR(255) COMMENT '上游集群名',
    upstream_host VARCHAR(255) COMMENT '上游主机',
    upstream_service_time VARCHAR(50) COMMENT '上游服务耗时',
    upstream_transport_failure_reason TEXT COMMENT '上游传输失败原因',
    upstream_local_address VARCHAR(255) COMMENT '上游本地地址',
    downstream_local_address VARCHAR(255) COMMENT '下游本地地址',
    downstream_remote_address VARCHAR(255) COMMENT '下游远程地址',
    route_name VARCHAR(255) COMMENT '路由名称',
    requested_server_name VARCHAR(255) COMMENT 'SNI',
    istio_policy_status VARCHAR(100) COMMENT 'Istio 策略状态',
    ai_log JSON COMMENT 'WASM AI 日志',
    instance_id VARCHAR(255) COMMENT '实例 ID',
    api VARCHAR(255) COMMENT 'API 名称',
    model VARCHAR(255) COMMENT '模型名称',
    consumer VARCHAR(255) COMMENT '消费者信息',
    route VARCHAR(255) COMMENT '路由名称',
    service VARCHAR(255) COMMENT '服务名称',
    mcp_server VARCHAR(255) COMMENT 'MCP Server',
    mcp_tool VARCHAR(255) COMMENT 'MCP Tool',
    input_tokens BIGINT COMMENT '输入 token 数量',
    output_tokens BIGINT COMMENT '输出 token 数量',
    total_tokens BIGINT COMMENT '总 token 数量',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    INDEX idx_start_time (start_time),
    INDEX idx_trace_id (trace_id),
    INDEX idx_authority (authority),
    INDEX idx_method (method),
    INDEX idx_response_code (response_code),
    INDEX idx_instance_id (instance_id),
    INDEX idx_api (api),
    INDEX idx_model (model),
    INDEX idx_consumer (consumer),
    INDEX idx_mcp_server (mcp_server)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='Higress Access Logs';

2. 部署 Log Collector 服务

方式一：Kubernetes 部署（推荐）

将以下 YAML 保存为 log-collector.yaml 并应用：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: log-collector
  namespace: higress-system
  labels:
    app: log-collector
spec:
  replicas: 1
  selector:
    matchLabels:
      app: log-collector
  template:
    metadata:
      labels:
        app: log-collector
    spec:
      containers:
      - name: collector
        image: registry.cn-shanghai.aliyuncs.com/daofeng/log-collector:latest
        imagePullPolicy: Always
        ports:
        - containerPort: 8080
        env:
        # 修改为你的 MySQL 连接信息
        - name: MYSQL_DSN
          value: "user:password@tcp(mysql-host:3306)/higress_poc?charset=utf8mb4&parseTime=True&loc=Local"
        resources:
          limits:
            cpu: "500m"
            memory: "512Mi"
          requests:
            cpu: "100m"
            memory: "128Mi"
        livenessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 10
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8080
          initialDelaySeconds: 5
          periodSeconds: 5

---
apiVersion: v1
kind: Service
metadata:
  name: log-collector
  namespace: higress-system
spec:
  selector:
    app: log-collector
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
  type: ClusterIP

应用部署：

kubectl apply -f log-collector.yaml

方式二：Docker 单机部署

如果您想在本地或单台服务器上快速部署，可以使用 Docker 运行日志收集服务。

部署命令：

docker run -d \
  --name log-collector \
  -p 8080:8080 \
  -e MYSQL_DSN="user:password@tcp(mysql-host:3306)/higress_poc?charset=utf8mb4&parseTime=True&loc=Local" \
  --restart unless-stopped \
  registry.cn-shanghai.aliyuncs.com/daofeng/log-collector:latest

参数说明：

• -d: 后台运行容器
• --name log-collector: 指定容器名称
• -p 8080:8080: 将容器的 8080 端口映射到宿主机
• -e MYSQL_DSN: 设置 MySQL 数据库连接字符串，请根据实际情况修改
• --restart unless-stopped: 容器退出时自动重启（除非手动停止）

验证部署：

检查容器运行状态：

docker ps | grep log-collector

查看容器日志：

docker logs -f log-collector

测试健康检查端点：

curl http://localhost:8080/health

停止和删除容器：

# 停止容器
docker stop log-collector

# 删除容器
docker rm log-collector

3. 验证部署

Kubernetes 部署验证

检查 Pod 状态：

kubectl get pods -n higress-system -l app=log-collector

查看日志确认服务启动正常：

kubectl logs -n higress-system deployment/log-collector

测试健康检查端点：

kubectl exec -n higress-system deployment/log-collector -- wget -qO- http://localhost:8080/health

Docker 部署验证

检查容器运行状态：

docker ps | grep log-collector

查看容器日志：

docker logs -f log-collector

测试健康检查端点：

curl http://localhost:8080/health

正常响应应该返回类似：ok 的响应。

4. 自定义 Log Collector（可选）

如果需要自定义日志推送器的功能，可以参考源码进行修改和重新构建。

源码仓库关系：

• 独立仓库：https://github.com/higress-group/db-log-pusher - 包含完整的插件和收集器源码
• Higress 集成：https://github.com/alibaba/higress/tree/main/plugins/wasm-go/extensions - Higress 官方仓库中的插件目录

源码结构：

db-log-pusher/
├── main.go                      # Pusher 插件主程序
└── log-collector/               # Collector 服务端
    ├── main.go                  # Collector 主程序
    ├── Dockerfile               # Docker 镜像构建文件
    └── ...                      # 其他依赖文件

主要功能：

• 提供 /ingest 端点接收日志（POST）
• 提供 /query 端点查询日志（GET）
• 提供 /health 端点健康检查
• 批量写入数据库（默认每 50 条或每秒刷新一次）
• 支持丰富的查询参数（时间范围、实例 ID、API、模型、MCP Server 等）

构建镜像：

# 克隆 db-log-pusher 仓库
git clone git@github.com:higress-group/db-log-pusher.git

# 克隆 higress 仓库
git clone git@github.com:alibaba/higress.git

# 将 db-log-collector 目录复制到 higress 插件目录
cp -r db-log-pusher/log-collector higress/plugins/wasm-go/extensions/db-log-pusher/

# 进入目录并构建镜像
cd higress/plugins/wasm-go/extensions/db-log-pusher/log-collector
docker build -t your-registry/log-collector:latest .

5. 注意事项

1. 性能考虑: 默认的 log-collector 是单实例部署，适用于中小流量场景。对于高并发场景，建议：

   • 增加 replicas 数量
   • 使用消息队列（如 Kafka）作为缓冲
   • 采用专业的日志系统（如 Elasticsearch + Logstash）

2. 数据安全:

   • 建议使用独立的数据库账号，限制权限
   • 生产环境应使用 TLS 加密数据库连接
   • 定期备份日志数据

3. 资源限制: 根据实际流量调整容器的 CPU 和内存限制

4. 监控告警: 建议为 log-collector 添加监控指标，如：

   • HTTP 请求成功率
   • 数据库写入延迟
   • Buffer 队列长度

使用注意事项

插件执行顺序

如果需要读取 ai-statistics 插件写入的 AI 日志，请确保：

1. 在 WasmPlugin 资源中，db-log-pusher 的 phase 应该晚于 ai-statistics
2. 或者在同一 phase 中，db-log-pusher 的 priority 应该低于 ai-statistics（数字越大优先级越高）

性能考虑

• 插件采用异步方式发送日志，不会阻塞主请求流程
• 对于大请求体，插件会进行适当处理以避免内存问题
• 日志发送失败不会影响主业务流程

与其他插件的配合

• 与认证插件配合时，可以从认证信息中获取消费者信息
• 与路由插件配合时，可以获取更精确的路由和服务信息
• 与 MCP 服务配合时，可以获取工具调用相关信息

故障排除

日志未发送

1. 检查收集器服务是否正常运行
2. 确认网络连通性
3. 查看 Higress 网关日志中的错误信息

配置验证

• 确保 collector_service_name 和 collector_port 配置正确
• 验证收集器服务能够接收 JSON 格式的日志数据

高级配置

对于更复杂的部署场景，您可以根据需要调整以下参数：

• collector_path: 根据您的日志收集服务 API 路径进行调整
• 配合其他监控工具进行日志格式化和处理