feat: Higress 轻量级日志方案：基于 HTTP 推送与 MySQL 存储 || feat: Higress lightweight logging solution: based on HTTP push and MySQL storage

[JayLi52]

[RFC] Higress 轻量级日志方案：基于 HTTP 推送与 MySQL 存储

1. 背景与动机 (Motivation)

当前 Higress 的可观测性方案（如 ELK、Kafka、Prometheus + Grafana 或商业 SLS）对以下场景用户部署成本过高：

• ✅ POC / 演示环境：需 5 分钟内快速验证网关能力
• ✅ 资源受限环境：无运维团队支持重型日志栈
• ✅ 轻量级业务：日均请求量 < 10 万，无需复杂分析

本方案目标：提供 零外部依赖、开箱即用 的日志采集能力，通过 Wasm 插件 + 轻量 Collector + MySQL 实现最小可行日志链路，同时保持插件通用性以利社区合并。

---

2. 架构设计 (Architecture)

采用 Side-channel Push（旁路推送） 模式，解耦数据面与采集逻辑：

核心原则：

• 🔒 网关稳定性优先：日志推送失败绝不阻塞主请求流
• 🧩 插件通用化：Wasm 插件仅负责 HTTP 推送，不绑定存储
• 📦 参考实现分离：MySQL Collector 作为示例组件独立提供

---

3. 详细设计 (Detailed Design)

3.1 组件一：通用 HTTP 日志推送插件 (request-logger-http)

属性	说明
语言	Go (TinyGo/Wasm)
触发阶段	OnLog（请求完成后异步执行）
仓库路径	plugins/wasm-go/extensions/request-logger-http/

配置参数 (plugin.yaml)

service_name: "higress-gateway"          # 网关标识
backend_cluster: "outbound|8080||log-collector.default.svc.cluster.local"
endpoint: "/api/v1/ingest"                # Collector 接收端点
timeout_ms: 50                            # 推送超时（Fail-fast）
sample_rate: 100                          # 采样率 (0-100)
headers_to_extract:                       # 需提取的 Headers
  - "user-agent"
  - "x-request-id"
  - "x-real-ip"

核心逻辑

1. 提取标准字段：method, path, status, latency_ms, upstream_cluster
2. 按配置提取指定 Headers
3. 组装 JSON 体（见第 4 节）
4. 调用 proxywasm.DispatchHttpCall 异步推送
5. 错误处理：静默丢弃所有推送失败（Fire-and-forget），保障网关 SLA

💡 关键设计：插件不感知存储类型，仅作为“请求上下文 → JSON → HTTP 推送”通用管道

---

3.2 组件二：日志接收服务（Reference Implementation）

📌 定位：作为 examples/log-collector/ 目录下的参考实现，非 Higress 核心代码
🌐 仓库建议：独立仓库 higress-examples/log-collector 或 Higress 仓库 examples/ 子目录

核心能力

• HTTP 服务：接收 POST /api/v1/ingest
• 内存 Ring Buffer：Channel + 定时/定量双触发 Flush
• 批量写入：每 1 秒 或 满 100 条 执行一次 INSERT ... VALUES (...), (...)
• 优雅关闭：SIGTERM 时清空缓冲区

MySQL Schema

CREATE TABLE access_logs (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    ts DATETIME(3) NOT NULL COMMENT '请求时间戳',
    method VARCHAR(10),
    path VARCHAR(512),
    status INT,
    latency_ms INT,
    upstream_cluster VARCHAR(100),
    properties JSON COMMENT '动态字段：headers, trace_id 等'
) ENGINE=InnoDB;

CREATE INDEX idx_ts ON access_logs(ts);
CREATE INDEX idx_path ON access_logs(path(100));
CREATE INDEX idx_status ON access_logs(status);

✅ 设计优势：properties JSON 列适应任意 Header 扩展，避免频繁 DDL

---

4. 接口协议 (Interface Protocol)

Wasm → Collector 通信格式

POST /api/v1/ingest HTTP/1.1
Content-Type: application/json
User-Agent: higress-request-logger/1.0

{
  "timestamp": "2026-02-13T14:30:00.123Z",
  "service": "higress-gateway",
  "trace_id": "b4661070-8f76-11ee-a9d1-0242ac120002",
  "request": {
    "method": "GET",
    "path": "/api/users/123",
    "headers": {
      "user-agent": "curl/7.81.0",
      "x-request-id": "req-abc-456"
    }
  },
  "response": {
    "status": 200,
    "latency_ms": 45,
    "upstream_cluster": "outbound|8080||user-service.default.svc.cluster.local"
  }
}

---

5. 性能与权衡 (Trade-offs)

特性	本方案 (MySQL)	商业方案 (SLS/ELK)
部署复杂度	⭐ 极低（仅需 MySQL）	⚠️ 高（需维护 Agent/Queue/Indexer）
查询能力	🔍 基础 SQL + JSON_EXTRACT	🌐 全文检索、多维分析、可视化
写入吞吐	🐢 ~2,000 QPS（单 MySQL 实例）	🚀 百万级 QPS
数据可靠性	🌧️ Collector 重启可能丢缓冲数据	🛡️ 持久化队列保障
适用场景	✅ POC / 测试 / 小流量业务	✅ 生产核心业务 / 高合规要求

📌 明确边界：本方案不替代企业级日志系统，而是为轻量场景提供“最小可行方案”，降低 Higress 使用门槛。

---

6. 实施路线图 (Implementation Plan)

Phase 1: Wasm 插件（核心贡献）

• 实现 request-logger-http 插件（Go + TinyGo）
• 添加单元测试（Mock Host Calls 验证逻辑）
• 编写插件文档：plugins/wasm-go/extensions/request-logger-http/README.md
• 提交 PR 至 alibaba/higress 仓库

Phase 2: 参考实现与示例

• 创建 examples/log-collector/ 目录：
  • collector/main.go（Go 服务）
  • docker-compose.yaml（Higress + Collector + MySQL + Grafana）
  • grafana/dashboard.json（基础访问日志看板）
• 编写端到端教程：docs/guides/lightweight-logging.md
• （可选）发布独立 Helm Chart 简化部署

---

7. FAQ

Q: 为什么插件不直接写 MySQL？
A: 避免 Wasm 沙箱内处理 DB 连接（性能/安全风险），且丧失通用性。HTTP 推送模式可对接任意后端（如 Loki、自研系统）。

Q: 如何避免日志丢失？
A: 本方案定位“尽力而为”。生产环境建议：

• Collector 前置 Kafka/Pulsar
• 使用商业日志服务
• 本方案仅用于非关键场景

Q: 是否支持其他数据库？
A: Collector 作为参考实现提供 MySQL 版本。社区可基于相同 HTTP 协议开发 PostgreSQL/SQLite 等变体。

---

✅ 本提案核心价值：
插件通用化（易合并） + 方案轻量化（易使用） + 实现参考化（易扩展）
欢迎社区评审与建议！ 🙏

---

[RFC] Higress lightweight logging solution: based on HTTP push and MySQL storage

1. Background and Motivation

Current Higress observability solutions (such as ELK, Kafka, Prometheus + Grafana or commercial SLS) are too expensive to deploy for users in the following scenarios:

• ✅ POC/Demonstration Environment: Quickly verify gateway capabilities within 5 minutes
• ✅ Resource Constrained Environment: No operations team to support heavy logging stack
• ✅ Lightweight business: average daily requests < 100,000, no complex analysis required

Goal of this solution: Provide zero external dependencies, out-of-the-box log collection capabilities, realize the minimum feasible log link through Wasm plug-in + lightweight Collector + MySQL, while maintaining plug-in versatility to facilitate community integration.

---

2. Architecture design (Architecture)

Adopt Side-channel Push mode to decouple the data plane and collection logic:

Core Principles:

• 🔒 Gateway stability first: Log push failure will never block the main request flow
• 🧩 Plug-in generalization: Wasm plug-in is only responsible for HTTP push and does not bind storage
• 📦 Reference Implementation Separation: MySQL Collector is provided independently as a sample component

---

3. Detailed Design

3.1 Component 1: Universal HTTP log push plug-in (request-logger-http)

Properties	Description
Language	Go (TinyGo/Wasm)
Trigger phase	OnLog (executed asynchronously after the request is completed)
Warehouse path	plugins/wasm-go/extensions/request-logger-http/

Configuration parameters (plugin.yaml)

service_name: "higress-gateway" # Gateway identification
backend_cluster: "outbound|8080||log-collector.default.svc.cluster.local"
endpoint: "/api/v1/ingest" # Collector receiving endpoint
timeout_ms: 50 # Push timeout (Fail-fast)
sample_rate: 100 # Sampling rate (0-100)
headers_to_extract: # Headers to be extracted
  - "user-agent"
  - "x-request-id"
  - "x-real-ip"

Core logic

1. Extract standard fields: method, path, status, latency_ms, upstream_cluster
2. Extract specified headers according to configuration
3. Assemble the JSON body (see Section 4)
4. Call proxywasm.DispatchHttpCall for asynchronous push
5. Error handling: Silently discard all push failures (Fire-and-forget) to ensure gateway SLA

💡 Key design: The plug-in is not aware of the storage type and only serves as a general pipeline of "request context → JSON → HTTP push"

---

3.2 Component 2: Log Receiving Service (Reference Implementation)

📌 Positioning: As a reference implementation under the examples/log-collector/ directory, non-Higress core code
🌐 Repository suggestions: independent warehouse higress-examples/log-collector or Higress warehouse examples/ subdirectory

Core Competencies

• HTTP service: receive POST /api/v1/ingest
• Memory Ring Buffer: Channel + timing/quantitative dual trigger Flush
• Batch writing: execute INSERT ... VALUES (...), (...) every 1 second or when 100 items are reached
• Graceful shutdown: clear buffer on SIGTERM

MySQL Schema

CREATE TABLE access_logs (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    ts DATETIME(3) NOT NULL COMMENT 'Request timestamp',
    method VARCHAR(10),
    path VARCHAR(512),
    status INT,
    latency_ms INT,
    upstream_cluster VARCHAR(100),
    properties JSON COMMENT 'Dynamic fields: headers, trace_id, etc.'
) ENGINE=InnoDB;

CREATE INDEX idx_ts ON access_logs(ts);
CREATE INDEX idx_path ON access_logs(path(100));
CREATE INDEX idx_status ON access_logs(status);

✅ Design advantage: properties JSON column adapts to any Header extension to avoid frequent DDL

---

4. Interface Protocol

Wasm → Collector communication format

POST /api/v1/ingest HTTP/1.1
Content-Type: application/json
User-Agent: higress-request-logger/1.0

{
  "timestamp": "2026-02-13T14:30:00.123Z",
  "service": "higress-gateway",
  "trace_id": "b4661070-8f76-11ee-a9d1-0242ac120002",
  "request": {
    "method": "GET",
    "path": "/api/users/123",
    "headers": {
      "user-agent": "curl/7.81.0",
      "x-request-id": "req-abc-456"
    }
  },
  "response": {
    "status": 200,
    "latency_ms": 45,
    "upstream_cluster": "outbound|8080||user-service.default.svc.cluster.local"
  }
}

---

5. Performance and Trade-offs

Features	This plan (MySQL)	Business plan (SLS/ELK)
Deployment Complexity	⭐ Very low (only MySQL required)	⚠️ High (needs to maintain Agent/Queue/Indexer)
Query capability	🔍 Basic SQL + JSON_EXTRACT	🌐 Full-text search, multi-dimensional analysis, visualization
Write Throughput	🐢 ~2,000 QPS (single MySQL instance)	🚀 Millions of QPS
Data reliability	🌧️ Collector restart may lose buffered data	🛡️ Persistence queue guarantee
Applicable Scenarios	✅ POC / Testing / Small Traffic Business	✅ Production Core Business / High Compliance Requirements

📌 Clear boundaries: This solution does not replace the enterprise-level log system, but provides a "minimum feasible solution" for lightweight scenarios and lowers the threshold for using Higress.

---

6. Implementation Plan

Phase 1: Wasm plugin (core contribution)

• Implement request-logger-http plugin (Go + TinyGo)
• Add unit test (Mock Host Calls verification logic)
• Write plugin documentation: plugins/wasm-go/extensions/request-logger-http/README.md
• Submit PR to alibaba/higress repository

Phase 2: Reference implementation and examples

• Create examples/log-collector/ directory:
  • collector/main.go (Go service)
  • docker-compose.yaml (Higress + Collector + MySQL + Grafana)
  • grafana/dashboard.json (basic access log dashboard)
• Writing an end-to-end tutorial: docs/guides/lightweight-logging.md
• (optional) Publish a standalone Helm Chart to simplify deployment

---

7. FAQ

**Q: Why doesn’t the plug-in directly write MySQL? **
A: Avoid handling DB connections in the Wasm sandbox (performance/security risks) and loss of versatility. HTTP push mode can be connected to any backend (such as Loki, self-developed systems).

**Q: How to avoid log loss? **
A: This program is positioned as “do your best”. Recommendations for production environments:

• Collector front-ends Kafka/Pulsar
• Use commercial logging services
• This solution is only used in non-critical scenarios

**Q: Does it support other databases? **
A: Collector is provided as a reference implementation for MySQL. The community can develop variants such as PostgreSQL/SQLite based on the same HTTP protocol.

---

✅ Core value of this proposal:
Plug-in generalization (easy to merge) + Lightweight solution (easy to use) + Reference implementation (easy to expand)
Community reviews and suggestions are welcome! 🙏

[CLAassistant]

All committers have signed the CLA.