Dynamic Client Configuration Quickstart
Aerospike’s integrated client control and observability suite helps you accelerate deployments and dramatically reduce incident response time with the following features:
- Dynamic client configuration: apply instant configuration changes without modifying any code.
- Enhanced client metrics: view more granular metrics that give insights into individual client behavior.
This Quickstart describes how to manage client configurations and monitor application-specific metrics without having to get your developers involved.
Prerequisites
- A running instance of Aerospike Database 8.1.0 or later
- An application connected to your database with logging enabled
- Updated Client (minimum versions):
- Java: v9.1.0+
- Python: v17.1.0+
- C: v7.1.0+
- C#: v8.1.0+
- Node.js: v6.3.0+
- Go: not yet available
- Rust: not yet available
- PHP: not yet available
Dynamic Client Configuration
The following steps set up Dynamic Client Configuration in an application.
-
Create a minimal configuration file named
aerospikeconfig.yaml
and store it in a directory such as$HOME/.aerospike/config/
(or another location of your choice). You’ll reference this path when enabling dynamic configuration in the next step. We’ll add to this file in later steps.static:client:cluster_name: <CLUSTER-NAME>dynamic:metrics:labels:app_id: <APP-ID> -
Enable dynamic configuration
Use environment variables in your application to enable Dynamic Client Configuration. The following example shows how to set the environment variable:
AEROSPIKE_CLIENT_CONFIG_URL=file://$HOME/.aerospike/config/aerospikeconfig.yamlEnable debugging to help verify the feature is working properly as you work through this guide. See the client documentation for help with enabling debugging.
-
Restart your application.
-
Check the logs to verify that the dynamic config file was registered. Run the following command at your shell prompt:
Terminal window tail -f /var/log/<APP>.log | grep -i "config\|YAML"You may need to adjust the path to your application’s log file.
Expected output upon success:
2025-05-24 00:54:51 UTC DEBUG Initial read of YAML config file...2025-05-24 00:54:51 UTC DEBUG Config successfully loaded....Expected failure outputs:
YAML Configuration file could not be read from: <CONFIG-PATH>.Unable to parse YAML file: <FILE-NAME>.YAML configuration file could not be found at <FILE-NAME>.
Observability and metrics
The following steps enable metrics and verify that they are being collected.
-
Enable client metrics.
Add metrics collection to your existing configuration file:
static:client:cluster_name: <CLUSTER-NAME>dynamic:metrics:enable: truelabels:app_id: <APP-ID> -
Verify metrics.
Check the directory for the metrics log file to see that metrics are being captured. The default filename is
metrics-yyyyMMddHHmmss.log
.Metrics export format:
Clients append labels as columns in the exported metrics.
Formatted CSV header cluster[name,clientType,clientVersion,app_id,label[],cpu,mem,invalidNodeCount,commandCount,retryCount,delayQueueTimeoutCount,eventloop[],node[]] label[name,value] eventloop[processSize,queueSize] node[name,address,port,syncConn,asyncConn,namespace[]] conn[inUse,inPool,opened,closed] namespace[name,errors,timeouts,keyBusy,bytesIn,bytesOut,latency[]] latency(%u,%u)[type[l1,l2,l3...]]Sample row output cluster[,C,7.0.4,my_app,[[region,us-west],[zone,usw1-az3]],0,5685248,0,12,0,0,[],[[BB9AFA9A8421C00,10.211.55.4,3000,0,1,2,0,0,0,0,0,[test,1,0,0,1111,2222,[conn[0,0,0,0,0,0,0],write[7,0,0,0,0,0,0],read[3,1,0,0,0,0,0],batch[0,0,0,0,0,0,0],query[0,0,0,0,0,0,0]]]]]] -
Generate load and observe.
Generate server traffic with Aerospike Benchmark (asbench) or your preferred load generation tool. As you generate load, observe the metrics logs to see the impact.
-
(Optional) Build an exporter that surfaces metrics in a dashboards, using metrics files as input.
Test dynamic configuration changes
In this section, we will generate traffic and use the YAML configuration file to modify your configuration dynamically.
-
Generate traffic to put strain on your app.
Using your preferred benchmarking tool, generate traffic to your app. The goal is to simulate an environment in which the app is overloaded with requests, causing server errors.
-
Experiment with modifying configuration dynamically using the YAML config file.
The following example file modifies the
total_timeout
andmax_retries
options:static:client:cluster_name: <CLUSTER-NAME>dynamic:metrics:enable: truelabels:app_id: <APP-ID>read:total_timeout: 3000max_retries: 3 -
Verify changes.
Check the log file again to verify the changes that you made. Note that you didn’t need to restart your application for this.
Run the following command at your shell prompt:
Terminal window tail -f /var/log/<app>.log | grep -i "config\|modified"Expected output:
# 2025-05-24 00:54:53 UTC DEBUG YAML config file has been modified. Loading...# 2025-05-24 00:54:53 UTC DEBUG Config successfully loaded. -
Test performance improvement.
Experiment with different configuration options to find the optimal settings for your application. Since these configurations can be changed dynamically, it’s easy to iterate and fine-tune for the best performance, with no code changes necessary.
Common Issues & Solutions
Problem | Solution |
---|---|
”Config file not found” | Check AEROSPIKE_CLIENT_CONFIG_URL path exists. |
”Permission denied” | Verify that your application has write permission on the log directory. |
Changes not applying | Verify client library version supports dynamic configuration. |
No metrics appearing | Check if app exposes /metrics endpoint. |
Increased timeouts | Normal - monitor error rates, not just timeouts. |
Send us your feedback
Have questions or concerns? Let us know! We’d love to hear how we are (or are not) addressing your pain points. You can follow that same link to schedule a call with the product team.