Splunk HEC Integration

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.

Prerequisites

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

Step 1: Enable HEC in Splunk

1. In Splunk, navigate to Settings > Data Inputs > HTTP Event Collector.
2. 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).
3. 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

Admin API

# Create a service for the upstream
curl -k "https://localhost:7443/apisix/admin/services/splunk-service?gateway_group_id={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={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

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.

Admin API

curl -k "https://localhost:7443/apisix/admin/global_rules/splunk-hec-logging?gateway_group_id={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

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.

Admin API

curl -k "https://localhost:7443/apisix/admin/plugin_metadata/splunk-hec-logging?gateway_group_id={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

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.

Additional Resources

• Logging
• Distributed Tracing
• Log Consumer Labels in Access Log
• Metrics