版本：3.10.x

将 Kubernetes 错误日志发送到 Splunk

API7 网关运行在 Kubernetes 时，错误日志由网关容器输出，并在平台层面收集。这不同于使用 splunk-hec-logging 等日志插件在路由层面传输访问日志。

如果需要从 Kubernetes Pod 收集网关错误日志并将其转发到 Splunk 进行集中式故障排查，请使用本指南。

本工作流是在 Kubernetes 上采集网关日志中所述容器输出方式的一个具体化。如果需要在容器输出与 Pod 内文件之间做比较，或使用 Splunk 以外的后端，请先阅读该指南。

前置条件

开始前，请确保：

API7 网关数据面 Pod 正在 Kubernetes 上运行。
可以访问 Splunk Cloud 或自行管理的 Splunk 部署。
可以在 Kubernetes 集群中安装 Helm Chart。
有权限在 Splunk 中创建或使用 HTTP Event Collector（HEC）令牌。

步骤一：准备 Splunk

如果已有 Splunk 和 HEC 令牌，请继续步骤二。

在本地测试环境中，可以使用 Docker Compose 在宿主机上运行 Splunk：

docker-compose.yaml
services:
  splunk:
    image: splunk/splunk:9.2
    container_name: splunk
    hostname: splunk
    environment:
      - SPLUNK_START_ARGS=--accept-license
      - SPLUNK_PASSWORD=yourpassword123
      - SPLUNK_HEC_TOKEN=your-hec-token
    ports:
      - "8000:8000"
      - "8088:8088"
      - "8089:8089"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

启动 Splunk：

docker compose up -d

备注

Collector 在 Kubernetes 中运行，因此 HEC 端点必须能从 Collector Pod 访问。对于宿主机上的 Docker Compose 部署，请使用集群可解析和访问的主机名或 IP。在基于 kind 的本地环境中，可以使用 host.docker.internal。

步骤二：创建 Splunk 索引

为网关错误日志创建专用索引，例如 gateway_error_logs，以便单独搜索和管理保留策略。

步骤三：创建 Splunk HEC 令牌

在 Splunk 中：

进入 Settings > Data Inputs > HTTP Event Collector。
创建新令牌。
记录 HEC 令牌值。

HEC 端点 URL 通常为：

https://<SPLUNK_HOST>:8088/services/collector/event

如果使用上述 Docker Compose 示例和本地 kind 集群，请将 SPLUNK_HOST 设置为 host.docker.internal。

步骤四：安装 Splunk OpenTelemetry Collector

安装适用于 Kubernetes 的 Splunk OpenTelemetry Collector，并将其配置为收集容器日志。

以下示例仅启用日志收集、禁用监控指标和追踪，并将日志条目转发到 gateway_error_logs 索引。

创建如下 values 文件：

values.yaml
clusterName: "my-cluster"

splunkPlatform:
  endpoint: "https://<SPLUNK_HOST>:8088/services/collector/event"
  token: "your-hec-token"
  index: "gateway_error_logs"
  insecureSkipVerify: true

  logsEnabled: true
  metricsEnabled: false
  tracesEnabled: false

logsCollection:
  containers:
    enabled: true
    excludeAgentLogs: true
    extraOperators:
      - type: "filter"
        expr: 'resource["k8s.container.name"] != "gateway"'
      - type: "filter"
        expr: 'attributes["log.iostream"] != "stderr"'

agent:
  resources:
    limits:
      cpu: 1
      memory: 512Mi
    requests:
      cpu: 200m
      memory: 256Mi

❶ 仅保留 API7 网关容器日志，避免 Collector 转发同一节点上其他 Kubernetes 工作负载中类似错误的日志条目。

❷ 保留标准错误流——官方镜像中网关错误日志走的就是这一路。按消息关键词过滤会丢弃有效的 warn、crit、alert 或 emerg 条目，也可能把请求文本中恰好含有该关键词的访问日志保留下来。

如果网关容器使用其他名称，请调整第一个过滤条件。如果将网关配置为写入普通文件而非标准流，请按在 Kubernetes 上采集网关日志所述采集这些文件。

安装 Collector：

helm repo add splunk-otel-collector https://signalfx.github.io/splunk-otel-collector-chart
helm repo update
helm upgrade --install my-splunk-otel-collector \
  -n logging \
  --create-namespace \
  -f values.yaml \
  splunk-otel-collector-chart/splunk-otel-collector

有关高级配置选项，请参阅 Splunk OpenTelemetry Collector Helm Chart 配置值参考。

步骤五：验证日志收集

在 API7 网关 Pod 中生成或等待错误，然后在 Splunk 中搜索：

index="gateway_error_logs" sourcetype="kube:container:gateway"

应能在所配置的索引中看到来自 API7 网关容器的标准错误条目。

故障排查

确认 logging 命名空间中的 Collector Pod 正常运行；
确认 HEC 端点 URL 和令牌正确；
如果 Splunk 位于集群外，确认 Collector Pod（而不仅是本地 Shell）可以访问 HEC 主机。
检查过滤表达式是否排除了过多数据；
确认网关 Pod 将日志写入 Collector 可以读取的容器输出；
如果 Splunk 使用可信证书，请在生产环境中使用适当的 TLS 配置替换 insecureSkipVerify: true。

后续步骤

在 Kubernetes 上采集网关日志：对比容器输出与 Pod 内的文件，并提供 OpenTelemetry Collector 和 Filebeat 的示例。
配置集中式日志记录：比较文件传输、基于 Collector 的传输和基于插件的日志记录方式。
将访问日志发送到 Splunk：直接从网关发送访问日志。
配置分布式追踪：需要请求级可见性时，将运行时故障与追踪信息关联起来。

前置条件​

步骤一：准备 Splunk​

步骤二：创建 Splunk 索引​

步骤三：创建 Splunk HEC 令牌​

步骤四：安装 Splunk OpenTelemetry Collector​

步骤五：验证日志收集​

故障排查​

后续步骤​