Edge Processor environment variables

Configure environment variables to tune specific settings for an Edge Processor instance, including exporter, receiver, and queue settings.

You can tune the configuration of a specific Edge Processor instance by setting environment variables on the host machine.

Note: Setting these environment variables can impact system resource usage, such as by increasing the amount of memory used by the Edge Processor instance. Test your configuration updates in an isolated environment before applying them broadly to your Edge Processor instances.

For information about how to set these environment variables, see the following sections:

For complete information about the available environment variables, see the following sections:

Setting the environment variables

How you set the environment variables depends on whether the Edge Processor instance is managed by systemd.

Is the instance managed by systemd? Instructions Example
Yes

Set the environment variable in the systemd unit file. Do the following:

  1. (Optional) To verify the location of the systemd unit file, run the following command on the host machine of the Edge Processor instance:

    CODE 
    systemctl status splunk-edge

  2. In the [Service] section of the file, for each environment variable that you want to set, enter a new line using the following format:

    CODE 
    Environment="<variable_name>=<value>"

The following settings limit the maximum number of syslog TCP connections on port 514 to 20, and specify that syslog TCP connections on port 514 can be idle for 5 minutes before they are closed.

CODE 
[Service]
Environment="EDGE_SYSLOG_TCP_514_CONN_LIMIT=20"
Environment="EDGE_SYSLOG_TCP_514_IDLE_TIMEOUT=5m"
No

Use the export command to set the environment variable, and then restart the splunk-edge process. Do the following:

  1. On the host machine of the Edge Processor instance, for each environment variable that you want to set, run the export command using the following format:

    CODE 
    export <variable_name>=<value>

  2. Restart the splunk-edge process:

    1. Run the following command, replacing <pid> with the process id (PID) for splunk-edge:

      CODE 
      kill <pid>

    2. Run the following command, replacing both of the <install_location> placeholders with the directory where you installed the Edge Processor instance:

      CODE 
      nohup <install_location>/splunk-edge run >> <install_location>/splunk-edge/var/log/install-splunk-edge.out 2>&1 </dev/null &

The following export command limits the maximum number of syslog TCP connections on port 514 to 20:

CODE 
export EDGE_SYSLOG_TCP_514_CONN_LIMIT=20

Supported values

Each environment variable can be set to a specific type of value or list of values. The following table defines the supported value types:

Value type Description
<boolean>

One of the following values:

  • true

  • false
<duration string>

A string that indicates a time duration. This string must be a number followed by a unit of measurement.

For example:

  • 30s indicates 30 seconds.

  • 5m indicates 5 minutes.

  • 6h indicates 6 hours.
<non-negative integer> An integer that is equal to or greater than 0.
<positive integer> An integer that is greater than 0.

Processor Tuning

PROCESSOR_BUFFER_BATCH_SIZE = <positive integer>
* Maximum number of events accumulated in the buffer before flushing downstream.
* Larger values reduce per-batch overhead but increase memory usage and latency
  for the first event in each batch.
* Used in S2S and Syslog receiver pipelines.
* Default: 128

PROCESSOR_BUFFER_BATCH_TIMEOUT_MS = <positive integer>
* Maximum time in milliseconds the buffer waits before flushing a partial batch
  (one that hasn't reached PROCESSOR_BUFFER_BATCH_SIZE).
* Acts as an upper-bound on latency — even at low throughput, events will not
  sit in the buffer longer than this timeout.
* Used in S2S and Syslog receiver pipelines.
* Default: 10

PROCESSOR_SPL2_SOURCE_TYPE_BY_AGENT = <boolean>
* Enables processor_bytes_in_by_agent_total metrics to be broken down by
  forwarding agent type, such as universal forwarder or heavy forwarder.
* When enabled, metrics include "agent" dimension in addition to sourcetype.
* Default: false

PROCESSOR_SOURCE_TYPE_CARDINALITY_SIZE = <positive integer>
* Maximum number of distinct sourcetypes tracked individually in metrics, using a
  least-recently-used (LRU) cache.
* When the number of sourcetypes exceeds this limit, the least-recently-seen ones
  are grouped together and reported under the sourcetype value "__agg__" in Edge
  Processor metrics, rather than under their own name.
* Default: 100

DISABLE_HIGH_CARD_METRIC = <boolean>
* Disables processor_events_in_total and processor_events_out_total metrics.
* Use when event-level cardinality becomes too high for metrics backend.
* Default: false

HEC Exporter Tuning

EXPORTER_HEC_TIMEOUT_MS = <positive integer>
* HTTP client timeout for the HEC exporter in milliseconds.
* Maximum duration the HTTP client will wait for a complete response from the
  HEC endpoint before aborting the request.
* Increase for high-latency HEC destinations (e.g., cross-region writes,
  overloaded indexers) to avoid premature request cancellation.
* Default: 10000 (10 seconds)

EXPORTER_HEC_QUEUE_CONSUMER_NUM = <positive integer>
* Number of queue consumer threads for HEC exporter.
* Default: The value of QUEUE_CONSUMER_NUM.
  If QUEUE_CONSUMER_NUM is not set, then the default is 50.

EXPORTER_HEC_DISABLE_KEEP_ALIVES = <boolean>
* Disables HTTP keep-alive connections to HEC endpoints.
* When true, each request uses a new connection.
* Default: false

EXPORTER_HEC_IDLE_CONN_TIMEOUT_MS = <positive integer>
* Idle connection timeout for HEC HTTP transport in milliseconds.
* Connections idle longer than this duration are closed.
* A value of 0 means no timeout.
* Default: 0

EXPORTER_HEC_MAX_IDLE_CONNS = <non-negative integer>
* Maximum number of idle connections in the HEC HTTP connection pool.
* Default: 100

EXPORTER_HEC_MAX_IDLE_CONNS_PER_HOST = <non-negative integer>
* Maximum number of idle connections per host in the HEC HTTP connection pool.
* Default: 100

MAX_HEC_CONTENT_LENGTH_LOGS = <positive integer>
* Maximum content length in bytes for HEC log batches.
* Default: 2097152 (2 MB)

MAX_HEC_EVENT_SIZE = <positive integer>
* Maximum single HEC event size in bytes.
* Default: 5242880 (5 MB)

HEC_ACCESS_TOKEN_PASSTHROUGH = <boolean>
* Enables HEC access token passthrough from inbound events to HEC destination.
* Set to "false" to disable passthrough and use the configured token only.
* Default: true

S2S Exporter Tuning

EXPORTER_S2S_QUEUE_CONSUMER_NUM = <positive integer>
* Number of queue consumer threads for S2S exporter.
* Default: The value of QUEUE_CONSUMER_NUM.
  If QUEUE_CONSUMER_NUM is not set, then the default is 50.

EXPORTER_S2S_TIMEOUT_SEC = <positive integer>
* S2S exporter overall timeout in seconds.
* If S2S_SEND_TIMEOUT_MILLIS exceeds this value, the timeout is automatically
  raised.
* Default: 15

EXPORTER_S2S_MIN_FREEZE_DURATION = <duration string>
* Minimum duration to freeze an S2S target after a connection failure.
* Frozen targets are temporarily removed from the load-balancing pool.
* Default: "5m"

EXPORTER_S2S_MAX_FREEZE_DURATION = <duration string>
* Maximum duration to freeze an S2S target after repeated connection failures.
* Default: "5m"

S2S_CONNECTION_TTL_DURATION = <duration string>
* Time-to-live for S2S connections.
* Connections are closed and reopened after this duration.
* A value of "0s" means no TTL (connections live indefinitely until broken).
* Default: "0s"

S2S_CONNECTIONS_PER_TARGET = <non-negative integer>
* Number of S2S connections to establish per target.
* When this environment variable is set to 0, the exporter automatically selects
  an appropriate connection count based on the number of resolved target IP
  addresses: 4 connections for up to 3 targets, 3 for 4–5, 2 for 6–9, and 1
  when there are 10 or more.
* Default: 0

S2S_SEND_TIMEOUT_MILLIS = <positive integer>
* Per-write send timeout for S2S protocol in milliseconds.
* Maximum duration for a single S2S write operation before timeout.
* Default: 15000 (15 seconds)

S2S_RECEIVER_CONN_LIMIT = <positive integer>
* Maximum number of inbound S2S connections allowed.
* Default: 2000

Persistent Queue Per-Exporter Tuning

Note: Persistent queue size is not controlled by environment variables. To specify the size of the persistent queue, use the Storage size option in the Edge Processor configuration settings. For more information, see Edit the size of your persistent queues. 
EXPORTER_S2S_WAL_BATCH_TIMEOUT_MS = <positive integer>
* Persistent queue batch timeout for S2S exporter in milliseconds.
* Default: 1000

EXPORTER_S2S_WAL_BATCH_SIZE = <positive integer>
* Persistent queue batch size for S2S exporter (number of records per batch).
* Default: 1024

EXPORTER_HEC_WAL_BATCH_TIMEOUT_MS = <positive integer>
* Persistent queue batch timeout for HEC exporter in milliseconds.
* Default: 1000

EXPORTER_HEC_WAL_BATCH_SIZE = <positive integer>
* Persistent queue batch size for HEC exporter (number of records per batch).
* Default: 4096

EXPORTER_S3_WAL_BATCH_TIMEOUT_MS = <positive integer>
* Persistent queue batch timeout for S3 exporter in milliseconds.
* Default: 30000 (30 seconds)

EXPORTER_S3_WAL_BATCH_SIZE = <positive integer>
* Persistent queue batch size for S3 exporter (number of records per batch).
* Default: 10000

EXPORTER_S3_WAL_CONSUMER_COUNT = <positive integer>
* Number of persistent queue consumer threads for S3 exporter.
* Default: 10

EXPORTER_AZURE_WAL_BATCH_TIMEOUT_MS = <positive integer>
* Persistent queue batch timeout for Azure Blob exporter in milliseconds.
* Default: 30000 (30 seconds)

EXPORTER_AZURE_WAL_BATCH_SIZE = <positive integer>
* Persistent queue batch size for Azure Blob exporter (number of records per batch).
* Default: 10000

EXPORTER_AZURE_WAL_CONSUMER_COUNT = <positive integer>
* Number of persistent queue consumer threads for Azure Blob exporter.
* Default: 10

Receiver Tuning

EDGE_SYSLOG_TCP_<PORT>_CONN_LIMIT = <positive integer>
* Sets the maximum number of TCP syslog connections that are allowed for a
  given port number.
* Replace <PORT> with the port number.
* Example: EDGE_SYSLOG_TCP_514_CONN_LIMIT=1000
* Default: 0 (unlimited)

EDGE_SYSLOG_TCP_<PORT>_IDLE_TIMEOUT = <duration string>
* Sets the maximum amount of time that a TCP syslog connection to a given
  port can remain idle before the connection is closed.
* Replace <PORT> with the port number.
* Example: EDGE_SYSLOG_TCP_514_IDLE_TIMEOUT="5m"
* Default: 0 if EDGE_SYSLOG_TCP_<PORT>_CONN_LIMIT is also set to 0.
  "1m" if EDGE_SYSLOG_TCP_<PORT>_CONN_LIMIT is set to a value other than 0.

SYSLOG_UDP_WORKER_NUM = <positive integer>
* Number of UDP syslog workers (readers and processors).
* Each worker reads from the UDP socket and processes events concurrently.
* Default: 5

Extension Tuning

USE_HEALTH_EXTENSION = <boolean>
* Enables the health check extension for Edge Processor components.
* When enabled, components report health status via HTTP on port 13133.
* Endpoint: GET :13133/ — returns overall collector health as JSON.
* Optional query parameters:
  * verbose=true — include per-component health detail in the response.
  * component=<name> — filter verbose output to components matching the given
    name or substring; can be specified multiple times.
  * pipeline=<name> — show a nested view of a single pipeline; use
    pipeline=all for all pipelines.
  * Examples: /?verbose=true, /?verbose=true&component=splunks2s,
    /?pipeline=traces
* The EXTENSION_HEALTH_* variables below become active when this is enabled.
* Default: false

EXTENSION_HEALTH_CONSUMER_BLOCKED_THRESHOLD_MS = <positive integer>
* Threshold in milliseconds for reporting a consumer as blocked.
* If a consumer is blocked longer than this duration, the component is marked
  unhealthy.
* When set, this overrides the threshold for all persistent queues.
* Requires: USE_HEALTH_EXTENSION=true
* Default: 30000 (30 seconds)

EXTENSION_HEALTH_QUEUE_FULL_FILL_THRESHOLD_PCT = <positive integer 1-100>
* Queue fill percentage threshold for reporting queue-full condition.
* When queue fill exceeds this percentage, the component is marked unhealthy.
* Requires: USE_HEALTH_EXTENSION=true
* Default: 100 (report only when queue is completely full)

EXTENSION_HEALTH_RECOVERY_DURATION_SEC = <positive integer>
* Duration in seconds a component must remain healthy after recovering from an
  unhealthy state before it is considered fully recovered.
* Requires: USE_HEALTH_EXTENSION=true
* Default: 60

EXTENSION_HEALTH_TLS_ENABLED = <boolean>
* Enables TLS on the health check extension endpoint.
* When enabled and S2S source has TLS configured, the health endpoint inherits
  the S2S TLS certificates.
* Requires: USE_HEALTH_EXTENSION=true
* Default: true

LOOKUP_UPDATE_INTERVAL = <duration string>
* How often lookup datasets are refreshed from the lookup service.
* Lookup datasets provide enrichment data for SPL2 transformations.
* Default: "4h"

Global / Service Tuning

QUEUE_CONSUMER_NUM = <positive integer>
* Global fallback for queue consumer count across all exporters.
* Individual exporters can override via EXPORTER_<NAME>_QUEUE_CONSUMER_NUM.
* Falls back to this value if exporter-specific variable is not set.
* Default: 50

SERVICE_TELEMETRY_METRICS_LEVEL = basic|normal|detailed
* Controls the detail level of service telemetry metrics.
* "basic" — minimal metrics for production overhead reduction
* "normal" — standard metrics for most deployments
* "detailed" — verbose metrics for debugging and performance analysis
* Default: detailed

Runtime / Observability Tuning

EDGE_LOGGING_LEVEL = debug|info|warn|error|dpanic|panic|fatal
* Log level for Edge Processor (uses Zap logger levels).
* "debug" — verbose logging for development and troubleshooting
* "info" — standard operational logging
* "warn" and above — errors and warnings only
* Default: info