跳到主要内容

google-cloud-logging

google-cloud-logging 插件将请求和响应日志以批处理的方式推送到 Google Cloud Logging Service，并支持自定义日志格式。

示例​

以下示例展示了如何在不同场景下配置 google-cloud-logging 插件。

要按照示例操作，你应该拥有一个已激活计费的 GCP 账户。你还应该首先通过完成以下步骤在 GCP 中获取身份验证凭据：

  • 访问 IAM & Admin 创建服务账户。
  • 为服务账户分配 Logs Writer 角色，该角色为账户分配 logging.logEntries.create 和 logging.logEntries.route 权限。
  • 为服务账户创建私钥并下载 JSON 格式的凭据。

凭据 JSON 文件内容应类似于以下内容：

{
  "type": "service_account",
  "project_id": "api7ai-docs",
  "private_key_id": "6330a8c37b15a26d3fb4e9e3986f04c004826d1a",
  "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDYTl1QKxgClpgq\n1FyZNKZTq4os9AoXU+h/1gdngtc681xqMIWlwycrJ7Bo69L//7REyUKnuIOPgHU6\nPCp4rGFokxdXzBJC0+WsxwZ/FZoaqLAD5Fbs4BpZ9q2F8fKz07l9Da+Ul2lLlQq6\nEgij2NOh9ytBvFiYEAnMY5DDWFyoXWBB0OXfGEE6486+DcfG8gMWQ7rXKVbKNyA1\nJdbS63cDJNERLb6z8QsaZOqYZwaqIn6apEv9aadnNEU+4HrXrjxsoDtk7zLmsbtp\nUOpYVVSiYz2uYbUz3XRJjW+NAeyeVBK8tePbe1n5WHM4Sg1Mp1wYtaJknS5gmOXe\nxglMt4vTAgMBAAECggEAHzGZ6mRJ56GmcH1vRywyalw8JoR2ahZ7L+hX6VkTR0ND\nn2VqTf/pR6Nxy4fAG5QEKsFS1VOE1tk3I/6mP1XYtwHeEBbJcWK+kLP5CghoULzl\nTq0LeMikHu+uY6w8OUlVTS/UQtC+SxwVMbstlEGyhWERxjdu0VwL\nY/jb6DA123cqjHteEwOFuipG+GELKJGIjgNhzyRimowOsY6F+3WrDHZrf2sM7AlD\nLbjrA3MdvIe6rNC8zy7zf/didygjryrJpjiHkKsLIPIPbu0l5xENHd3TNWuVAg48\nhf4nRwyZ7q1RXgRYnp/SfPH1YB0p4+7D0xLQUd2OEQKBgQDxvOED6IQ3zxipW+uX\nX4c+6QxwnOCTY/oQOtCwmgPSvzIMSyoNCH0YY3sdoUmygSP0hmBFIaP\nBH6A5d3A06iMTUiAwEOp5JDQImqVTN+Sz/JBBOxCpjuW/dmG72MFlZBL161lY0g6\n79ku2xatxvncdJvcpEWqB4UBEQKBgQDlEV/Tapm950M+PYTtYHry1AYxGum+Eb2+\nNg9u5kWbgl6aWSgR/XsKQPTcsYX0gFSkrYhFrVwdruDeG9JYSCckH6FtCoa8yv5s\nMB+QR7VWJoa3ej7Hc0O6VUjwUfUkXuQRoFCEl8lFCZzugsjSw93xTeo6w3s9oaCB\neY9RXGn+owKBgQCMU/Tba/K04weR6MZOTSoZnveVt7u2U+cp3LqgigeGI29OK6Px\nhOf5bGZfwO0jLlJAVJin5tdtgK1FfUDPbPByqv2bnkLNj19zPikJSqG18QSmPsXa\nV9RtYgo0doNJF3tbFUQKTdRB8qW5oXSgofMVfCEiJ8uL6jVAVCwMk+jlwQKBgQCD\ntE6lbwhAcORvt81i8nMehRueRjwYpXi0Eb8j41AoTnf4RMTOOzDwP1LKRWOgpdyE\n5qWQclGhW3g9HD//tFSU537YBBJeIFTSfYTYXvJ7OyGAAtBvuu05CGosiuLo64o0\nPDmvUtpNUG6jkBzJWgaVBFhlOxnz4Kc5alwlyn3DAwKBgQCwNJsqb4pOjwjaJl/m\nePXpeX7YdVyFnBDbSQ1BFxDYGU12yTKRYqQVIB+VIIGN28acta1EPI8tF2ODG5az\nCBmgH5amLRHHCDYRKwrP+BTA39lK0pQEUP47RSzOdY82KQB13BW1uEZTcifjS9HN\niZPoV+OYHG5iJiiWEQi9/Q1AfQ==\n-----END PRIVATE KEY-----\n",
  "client_email": "api7-docs-log@api7ai-docs.iam.gserviceaccount.com",
  "client_id": "100920913890704420895",
  "auth_uri": "https://accounts.google.com/o/oauth2/auth",
  "token_uri": "https://oauth2.googleapis.com/token",
  "auth_provider_x509_cert_url": "https://www.googleapis.com/oauth2/v1/certs",
  "client_x509_cert_url": "https://www.googleapis.com/robot/v1/metadata/x509/api7-docs-log%40api7ai-docs.iam.gserviceaccount.com",
  "universe_domain": "googleapis.com"
}

使用 auth_config 配置身份验证​

以下示例展示了如何在路由上配置 google-cloud-logging 插件，记录客户端请求和响应，并将日志推送到 Google Cloud Logging。你将使用 auth_config 选项配置 GCP 身份验证详情。

创建一个启用 google-cloud-logging 的路由，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "google-cloud-logging-route",
    "uri": "/anything",
    "plugins": {
      "google-cloud-logging": {
        "auth_config": {
          // Annotate 1
          "client_email": "api7-docs-logging@api7ai-docs.iam.gserviceaccount.com",
          // Annotate 2
          "project_id": "api7ai-docs",
          // Annotate 3
          "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDYTl1QKxgClpgq\n1FyZNKZTq4os9AoXU+h/1gdngtc681xqMIWlwycrJ7Bo69L//7REyUKnuIOPgHU6\nPCp4rGFokxdXzBJC0+WsxwZ/FZoaqLAD5Fbs4BpZ9q2F8fKz07l9Da+Ul2lLlQq6\nEgij2NOh9ytBvFiYEAnMY5DDWFyoXWBB0OXfGEE6486+DcfG8gMWQ7rXKVbKNyA1\nJdbS63cDJNERLb6z8QsaZOqYZwaqIn6apEv9aadnNEU+4HrXrjxsoDtk7zLmsbtp\nUOpYVVSiYz2uYbUz3XRJjW+NAeyeVBK8tePbe1n5WHM4SnS5gmOXe\nxglMt4vTAgMBAAECggEAHzGZ6mRJ56GmcH1vRywyalw8JoR2ahZ7L+hX6VkTR0ND\nn2VqTf/pR6Nxy4fAG5QEKsFS1VOE1tk3I/6mP1XYtwHeEBbJcWK+kLP5CghoULzl\nTq0LeMikHuI19FxH3HVwSV+uY6w8OUlVTS/UQtC+SxwVMbstlEGyhWERxjdu0VwL\nY/jb6DA123cqjHteEwOFuipG+GELKJGIjgNhzyRimowOsY6F+3WrDHZrf2sM7AlD\nLbjrA3MdvIe6rNC8zy7zf/didygjryrJpjiHkKsLIPIPbu0l5xENHd3TNWuVAg48\nhf4nRwyZ7q1RXgRYnp/SfPH1YB0p4+7D0xLQUd2xvOED6IQ3zxipW+uX\nX4c+6QxwnOCTY/oQOtCwmgPSvzIMSyoNCH0YY3sdoUmygS40v30OV8vP0hmBFIaP\nBH6A5d3A06iMTUiAwEOp5JDQImqVTN+Sz/JBBOxCpjuW/dmG72MFlZBL161lY0g6\n79ku2xatxvncdJvcpEWqB4UBEQKBgQDlEV/Tapm950M+PYTtYHry1AYxGum+Eb2+\nNg9u5kWbgl6aWSgR/XsKQPTcsYX0gFSkrYhFrVwdruDeG9JYSCckH6FtCoa8yv5s\nMB+QR7VWJoa3ej7Hc0O6VUjwUfUkXuQRoFCEl8lFCZzugsjSw93xTeo6w3s9oaCB\neY9RXGn+owKBgQCMU/Tba/K04weR6MZOTSoZnveVt7u2U+cp3LqgigeGI29OK6Px\nhOf5bGZfwO0jLlJAVJin5tdtgK1FfUDPbPByqv2bnkLNj19zPikJSqG18QSmPsXa\nV9RtYgo0doNJF3tbFUQKTdRB8qW5oXSgofMVfCEiJ8uL6jVAVCwMk+jlwQKBgQCD\ntE6lbwhAcORvt81i8nMehRueRjwYpXi0Eb8j41AoTnf4RMTOOzDwP1LKRWOgpdyE\n5qWQclGhW3g9HD//tFSU537YBBJeIFTSfYTYXvJ7OyGAAtBvuu05CGosiuLo64o0\nPDmvUtpNUG6jkBzJWgaVBFhlOxnz4Kc5alwlyn3DAwKBgQCwNJsqb4pOjwjaJl/m\nePXpeX7YdVyFnBDbSQ1BFxDYGU12yTKRYqQVIB+VIIGN28acta1EPI8tF2ODG5az\nCBmgH5amLRHHCDYRKwrP+BTA39lK0pQEUP47RSzOdY82KQB13BW1uEZTcifjS9HN\niZPoV+OYHG5iJiiWEQi9/Q1AfQ==\n-----END PRIVATE KEY-----\n",
          // Annotate 4
          "token_uri": "https://oauth2.googleapis.com/token"
        }
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

❶ 替换为你的服务账户。

❷ 替换为你的项目 ID。

❸ 替换为你的私钥。

❹ 替换为你的令牌 URI。

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

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

你应该会收到一个 HTTP/1.1 200 OK 响应。

导航到 Google Cloud Logs Explorer，你应该会看到与你的请求对应的日志条目，类似如下：

{
  "insertId": "5400340ea330b35f2d557da2cbb9e88d",
  "jsonPayload": {
    "service_id": "",
    "route_id": "google-cloud-logging-route"
  },
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "http://127.0.0.1:9080/anything",
    "requestSize": "85",
    "status": 200,
    "responseSize": "615",
    "userAgent": "curl/8.6.0",
    "remoteIp": "192.168.107.1",
    "serverIp": "54.86.137.185:80",
    "latency": "1.083s"
  },
  "resource": {
    "type": "global",
    "labels": {
      "project_id": "api7ai-docs"
    }
  },
  "timestamp": "2025-02-07T07:39:51.859Z",
  "labels": {
    "source": "apache-apisix-google-cloud-logging"
  },
  "logName": "projects/api7ai-docs/logs/apisix.apache.org%2Flogs",
  "receiveTimestamp": "2025-02-07T07:39:58.012811475Z"
}

使用 auth_file 配置身份验证​

以下示例展示了如何在路由上配置 google-cloud-logging 插件，记录客户端请求和响应，并将日志推送到 Google Cloud Logging。你将使用 auth_file 选项配置 GCP 身份验证详情。

将之前下载的 GCP 服务账户凭据 JSON 文件复制到 APISIX 可访问的位置。如果你在 Docker 中运行 APISIX，你应该将文件复制到容器中，例如 /usr/local/apisix/conf/gcp-logging-auth.json。

创建一个启用 google-cloud-logging 的路由，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "google-cloud-logging-route",
    "uri": "/anything",
    "plugins": {
      "google-cloud-logging": {
        // Annotate 1
        "auth_file": "/usr/local/apisix/conf/gcp-logging-auth.json"
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

❶ 替换为你的 GCP 服务账户凭据 JSON 文件路径。

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

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

你应该会收到一个 HTTP/1.1 200 OK 响应。

导航到 Google Cloud Logs Explorer，你应该会看到与你的请求对应的日志条目，类似如下：

{
  "insertId": "5400340ea330b35f2d557da2cbb9e88d",
  "jsonPayload": {
    "service_id": "",
    "route_id": "google-cloud-logging-route"
  },
  "httpRequest": {
    "requestMethod": "GET",
    "requestUrl": "http://127.0.0.1:9080/anything",
    "requestSize": "85",
    "status": 200,
    "responseSize": "615",
    "userAgent": "curl/8.6.0",
    "remoteIp": "192.168.107.1",
    "serverIp": "54.86.137.185:80",
    "latency": "1.083s"
  },
  "resource": {
    "type": "global",
    "labels": {
      "project_id": "api7ai-docs"
    }
  },
  "timestamp": "2025-02-07T08:25:11.325Z",
  "labels": {
    "source": "apache-apisix-google-cloud-logging"
  },
  "logName": "projects/api7ai-docs/logs/apisix.apache.org%2Flogs",
  "receiveTimestamp": "2025-02-07T08:25:11.423190575Z"
}

通过插件元数据自定义日志格式​

以下示例展示了如何使用 Plugin Metadata 和 内置变量 自定义日志格式，以记录请求和响应中的特定头部。

在 APISIX 中，Plugin Metadata 用于配置同一插件的所有插件实例的通用元数据字段。当插件在多个资源中启用并且需要对其元数据字段进行通用更新时，这非常有用。

首先，创建一个启用 google-cloud-logging 的路由，如下所示，并替换为你的凭据：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "google-cloud-logging-route",
    "uri": "/anything",
    "plugins": {
      "google-cloud-logging": {
        "auth_config": {
          "client_email": "api7-docs-logging@api7ai-docs.iam.gserviceaccount.com",
          "project_id": "api7ai-docs",
          "private_key": "-----BEGIN PRIVATE KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQDYTl1QKxgClpgq\n1FyZNKZTq4os9AoXU+h/1gdngtc681xqMIWlwycrJ7Bo69L//7REyUKnuIOPgHU6\nPCp4rGFokxdXzBJC0+WsxwZ/FZoaqLAD5Fbs4BpZ9q2F8fKz07l9Da+Ul2lLlQq6\nEgij2NOh9ytBvFiYEAnMY5DDWFyoXWBB0OXfGEE6486+DcfG8gMWQ7rXKVbKNyA1\nJdbS63cDJNERLb6z8QsaZOqYZwaqIn6apEv9aadnNEU+4HrXrjxsoDtk7zLmsbtp\nUOpYVVSiYz2uYbUz3XRJjW+NAeyeVBK8tePbe1n5WHM4SnS5gmOXe\nxglMt4vTAgMBAAECggEAHzGZ6mRJ56GmcH1vRywyalw8JoR2ahZ7L+hX6VkTR0ND\nn2VqTf/pR6Nxy4fAG5QEKsFS1VOE1tk3I/6mP1XYtwHeEBbJcWK+kLP5CghoULzl\nTq0LeMikHuI19FxH3HVwSV+uY6w8OUlVTS/UQtC+SxwVMbstlEGyhWERxjdu0VwL\nY/jb6DA123cqjHteEwOFuipG+GELKJGIjgNhzyRimowOsY6F+3WrDHZrf2sM7AlD\nLbjrA3MdvIe6rNC8zy7zf/didygjryrJpjiHkKsLIPIPbu0l5xENHd3TNWuVAg48\nhf4nRwyZ7q1RXgRYnp/SfPH1YB0p4+7D0xLQUd2xvOED6IQ3zxipW+uX\nX4c+6QxwnOCTY/oQOtCwmgPSvzIMSyoNCH0YY3sdoUmygS40v30OV8vP0hmBFIaP\nBH6A5d3A06iMTUiAwEOp5JDQImqVTN+Sz/JBBOxCpjuW/dmG72MFlZBL161lY0g6\n79ku2xatxvncdJvcpEWqB4UBEQKBgQDlEV/Tapm950M+PYTtYHry1AYxGum+Eb2+\nNg9u5kWbgl6aWSgR/XsKQPTcsYX0gFSkrYhFrVwdruDeG9JYSCckH6FtCoa8yv5s\nMB+QR7VWJoa3ej7Hc0O6VUjwUfUkXuQRoFCEl8lFCZzugsjSw93xTeo6w3s9oaCB\neY9RXGn+owKBgQCMU/Tba/K04weR6MZOTSoZnveVt7u2U+cp3LqgigeGI29OK6Px\nhOf5bGZfwO0jLlJAVJin5tdtgK1FfUDPbPByqv2bnkLNj19zPikJSqG18QSmPsXa\nV9RtYgo0doNJF3tbFUQKTdRB8qW5oXSgofMVfCEiJ8uL6jVAVCwMk+jlwQKBgQCD\ntE6lbwhAcORvt81i8nMehRueRjwYpXi0Eb8j41AoTnf4RMTOOzDwP1LKRWOgpdyE\n5qWQclGhW3g9HD//tFSU537YBBJeIFTSfYTYXvJ7OyGAAtBvuu05CGosiuLo64o0\nPDmvUtpNUG6jkBzJWgaVBFhlOxnz4Kc5alwlyn3DAwKBgQCwNJsqb4pOjwjaJl/m\nePXpeX7YdVyFnBDbSQ1BFxDYGU12yTKRYqQVIB+VIIGN28acta1EPI8tF2ODG5az\nCBmgH5amLRHHCDYRKwrP+BTA39lK0pQEUP47RSzOdY82KQB13BW1uEZTcifjS9HN\niZPoV+OYHG5iJiiWEQi9/Q1AfQ==\n-----END PRIVATE KEY-----\n",
          "token_uri": "https://oauth2.googleapis.com/token"
        }
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

接下来，配置 google-cloud-logging 的插件元数据：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/google-cloud-logging" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "log_format": {
      "host": "$host",
      "@timestamp": "$time_iso8601",
      "client_ip": "$remote_addr",
    }
  }'

向路由发送请求：

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

你应该会收到一个 HTTP/1.1 200 OK 响应。

导航到 Google Cloud Logs Explorer，你应该会看到与你的请求对应的日志条目，类似如下：

{
  "@timestamp":"2025-02-07T09:10:42+00:00",
  "client_ip":"192.168.107.1",
  "host":"127.0.0.1",
  "route_id":"google-cloud-logging-route"
}

如果在单个实例上未具体指定日志格式，则在插件元数据中配置的日志格式对 google-cloud-logging 的所有实例生效。

如果你在路由上的 google-cloud-logging 插件中具体配置了日志格式：

curl "http://127.0.0.1:9180/apisix/admin/routes/google-cloud-logging-route" -X PATCH \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "plugins": {
      "google-cloud-logging": {
        "log_format": {
          "host": "$host",
          "@timestamp": "$time_iso8601",
          "client_ip": "$remote_addr",
          // Annotate 1
          "env": "$http_env",
          // Annotate 2
          "resp_content_type": "$sent_http_Content_Type"
        }
      }
    }
  }'

❶ 记录自定义请求头 env。

❷ 记录响应头 Content-Type。

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

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

你应该会收到一个 HTTP/1.1 200 OK 响应。

导航到 Google Cloud Logs Explorer，你应该会看到与你的请求对应的日志条目，类似如下：

{
  "@timestamp":"2025-02-07T09:38:55+00:00",
  "client_ip":"192.168.107.1",
  "host":"127.0.0.1",
  "env":"dev",
  "resp_content_type":"application/json",
  "route_id":"google-cloud-logging-route"
}

路由上的日志格式配置优先级高于 google-cloud-logging 插件元数据上配置的日志格式。