跳到主要内容

rocketmq-logger

rocketmq-logger 插件批量将网关请求和响应日志发送到 Apache RocketMQ。它支持默认的结构化日志格式、原始 HTTP 请求格式以及自定义日志字段。

示例​

以下示例演示如何为常见日志场景配置 rocketmq-logger 插件。

要完成这些示例，请启动 RocketMQ NameServer 和 Broker。Docker 设置使用专用网络，使正在运行的 APISIX 或 API7 网关容器能够通过容器名称访问 RocketMQ。

将 GATEWAY_CONTAINER 设置为正在运行的 APISIX 或 API7 网关容器名称。创建专用 Docker 网络并将网关连接到该网络：

export GATEWAY_CONTAINER=replace-with-gateway-container-name

docker network create gateway-rocketmq-net
docker network connect gateway-rocketmq-net "$GATEWAY_CONTAINER"

创建 Docker Compose 文件：

docker-compose.yml
services:
  rocketmq-namesrv:
    image: apache/rocketmq:5.5.0
    container_name: rocketmq-namesrv
    restart: unless-stopped
    command: ["nameserver"]
    networks:
      - gateway-rocketmq-net

  rocketmq-broker:
    image: apache/rocketmq:5.5.0
    container_name: rocketmq-broker
    restart: unless-stopped
    depends_on:
      - rocketmq-namesrv
    environment:
      NAMESRV_ADDR: rocketmq-namesrv:9876
    command: ["broker", "-n", "rocketmq-namesrv:9876"]
    networks:
      - gateway-rocketmq-net

networks:
  gateway-rocketmq-net:
    external: true

启动容器：

docker compose up -d

等待 Broker 向 NameServer 注册：

until docker exec rocketmq-namesrv sh mqadmin clusterList \
  -n rocketmq-namesrv:9876 2>/dev/null | grep -q "DefaultCluster"; do
  sleep 2
done

创建 TopicTest 主题：

docker exec rocketmq-namesrv sh mqadmin updateTopic \
  -n rocketmq-namesrv:9876 \
  -t TopicTest \
  -c DefaultCluster

以下 Admin API 和 ADC 示例使用 Docker 环境及其 rocketmq-namesrv:9876 地址。Ingress Controller 示例使用 Kubernetes 环境及其 rocketmq-namesrv.aic.svc:9876 服务地址。如果使用其他组合，请将该地址替换为网关可访问的 RocketMQ NameServer 端点。

检查 RocketMQ 消息​

在以下示例中发送请求后，请使用与你的环境对应的命令检查 TopicTest 中的消息：

docker exec rocketmq-namesrv sh mqadmin printMsg \
  -n rocketmq-namesrv:9876 \
  -t TopicTest

比较结构化日志与原始请求日志​

default 元数据格式发送结构化 JSON 日志条目，而 origin 格式发送原始 HTTP 请求。此示例会配置这两种格式，以便比较它们的输出。

创建一个启用 rocketmq-logger 的路由，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes/rocketmq-logger-route" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "uri": "/anything",
    "plugins": {
      "rocketmq-logger": {
        "nameserver_list": [ "rocketmq-namesrv:9876" ],
        "topic": "TopicTest",
        "key": "key1",
        "timeout": 30,
        "meta_format": "default",
        "batch_max_size": 1
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

❶ meta_format：使用结构化 JSON 日志格式。

❷ batch_max_size：为便于测试，立即发送每条日志。

向路由发送请求以生成日志条目：

curl -i "http://127.0.0.1:9080/anything"

使用与你的环境对应的检查命令。消息体应包含与以下内容类似的日志条目：

{
  "client_ip": "127.0.0.1",
  "upstream": "34.197.122.172:80",
  "start_time": 1789377954622,
  "request": {
    "headers": {
      "host": "127.0.0.1:9080",
      "accept": "*/*",
      "user-agent": "curl/8.6.0"
    },
    "querystring": {},
    "size": 86,
    "uri": "/anything",
    "url": "http://127.0.0.1:9080/anything",
    "method": "GET"
  },
  "route_id": "rocketmq-logger-route",
  "apisix_latency": 8.9998455047607,
  "upstream_latency": 503,
  "latency": 511.99984550476,
  "response": {
    "size": 617,
    "headers": {
      "content-length": "391",
      "connection": "close",
      "date": "Mon, 14 Sep 2026 09:25:54 GMT",
      "server": "APISIX/3.18.0",
      "content-type": "application/json"
    },
    "status": 200
  },
  "server": {
    "hostname": "apisix",
    "version": "3.18.0"
  },
  "service_id": ""
}

将 rocketmq-logger 的元日志格式更新为 origin：

curl "http://127.0.0.1:9180/apisix/admin/routes/rocketmq-logger-route" -X PATCH \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "plugins": {
      "rocketmq-logger": {
        "meta_format": "origin"
      }
    }
  }'

再次向路由发送请求以生成新的日志条目：

curl -i "http://127.0.0.1:9080/anything"

再次使用检查命令。新消息体应包含原始 HTTP 格式的请求：

GET /anything HTTP/1.1
host: 127.0.0.1:9080
user-agent: curl/8.6.0
accept: */*

使用插件元数据自定义日志字段​

使用插件元数据为每个 rocketmq-logger 实例应用通用日志格式。以下配置使用内置变量记录一个请求头和一个响应头。

首先，创建一个启用 rocketmq-logger 的路由，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes/rocketmq-logger-route" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "uri": "/anything",
    "plugins": {
      "rocketmq-logger": {
        "nameserver_list": [ "rocketmq-namesrv:9876" ],
        "topic": "TopicTest",
        "key": "key1",
        "timeout": 30,
        "meta_format": "default",
        "batch_max_size": 1
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

❶ meta_format：使用 default，因为插件元数据不会自定义 origin 格式的日志。

❷ batch_max_size：为便于测试，立即发送每条日志。

接下来，配置 rocketmq-logger 的插件元数据：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/rocketmq-logger" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "log_format": {
      "host": "$host",
      "@timestamp": "$time_iso8601",
      "client_ip": "$remote_addr",
      "env": "$http_env",
      "resp_content_type": "$sent_http_Content_Type"
    }
  }'

❶ 记录自定义请求头 env。

❷ 记录响应头 Content-Type。

向路由发送带有 env 头的请求：

curl -i "http://127.0.0.1:9080/anything" -H "env: dev"

使用检查命令。消息体应包含与以下内容类似的日志条目：

{
  "host": "127.0.0.1",
  "client_ip": "127.0.0.1",
  "resp_content_type": "application/json",
  "route_id": "rocketmq-logger-route",
  "env": "dev",
  "@timestamp": "2026-09-14T09:28:24+00:00"
}

有条件地记录请求体​

以下示例仅在 log_body 查询参数为 yes 时记录请求体。

创建一个启用 rocketmq-logger 的路由，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes/rocketmq-logger-route" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "plugins": {
      "rocketmq-logger": {
        "nameserver_list": [ "rocketmq-namesrv:9876" ],
        "topic": "TopicTest",
        "key": "key1",
        "timeout": 30,
        "meta_format": "default",
        "batch_max_size": 1,
        "include_req_body": true,
        "include_req_body_expr": [["arg_log_body", "==", "yes"]]
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    },
    "uri": "/anything"
  }'

❶ include_req_body：启用请求体日志记录。

❷ include_req_body_expr：仅当 log_body 查询参数为 yes 时记录请求体。

发送包含 log_body=yes 的请求：

curl -i "http://127.0.0.1:9080/anything?log_body=yes" -X POST -d '{"env": "dev"}'

使用检查命令。消息体应包含请求体：

{
  ...,
  "request": {
    ...,
    "method": "POST",
    "body": "{\"env\": \"dev\"}",
    "size": 183
  }
}

发送另一个不包含该查询参数的请求：

curl -i "http://127.0.0.1:9080/anything" -X POST -d '{"env": "dev"}'

再次使用检查命令。新消息体不应包含请求体。

信息

自定义日志格式不会自动添加已收集的请求体或响应体。请在格式中包含对应变量：

{
  "include_req_body": true,
  "include_resp_body": true,
  "log_format": {
    "request_body": "$request_body",
    "response_body": "$resp_body"
  }
}

请求体和响应体大小限制仍然适用。如需在不替换默认日志条目的情况下添加自定义字段，请使用 log_format_extra。