# 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](https://airtable.com/appAO1eVyJkYgD8b5/pag4B099sYFbfzuty/form). ::: 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](https://aerospike.com/docs/develop/learn/dynamic-client-config): apply instant configuration changes without modifying any code. - [Enhanced client metrics](https://aerospike.com/docs/develop/learn/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+](https://aerospike.com/docs/develop/client/java/install/) - [Python: v17.1.0+](https://aerospike.com/docs/develop/client/python/install/) - [C: v7.1.0+](https://aerospike.com/docs/develop/client/c/install/) - [C#: v8.1.0+](https://aerospike.com/docs/develop/client/csharp/install/) - [Node.js: v6.3.0+](https://aerospike.com/docs/develop/client/node/install/) - 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. ```yaml static: client: cluster_name: dynamic: metrics: labels: 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: ```plaintext 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](https://aerospike.com/docs/develop/client/java/logging/) - [Go](https://aerospike.com/docs/develop/client/go/logging/) - [C](https://aerospike.com/docs/develop/client/c/logging/) - [C#](https://aerospike.com/docs/develop/client/csharp/logging/) 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: Terminal window ```bash tail -f /var/log/.log | grep -i "config\|YAML" ``` You may need to adjust the path to your application’s log file. Expected output upon success: ```text 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: ```text YAML Configuration file could not be read from: . Unable to parse YAML file: . YAML configuration file could not be found at . ``` ::: 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](https://aerospike.com/docs/develop/learn/dynamic-client-config/yaml) 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: ```yaml static: client: cluster_name: dynamic: metrics: enable: true labels: 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 ```text 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 ```text 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)](https://aerospike.com/docs/database/tools/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: ```yaml static: client: cluster_name: dynamic: metrics: enable: true labels: 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: Terminal window ```bash tail -f /var/log/.log | grep -i "config\|modified" ``` Expected output: ```text # 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](https://airtable.com/appAO1eVyJkYgD8b5/pag4B099sYFbfzuty/form)! 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.