Skip to content

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:

This Quickstart describes how to manage client configurations and monitor application-specific metrics without having to get your developers involved.

Prerequisites

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.

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

  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.

    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:

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

ProblemSolution
”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 applyingVerify client library version supports dynamic configuration.
No metrics appearingCheck if app exposes /metrics endpoint.
Increased timeoutsNormal - 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.

Feedback

Was this page helpful?

What type of feedback are you giving?

What would you like us to know?

+Capture screenshot

Can we reach out to you?