Aperture Agent Configuration Reference

info

See also Aperture Agent installation.

List of all configuration parameters for Aperture Agent.

Table of contents

AGENT CONFIGURATION

Key	Reference
otel	OTel

COMMON CONFIGURATION

Key	Reference
agent_info	AgentInfo
auto_scale	AutoScaleConfig
client	Client
dist_cache	DistCache
etcd	Etcd
flow_control	FlowControl
agent_functions	Functions
kubernetes_client	KubernetesClient
liveness	Liveness
log	Log
metrics	Metrics
object_storage	ObjectStorage
peer_discovery	PeerDiscovery
profilers	Profilers
prometheus	Prometheus
readiness	Readiness
server	Server
service_discovery	ServiceDiscovery
watchdog	Watchdog

EXTENSION CONFIGURATION

Key	Reference
fluxninja	FluxNinjaExtension
sentry	SentryExtension

Reference

agent_info

(AgentInfoConfig) Environment variable prefix: APERTURE_AGENT_AGENT_INFO_

---

auto_scale

kubernetes

(AutoScaleKubernetesConfig) Environment variable prefix: APERTURE_AGENT_AUTO_SCALE_KUBERNETES_

---

client

proxy

(ProxyConfig) Environment variable prefix: APERTURE_AGENT_CLIENT_PROXY_

---

dist_cache

(DistCacheConfig) Environment variable prefix: APERTURE_AGENT_DIST_CACHE_

---

etcd

(EtcdConfig) Environment variable prefix: APERTURE_AGENT_ETCD_

---

flow_control

preview_service

(FlowPreviewConfig) Environment variable prefix: APERTURE_AGENT_FLOW_CONTROL_PREVIEW_SERVICE_

---

fluxninja

(FluxNinjaExtensionConfig) Environment variable prefix: APERTURE_AGENT_FLUXNINJA_

---

agent_functions

(AgentFunctionsConfig) Environment variable prefix: APERTURE_AGENT_AGENT_FUNCTIONS_

---

kubernetes_client

http_client

(HTTPClientConfig) Environment variable prefix: APERTURE_AGENT_KUBERNETES_CLIENT_HTTP_CLIENT_

---

liveness

scheduler

(JobGroupConfig) Environment variable prefix: APERTURE_AGENT_LIVENESS_SCHEDULER_

service

(JobConfig) Environment variable prefix: APERTURE_AGENT_LIVENESS_SERVICE_

---

log

(LogConfig) Environment variable prefix: APERTURE_AGENT_LOG_

---

metrics

(MetricsConfig) Environment variable prefix: APERTURE_AGENT_METRICS_

---

otel

(AgentOTelConfig) Environment variable prefix: APERTURE_AGENT_OTEL_

---

object_storage

(ObjectStorageConfig) Environment variable prefix: APERTURE_AGENT_OBJECT_STORAGE_

---

peer_discovery

(PeerDiscoveryConfig) Environment variable prefix: APERTURE_AGENT_PEER_DISCOVERY_

---

profilers

(ProfilersConfig) Environment variable prefix: APERTURE_AGENT_PROFILERS_

---

prometheus

(PrometheusConfig) Environment variable prefix: APERTURE_AGENT_PROMETHEUS_

http_client

(HTTPClientConfig) Environment variable prefix: APERTURE_AGENT_PROMETHEUS_HTTP_CLIENT_

---

readiness

scheduler

(JobGroupConfig) Environment variable prefix: APERTURE_AGENT_READINESS_SCHEDULER_

service

(JobConfig) Environment variable prefix: APERTURE_AGENT_READINESS_SERVICE_

---

sentry

(SentryConfig) Environment variable prefix: APERTURE_AGENT_SENTRY_

---

server

grpc

(GRPCServerConfig) Environment variable prefix: APERTURE_AGENT_SERVER_GRPC_

grpc_gateway

(GRPCGatewayConfig) Environment variable prefix: APERTURE_AGENT_SERVER_GRPC_GATEWAY_

http

(HTTPServerConfig) Environment variable prefix: APERTURE_AGENT_SERVER_HTTP_

listener

(ListenerConfig) Environment variable prefix: APERTURE_AGENT_SERVER_LISTENER_

tls

(ServerTLSConfig) Environment variable prefix: APERTURE_AGENT_SERVER_TLS_

---

service_discovery

kubernetes

(KubernetesDiscoveryConfig) Environment variable prefix: APERTURE_AGENT_SERVICE_DISCOVERY_KUBERNETES_

---

watchdog

memory

(WatchdogConfig) Environment variable prefix: APERTURE_AGENT_WATCHDOG_MEMORY_

---

Objects

---

AdaptivePolicy

AdaptivePolicy creates a policy that forces GC when the usage surpasses the configured factor of the available memory. This policy calculates next target as usage+(limit-usage)*factor.

enabled

(bool, default: false)

Flag to enable the policy

factor

(float64, minimum: 0, maximum: 1, default: 0.5)

Factor sets user-configured limit of available memory

---

AgentFunctionsConfig

AgentFunctionsConfig is configuration for agent functions.

endpoints

([]string)

RPC servers to connect to (which will be able to call agent functions)

client

(ClientConfig)

Network client configuration

---

AgentInfoConfig

AgentInfoConfig is the configuration for the agent group and other agent attributes.

agent_group

(string, default: "default")

All agents within an agent group receive the same data-plane configuration (for example, Flux Meters, Rate Limiters and so on).

Read more about agent groups here.

---

AgentOTelConfig

AgentOTelConfig is the configuration for Agent's OTel collector.

disable_kubelet_scraper

(bool, default: false)

DisableKubeletScraper disables the default metrics collection for Kubelet. Deprecated: Kubelet scraper is removed entirely, so this flag makes no difference.

disable_kubernetes_scraper

(bool, default: false)

DisableKubernetesScraper disables the default metrics collection for Kubernetes resources.

enable_high_cardinality_platform_metrics

(bool, default: false)

EnableHighCardinalityPlatformMetrics filters out high cardinality Aperture platform metrics from being published to Prometheus. Filtered out metrics are: "grpcserver_handled_total." "grpcserver_handling_seconds." "grpcserver_handling_seconds_bucket." "grpcserver_handling_seconds_count." "grpcserver_handling_seconds_sum." "grpcserver_msg_received_total." "grpcserver_msg_sent_total." "grpcserver_started_total."

batch_alerts

(BatchAlertsConfig)

BatchAlerts configures batch alerts processor.

batch_postrollup

(BatchPostrollupConfig)

BatchPostrollup configures the OTel batch post-processor.

batch_prerollup

(BatchPrerollupConfig)

BatchPrerollup configures the OTel batch pre-processor.

ports

(PortsConfig)

Ports configures debug, health and extension ports values.

---

AutoScaleKubernetesConfig

AutoScaleKubernetesConfig is the configuration for the flow preview service.

enabled

(bool, default: false)

Enables the Kubernetes auto-scale capability.

---

BackoffConfig

BackoffConfig holds configuration for gRPC client backoff.

base_delay

(string, default: "1s")

Base Delay

jitter

(float64, minimum: 0, default: 0.2)

Jitter

max_delay

(string, default: "120s")

Max Delay

multiplier

(float64, minimum: 0, default: 1.6)

Backoff multiplier

---

BatchAlertsConfig

BatchAlertsConfig defines configuration for OTel batch processor.

send_batch_max_size

(uint32, minimum: 0)

SendBatchMaxSize is the upper limit of the batch size. Bigger batches will be split into smaller units.

send_batch_size

(uint32, minimum: 0)

SendBatchSize is the number of alerts to send in a batch.

timeout

(string, default: "1s")

Timeout sets the time after which a batch will be sent regardless of size.

---

BatchPostrollupConfig

BatchPostrollupConfig defines post-rollup configuration for OTel batch processor.

send_batch_max_size

(uint32, minimum: 0)

SendBatchMaxSize is the upper limit of the batch size. Bigger batches will be split into smaller units.

send_batch_size

(uint32, minimum: 0)

SendBatchSize is the number of metrics to send in a batch.

timeout

(string, default: "1s")

Timeout sets the time after which a batch will be sent regardless of size.

---

BatchPrerollupConfig

BatchPrerollupConfig defines pre-rollup configuration for OTel batch processor.

send_batch_max_size

(uint32, minimum: 0)

SendBatchMaxSize is the upper limit of the batch size. Bigger batches will be split into smaller units.

send_batch_size

(uint32, minimum: 0)

SendBatchSize is the number of metrics to send in a batch.

timeout

(string, default: "10s")

Timeout sets the time after which a batch will be sent regardless of size.

---

ClientConfig

ClientConfig is the client configuration.

grpc

(GRPCClientConfig)

gRPC client settings.

http

(HTTPClientConfig)

HTTP client settings.

---

ClientTLSConfig

ClientTLSConfig is the configuration for client TLS.

ca_file

(string)

cert_file

(string)

insecure_skip_verify

(bool)

key_file

(string)

key_log_file

(string)

---

DistCacheConfig

DistCacheConfig configures distributed cache that holds per-label counters in distributed rate limiters.

bind_addr

(string, format: hostname_port, default: ":3320")

BindAddr denotes the address that DistCache will bind to for communication with other peer nodes.

memberlist_advertise_addr

(string, format: empty | hostname_port)

Address of memberlist to advertise to other cluster members. Used for NAT traversal if provided.

memberlist_bind_addr

(string, format: hostname_port, default: ":3322")

Address to bind memberlist server to.

replica_count

(int64, default: 1)

ReplicaCount is 1 by default.

sync_replication

(bool, default: false)

SyncReplication enables synchronous replication. By default the replication is asynchronous.

---

EtcdConfig

EtcdConfig holds configuration for etcd client.

endpoints

([]string)

List of etcd server endpoints

lease_ttl

(string, default: "10s")

Lease time-to-live

log_level

(string, format: empty | empty, one of: debug | DEBUG | info | INFO | warn | WARN | error | ERROR | dpanic | DPANIC | panic | PANIC | fatal | FATAL, default: "error")

LogLevel of logs coming from inside the etcd client

namespace

(string, default: "aperture")

etcd namespace

password

(string)

username

(string)

Authentication

tls

(ClientTLSConfig)

Client TLS configuration

---

FlowPreviewConfig

FlowPreviewConfig is the configuration for the flow control preview service.

enabled

(bool, default: true)

Enables the flow preview service.

---

FluxNinjaExtensionConfig

FluxNinjaExtensionConfig is the configuration for FluxNinja integration.

api_key

(string)

API Key for this agent. If this key is not set, the extension won't be enabled.

agent_api_key

(string, DEPRECATED)

Deprecated: v3.0.0. Use APIKey instead

controller_id

(string)

Overrides Controller ID for Aperture Controller. If not set, random id will be generated and persisted in etcd.

disable_local_otel_pipeline

(bool, default: false)

Disables local Prometheus OTel pipelines for metrics. Implied by EnableCloudController.

enable_cloud_controller

(bool, default: false)

Whether to connect to Aperture Cloud Controller.

Enabling this flag configures various agent components to point to the Aperture Cloud Controller, for example configures remote etcd endpoint and disables local Prometheus OTel pipelines.

Disable this flag only if using Self-Hosted Aperture Controller.

endpoint

(string, format: empty | hostname_port | url | fqdn)

Address to gRPC or HTTP(s) server listening in agent service. For connecting to Aperture Cloud Controller, the endpoint should be a grpc/http2 address. For self-hosted controller, the HTTP protocol address can start with http(s)://.

heartbeat_interval

(string, default: "5s")

Interval between each heartbeat.

installation_mode

(string, one of: KUBERNETES_SIDECAR | KUBERNETES_DAEMONSET | LINUX_BARE_METAL | CLOUD_AGENT, default: "LINUX_BARE_METAL")

Installation mode describes on which underlying platform the Agent or the Controller is being run.

client

(ClientConfig)

Client configuration.

---

GRPCClientConfig

GRPCClientConfig holds configuration for gRPC Client.

insecure

(bool, default: false)

Disable ClientTLS

min_connection_timeout

(string, default: "20s")

Minimum connection timeout

use_proxy

(bool, default: false)

Use HTTP CONNECT Proxy

backoff

(BackoffConfig)

Backoff configuration

tls

(ClientTLSConfig)

Client TLS configuration

---

GRPCGatewayConfig

GRPCGatewayConfig holds configuration for gRPC to HTTP gateway

grpc_server_address

(string, format: empty | hostname_port)

gRPC server address to connect to - By default it points to HTTP server port because FluxNinja stack runs gRPC and HTTP servers on the same port

---

GRPCServerConfig

GRPCServerConfig holds configuration for gRPC Server.

connection_timeout

(string, default: "120s")

Connection timeout

enable_reflection

(bool, default: false)

Enable Reflection

latency_buckets_ms

([]float64, default: [10,25,100,250,1000])

Buckets specification in latency histogram

---

HTTPClientConfig

HTTPClientConfig holds configuration for HTTP Client.

disable_compression

(bool, default: false)

Disable Compression

disable_keep_alives

(bool, default: false)

Disable HTTP Keepalive

expect_continue_timeout

(string, default: "1s")

Expect Continue Timeout. 0 = no timeout.

idle_connection_timeout

(string, default: "90s")

Idle Connection Timeout. 0 = no timeout.

key_log_file

(string)

SSL/TLS key log file (useful for debugging)

max_conns_per_host

(int64, minimum: 0, default: 0)

Max Connections Per Host. 0 = no limit.

max_idle_connections

(int64, minimum: 0, default: 100)

Max Idle Connections. 0 = no limit.

max_idle_connections_per_host

(int64, minimum: 0, default: 5)

Max Idle Connections per host. 0 = no limit.

max_response_header_bytes

(int64, minimum: 0, default: 0)

Max Response Header Bytes. 0 = no limit.

network_keep_alive

(string, default: "30s")

Network level keep-alive duration

network_timeout

(string, default: "30s")

Timeout for making network connection

read_buffer_size

(int64, minimum: 0, default: 0)

Read Buffer Size. 0 = 4 KB

response_header_timeout

(string, default: "0s")

Response Header Timeout. 0 = no timeout.

tls_handshake_timeout

(string, default: "10s")

TLS Handshake Timeout. 0 = no timeout

timeout

(string, default: "60s")

HTTP client timeout - Timeouts include connection time, redirects, reading the response and so on. 0 = no timeout.

use_proxy

(bool, default: false)

Use Proxy

write_buffer_size

(int64, minimum: 0, default: 0)

Write Buffer Size. 0 = 4 KB.

proxy_connect_header

(Header)

Proxy Connect Header - map[string][]string

tls

(ClientTLSConfig)

Client TLS configuration

---

HTTPServerConfig

HTTPServerConfig holds configuration for HTTP Server.

disable_http_keep_alives

(bool, default: false)

Disable HTTP Keepalive

idle_timeout

(string, default: "30s")

Idle timeout

latency_buckets_ms

([]float64, default: [10,25,100,250,1000])

Buckets specification in latency histogram

max_header_bytes

(int64, minimum: 0, default: 1048576)

Max header size in bytes

read_header_timeout

(string, default: "10s")

Read header timeout

read_timeout

(string, default: "10s")

Read timeout

write_timeout

(string, default: "45s")

Write timeout

---

Header

A Header represents the key-value pairs in an HTTP header.

The keys should be in canonical form, as returned by CanonicalHeaderKey.

Header

---

HeapConfig

HeapConfig holds configuration for heap Watchdog.

limit

(uint64, minimum: 0)

Maximum memory (in bytes) sets limit of process usage. Default = 256MB.

min_gogc

(int64, minimum: 0, maximum: 100, default: 25)

Minimum GoGC sets the minimum garbage collection target percentage for heap driven Watchdogs. This setting helps avoid over scheduling.

adaptive_policy

(AdaptivePolicy)

watermarks_policy

(WatermarksPolicy)

---

JobConfig

JobConfig is configuration for a periodic job

execution_period

(string, default: "10s")

Time between job executions. Zero or negative value means that the job will never run periodically.

execution_timeout

(string, default: "5s")

Execution timeout

initially_healthy

(bool, default: false)

Sets whether the job is initially healthy

---

JobGroupConfig

JobGroupConfig holds configuration for JobGroup.

blocking_execution

(bool, default: false)

When true, the scheduler will run jobs synchronously, waiting for each execution instance of the job to return before starting the next execution. Running with this option effectively serializes all job execution.

worker_limit

(int64, default: 0)

Limits how many jobs can be running at the same time. This is useful when running resource intensive jobs and a precise start time is not critical. 0 = no limit. If BlockingExecution is set, then WorkerLimit is ignored.

---

KubernetesDiscoveryConfig

KubernetesDiscoveryConfig for Kubernetes service discovery.

enabled

(bool, default: true)

---

ListenerConfig

ListenerConfig holds configuration for socket listeners.

addr

(string, format: hostname_port, default: ":8080")

Address to bind to in the form of [host%zone]:port

keep_alive

(string, default: "180s")

Keep-alive period - 0 = enabled if supported by protocol or operating system. If negative, then keep-alive is disabled.

network

(string, format: empty | empty, one of: tcp | tcp4 | tcp6, default: "tcp")

TCP networks - tcp, tcp4 (IPv4-only), tcp6 (IPv6-only)

---

LogConfig

LogConfig holds configuration for a logger and log writers.

level

(string, format: empty | empty, one of: debug | DEBUG | info | INFO | warn | WARN | error | ERROR | fatal | FATAL | panic | PANIC | trace | TRACE | disabled | DISABLED, default: "info")

Log level

non_blocking

(bool, default: true)

Use non-blocking log writer (can lose logs at high throughput)

pretty_console

(bool, default: false)

Additional log writer: pretty console (stdout) logging (not recommended for prod environments)

writers

([]LogWriterConfig)

Log writers

---

LogWriterConfig

LogWriterConfig holds configuration for a log writer.

compress

(bool, default: false)

Compress

file

(string, default: "stderr")

Output file for logs. Keywords allowed - [stderr, default]. default maps to /var/log/fluxninja/<service>.log

max_age

(int64, minimum: 0, default: 7)

Max age in days for log files

max_backups

(int64, minimum: 0, default: 3)

Max log file backups

max_size

(int64, minimum: 0, default: 50)

Log file max size in MB

---

MetricsConfig

MetricsConfig holds configuration for service metrics.

enable_go_metrics

(bool, default: false)

EnableGoCollector controls whether the go collector is registered on startup. See https://godoc.org/github.com/prometheus/client_golang/prometheus#NewGoCollector

enable_process_collector

(bool, default: false)

EnableProcessCollector controls whether the process collector is registered on startup. See https://godoc.org/github.com/prometheus/client_golang/prometheus#NewProcessCollector

pedantic

(bool, default: false)

Pedantic controls whether a pedantic registry is used. See https://godoc.org/github.com/prometheus/client_golang/prometheus#NewPedanticRegistry

---

ObjectStorageBackoffConfig

ObjectStorageBackoffConfig for object storage backoff configuration.

initial

(string, default: "0.5s")

maximum

(string, default: "2s")

multiplier

(float64, default: 1.5)

---

ObjectStorageConfig

ObjectStorageConfig configures object storage structure.

backend

(string, one of: gcs, default: "gcs")

Backend which provides the object storage.

bucket

(string)

Bucket name of the bucket to use. Required if enabled is true.

enabled

(bool, default: false)

Enabled denotes if object storage is enabled.

key_prefix

(string)

KeyPrefix to use when writing to bucket. Required if enabled is true.

operations_channel_size

(int64, default: 1000)

OperationsChannelSize controls size of the channel used for asynchronous puts and deletes.

retry_policy

(ObjectStorageRetryPolicy)

RetryPolicy to configure retries and timeouts for object storage requests.

---

ObjectStorageRetryPolicy

ObjectStorageRetryPolicy for object storage retry configuration.

timeout

(string, default: "10s")

backoff

(ObjectStorageBackoffConfig)

---

PeerDiscoveryConfig

PeerDiscoveryConfig holds configuration for Agent Peer Discovery.

advertisement_addr

(string, format: empty | hostname_port)

Network address of aperture server to advertise to peers - this address should be reachable from other agents. Used for NAT traversal when provided.

---

PortsConfig

PortsConfig defines configuration for OTel debug and extension ports.

debug_port

(uint32, minimum: 0)

Port on which OTel collector exposes Prometheus metrics on /metrics path.

health_check_port

(uint32, minimum: 0)

Port on which health check extension in exposed.

pprof_port

(uint32, minimum: 0)

Port on which pprof extension in exposed.

zpages_port

(uint32, minimum: 0)

Port on which zpages extension in exposed.

---

ProfilersConfig

ProfilersConfig holds configuration for profilers.

cpu_profiler

(bool, default: false)

Flag to enable CPU profiling on process start and save it to a file. The Browser (HTTP) interface won't work if this is enabled, as the CPU profile will always be running.

profiles_path

(string, default: "default")

Path to save performance profiles. "default" path is /var/log/aperture/<service>/profiles.

register_http_routes

(bool, default: true)

Register routes. Profile types profile, symbol and cmdline will be registered at /debug/pprof/{profile,symbol,cmdline}.

---

PrometheusConfig

PrometheusConfig holds configuration for Prometheus Server.

address

(string, format: empty | hostname_port | url | fqdn | empty)

Address of the Prometheus server

labels

([]PrometheusLabel)

A list of labels to be attached to every query

---

PrometheusLabel

PrometheusLabel holds Name->Value mapping for the label that will be attached to every PromQL query executed by the controller.

name

(string)

value

(string)

---

ProxyConfig

ProxyConfig holds proxy configuration.

This configuration has preference over environment variables HTTP_PROXY, HTTPS_PROXY or NO_PROXY. See https://pkg.go.dev/golang.org/x/net/http/httpproxy#Config

http

(string, format: empty | url | hostname_port)

https

(string, format: empty | url | hostname_port)

no_proxy

([]string)

---

SentryConfig

SentryConfig holds configuration for Sentry.

attach_stack_trace

(bool, default: true)

Configure to generate and attach stack traces to capturing message calls

debug

(bool, default: true)

Debug enables printing of Sentry SDK debug messages

disabled

(bool, default: false)

Sentry crash report disabled

dsn

(string, default: "https://6223f112b0ac4344aa67e94d1631eb85@o574197.ingest.sentry.io/6605877")

If DSN is not set, the client is effectively disabled You can set test project's DSN to send log events. oss-aperture project DSN is set as default.

environment

(string, default: "production")

Environment

sample_rate

(float64, minimum: 0, maximum: 1, default: 1)

Sample rate for event submission

traces_sample_rate

(float64, minimum: 0, maximum: 1, default: 0.2)

Sample rate for sampling traces

---

ServerTLSConfig

ServerTLSConfig holds configuration for setting up server TLS support.

allowed_cn

(string, format: empty | fqdn)

Allowed CN

cert_file

(string)

Server Cert file path

client_ca_file

(string)

Client CA file path

enabled

(bool, default: false)

Enabled TLS

key_file

(string)

Server Key file path

---

WatchdogConfig

WatchdogConfig holds configuration for Watchdog Policy. For each policy, either watermark or adaptive should be configured.

cgroup

(WatchdogPolicyType)

heap

(HeapConfig)

job

(JobConfig)

system

(WatchdogPolicyType)

---

WatchdogPolicyType

WatchdogPolicyType holds configuration Watchdog Policy algorithms. If both algorithms are configured then only watermark algorithm is used.

adaptive_policy

(AdaptivePolicy)

watermarks_policy

(WatermarksPolicy)

---

WatermarksPolicy

WatermarksPolicy creates a Watchdog policy that schedules GC at concrete watermarks.

enabled

(bool, default: false)

Flag to enable the policy

watermarks

([]float64, default: [0.5,0.75,0.8,0.85,0.9,0.95,0.99])

Watermarks are increasing limits on which to trigger GC. Watchdog disarms when the last watermark is surpassed. It's recommended to set an extreme watermark for the last element (for example, 0.99).

---