Dynamic Client Configuration Quickstart

PREVIEW

This feature is ready for testing but we recommend keeping it in non-production environments. Note that it is subject to change and may not be feature-complete. Aerospike provides no SLAs or technical support commitments for this preview. Feel free to ask questions or surface concerns directly to our product team.

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.

1. 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>

2. 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.yaml

   Enable debugging to help verify the feature is working properly as you work through this guide. See the client documentation for help with enabling debugging.

   • Java
   • Go
   • C
   • C#

3. Restart your application.

4. Check the logs to verify that the dynamic config file was registered. Run the following command at your shell prompt:

   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>.

   Tip

   If you don’t see any logs, check your environment variables to ensure that AEROSPIKE_CLIENT_CONFIG_URL is recognized and that it points to a valid YAML file. See configuration schema for a list of complete configuration options.

Observability and metrics

The following steps enable metrics and verify that they are being collected.

1. Enable client metrics.

   Add metrics collection to your existing configuration file:

   static:
     client:
       cluster_name: <CLUSTER-NAME>
   dynamic:
     metrics:
       enable: true
       labels:
         app_id: <APP-ID>

2. Verify metrics.

   Check the directory for the metrics log file to see that metrics are being captured. The default filename is metrics-yyyyMMddHHmmss.log.

   Note

   The default metrics writer creates a new file after a certain threshold of data is collected.

   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]]]]]]

3. 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.

4. (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.

1. 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.

2. Experiment with modifying configuration dynamically using the YAML config file.

   The following example file modifies the total_timeout and max_retries options:

   static:
     client:
       cluster_name: <CLUSTER-NAME>
   dynamic:
     metrics:
       enable: true
       labels:
         app_id: <APP-ID>
     read:
       total_timeout: 3000
       max_retries: 3

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:

   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.

4. 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.