# Aerospike

> Monitor Aerospike node and namespace metrics with OpenTelemetry and Last9

Source: https://last9.io/docs/integrations/aerospike/

Use OpenTelemetry to monitor Aerospike infrastructure and send telemetry data to Last9. This integration collects node-level and namespace-level metrics from your Aerospike cluster using the OpenTelemetry Collector's Aerospike receiver.

## Prerequisites

Before setting up Aerospike monitoring, ensure you have:

- Aerospike server installed and running
- Administrative access to your Aerospike server
- OpenTelemetry Collector installation access
- Last9 account with integration credentials

1.  **Install OpenTelemetry Collector**

    Choose the appropriate package for your operating system.

**DEB Package**

    For Debian/Ubuntu systems:

    ```bash
    wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.118.0/otelcol-contrib_0.118.0_linux_amd64.deb
    sudo dpkg -i otelcol-contrib_0.118.0_linux_amd64.deb
    ```

**RPM Package**

    For Red Hat/CentOS systems:

    ```bash
    wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.118.0/otelcol-contrib_0.118.0_linux_amd64.rpm
    sudo rpm -ivh otelcol-contrib_0.118.0_linux_amd64.rpm
    ```

    More installation options can be found in the [official OpenTelemetry documentation](https://opentelemetry.io/docs/collector/installation/#linux).

2.  **Configure OpenTelemetry Collector**

    Create the collector configuration file:

    ```bash
    sudo nano /etc/otelcol-contrib/config.yaml
    ```

    Add the following configuration to monitor Aerospike metrics and system resources:

    ```yaml
    receivers:
      aerospike:
        endpoint: "localhost:3000"
        collection_interval: 60s
      hostmetrics:
        collection_interval: 60s
        scrapers:
          cpu:
            metrics:
              system.cpu.logical.count:
                enabled: true
          memory:
            metrics:
              system.memory.utilization:
                enabled: true
              system.memory.limit:
                enabled: true
          load:
          disk:
          filesystem:
            metrics:
              system.filesystem.utilization:
                enabled: true
          network:
          paging:

    processors:
      batch:
        timeout: 20s
        send_batch_size: 10000
        send_batch_max_size: 10000
      resourcedetection/cloud:
        detectors: ["aws", "gcp", "azure"]
      resourcedetection/system:
        detectors: ["system"]
        system:
          hostname_sources: ["os"]

    exporters:
      otlp/last9:
        endpoint: "{{ .Logs.WriteURL }}"
        headers:
          "Authorization": "{{ .Logs.AuthValue }}"
      debug:
        verbosity: detailed

    service:
      pipelines:
        metrics:
          receivers: [aerospike, hostmetrics]
          processors: [batch, resourcedetection/system, resourcedetection/cloud]
          exporters: [otlp/last9]
    ```

    Replace the placeholder values in the `exporters` section with your actual Last9 credentials from the Last9 Integrations page.

    Update the Aerospike endpoint if your server runs on a different host or port (default: `localhost:3000`).

3.  **Configure OpenTelemetry Collector Service**

    Create a systemd service file for the collector:

    ```bash
    sudo nano /etc/systemd/system/otelcol-contrib.service
    ```

    Add the following service configuration:

    ```bash
    [Unit]
    Description=OpenTelemetry Collector Contrib
    After=network.target

    [Service]
    ExecStart=/usr/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml
    Restart=always
    User=root
    Group=root

    [Install]
    WantedBy=multi-user.target
    ```

4.  **Start and Enable the Service**

    Reload systemd configuration and start the collector service:

    ```bash
    sudo systemctl daemon-reload
    sudo systemctl enable otelcol-contrib
    sudo systemctl start otelcol-contrib
    ```

## Understanding the Setup

### Node Metrics

The Aerospike receiver collects node-level metrics reflecting the health of each server in your cluster:

- **Connections**: Current open connections and cumulative connection counts, broken down by type (client, fabric, heartbeat)
- **Memory**: Percentage of node memory still free
- **Query Tracking**: Number of long-running queries tracked by the system (those that exceeded the untracked-time threshold)

### Namespace Metrics

Namespace metrics provide per-namespace insight into storage and workload:

- **Storage**: Minimum contiguous disk free percentage across all devices, and memory usage broken down by component (data, index, set index, secondary index)
- **Transactions**: Read, write, delete, and UDF operations with result breakdowns (success, error, timeout, filtered out, not found)
- **Scans and Queries**: Aggregation, basic, and background scan and query counts with result breakdowns

### Host Metrics

The `hostmetrics` receiver gathers system-level metrics to provide context for Aerospike performance:

- CPU utilization and load averages
- Memory usage and availability
- Disk I/O and filesystem utilization
- Network traffic statistics

## Key Metrics to Monitor

### Node-Level

| Metric                            | Description                        | Unit        |
| --------------------------------- | ---------------------------------- | ----------- |
| `aerospike.node.connection.open`  | Current open connections (by type) | connections |
| `aerospike.node.connection.count` | Connections opened and closed      | connections |
| `aerospike.node.memory.free`      | Percentage of node memory free     | %           |
| `aerospike.node.query.tracked`    | Long-running queries tracked       | queries     |

### Namespace-Level

| Metric                                  | Description                                                        | Unit         |
| --------------------------------------- | ------------------------------------------------------------------ | ------------ |
| `aerospike.namespace.disk.available`    | Minimum contiguous disk free across all devices                    | %            |
| `aerospike.namespace.memory.free`       | Percentage of namespace memory free                                | %            |
| `aerospike.namespace.memory.usage`      | Memory used by component (data, index, set_index, secondary_index) | bytes        |
| `aerospike.namespace.transaction.count` | Transactions by type and result                                    | transactions |
| `aerospike.namespace.scan.count`        | Scan operations by type and result                                 | scans        |
| `aerospike.namespace.query.count`       | Query operations by type and result                                | queries      |

## Configuration Tips

### Authentication

If your Aerospike cluster requires authentication:

```yaml
aerospike:
  endpoint: "localhost:3000"
  username: "your_username"
  password: "your_password"
  collection_interval: 60s
```

### TLS

For TLS-secured connections:

```yaml
aerospike:
  endpoint: "localhost:3000"
  collection_interval: 60s
  tls:
    insecure: false
    ca_file: "/etc/ssl/certs/aerospike-ca.crt"
    cert_file: "/etc/ssl/certs/aerospike-client.crt"
    key_file: "/etc/ssl/certs/aerospike-client.key"
```

### Multi-Node Clusters

The Aerospike receiver connects to a single node endpoint. To monitor multiple nodes, define multiple receivers with distinct names:

```yaml
receivers:
  aerospike/node1:
    endpoint: "node1.example.com:3000"
    collection_interval: 60s
  aerospike/node2:
    endpoint: "node2.example.com:3000"
    collection_interval: 60s

service:
  pipelines:
    metrics:
      receivers: [aerospike/node1, aerospike/node2, hostmetrics]
      processors: [batch, resourcedetection/system, resourcedetection/cloud]
      exporters: [otlp/last9]
```

## Verification and Monitoring

1.  **Check Service Status**

    Verify the OpenTelemetry Collector service is running:

    ```bash
    sudo systemctl status otelcol-contrib
    ```

2.  **Monitor Service Logs**

    Check for any configuration errors or connection issues:

    ```bash
    sudo journalctl -u otelcol-contrib -f
    ```

3.  **Verify Aerospike Connectivity**

    Test that Aerospike is accessible on the expected port:

    ```bash
    # Check node info
    asinfo -v "node"

    # List namespaces
    asinfo -v "namespaces"
    ```

4.  **Verify Data in Last9**

    Log into your Last9 account and check that Aerospike metrics are being received in [Grafana](https://app.last9.io/grafana).

## Troubleshooting

### Service Fails to Start

```bash
# Check service status
sudo systemctl status otelcol-contrib

# View detailed logs
sudo journalctl -u otelcol-contrib --no-pager

# Validate configuration syntax
sudo /usr/bin/otelcol-contrib --config /etc/otelcol-contrib/config.yaml --dry-run
```

### Aerospike Connection Issues

```bash
# Test port accessibility
nc -zv localhost 3000

# Check Aerospike service status
sudo systemctl status aerospike

# View Aerospike logs
sudo tail -f /var/log/aerospike/aerospike.log
```

### No Metrics Appearing

- Confirm the Aerospike endpoint is reachable from the collector host
- Verify port 3000 is not blocked by a firewall
- For authenticated clusters, confirm the credentials have read access to node and namespace statistics
- The Aerospike receiver requires `otelcol-contrib` — the core distribution does not include it

## Need Help?

If you encounter any issues or have questions:

- Join our [Discord community](https://discord.com/channels/652153247672729619/652153247672729621) for real-time support
- Contact our support team at [support@last9.io](mailto:support@last9.io)