Send Access Logs to Splunk

Send API7 Gateway access logs to Splunk using the HTTP Event Collector (HEC) logging plugin.

API7 Gateway can send access logs directly to Splunk using the HTTP Event Collector (HEC) protocol via the splunk-hec-logging plugin. This enables centralized log analysis, alerting, and dashboarding in Splunk without requiring a separate log forwarder.

Use this guide for the integration workflow. For the full plugin parameter and metadata reference, see splunk-hec-logging.

If you want to collect gateway error logs from Kubernetes pods rather than stream request access logs from routes, see Send Kubernetes Error Logs to Splunk.

Prerequisites

A running API7 Gateway deployment.
A Splunk instance with HTTP Event Collector (HEC) enabled.
An HEC token generated in Splunk.
A token from the Dashboard.

Step 1: Enable HEC in Splunk

In Splunk, navigate to Settings > Data Inputs > HTTP Event Collector.
Click New Token and configure:
- Name: A descriptive name (e.g., api7-gateway).
- Source type: _json.
- Index: Select or create an index for gateway logs (e.g., main).
Save and record the HEC token.

The HEC endpoint URL is typically https://<SPLUNK_HOST>:8088/services/collector/event.

Step 2: Enable the Plugin

You can enable splunk-hec-logging either on a single route (to log only selected traffic) or as a global rule (to log all traffic in the gateway group). Choose one of the options below.

Option A: Per-route

# Create a service for the upstream
curl -k "https://localhost:7443/apisix/admin/services/splunk-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "splunk-service",
    "upstream": {
      "type": "roundrobin",
      "nodes": [
        { "host": "httpbin.org", "port": 80, "weight": 1 }
      ]
    }
  }'

# Create a route that uses the service and enables the plugin
curl -k "https://localhost:7443/apisix/admin/routes/splunk-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "splunk-route",
    "service_id": "splunk-service",
    "paths": ["/anything/*"],
    "plugins": {
      "splunk-hec-logging": {
        "endpoint": {
          "uri": "https://splunk.example.com:8088/services/collector/event",
          "token": "YOUR_HEC_TOKEN"
        }
      }
    }
  }'

adc.yaml

services:
  - name: splunk-service
    routes:
      - name: splunk-route
        uris:
          - /anything/*
        plugins:
          splunk-hec-logging:
            endpoint:
              uri: "https://splunk.example.com:8088/services/collector/event"
              token: "YOUR_HEC_TOKEN"
    upstream:
      type: roundrobin
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1

adc sync -f adc.yaml

Option B: Global rule

A global rule applies the plugin to every request handled by the gateway group. You still need at least one route for traffic to match.

curl -k "https://localhost:7443/apisix/admin/global_rules/splunk-hec-logging?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "splunk-hec-logging": {
        "endpoint": {
          "uri": "https://splunk.example.com:8088/services/collector/event",
          "token": "YOUR_HEC_TOKEN"
        }
      }
    }
  }'

adc.yaml

global_rules:
  splunk-hec-logging:
    endpoint:
      uri: "https://splunk.example.com:8088/services/collector/event"
      token: "YOUR_HEC_TOKEN"

adc sync -f adc.yaml

Optional: Customize Log Format

Use plugin metadata to override the default fields included in each event. Values support NGINX $variable syntax. The example below shows three common fields; for the full default format and all supported variables, see splunk-hec-logging.

curl -k "https://localhost:7443/apisix/admin/plugin_metadata/splunk-hec-logging?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "log_format": {
      "method": "$request_method",
      "uri": "$request_uri",
      "status": "$status"
    }
  }'

adc.yaml

plugin_metadata:
  splunk-hec-logging:
    log_format:
      method: "$request_method"
      uri: "$request_uri"
      status: "$status"

adc sync -f adc.yaml

This metadata applies to all splunk-hec-logging plugin instances in the same gateway group.

Verify

Send a test request through the gateway:

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

In Splunk, search for the log entry using the index you chose in Step 1:

index=main source="apache-apisix-splunk-hec-logging"

You should see an event with the request details. The plugin batches events before sending to Splunk, so allow a few seconds for the entry to appear.