Skip to content
Maintained by AxonOps — production-grade documentation from engineers who operate distributed databases at scale

AxonOps Agent Installation

The AxonOps Agent enables collection of:

  • Metrics
  • Logs
  • Events

The AxonOps Agent also enables the following maintenance operations to be performed on the cluster:

  • Adaptive repairs
  • Backups

See Installing AxonOps agent for Cassandra in Docker if you are running Cassandra under Docker, and the Kubernetes guide if you are setting up Strimzi or K8ssandra clusters.

Version Compatibility

AxonOps Agent is available for the following versions of Apache Cassandra and Apache Kafka:

Cassandra

  • Apache Cassandra 3.0.x
  • Apache Cassandra 3.11.x
  • Apache Cassandra 4.0.x
  • Apache Cassandra 4.1.x
  • Apache Cassandra 5.0.x

Kafka

  • Apache Kafka 2.x
  • Apache Kafka 3.x

Set up the package repository

Select the OS Family

Execute the following commands to setup the AxonOps repository:

sudo apt-get update
sudo apt-get install -y curl gnupg ca-certificates

curl -L https://packages.axonops.com/apt/repo-signing-key.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/axonops.gpg

echo "deb [arch=arm64,amd64 signed-by=/usr/share/keyrings/axonops.gpg]\
  https://packages.axonops.com/apt axonops-apt main" \
  | sudo tee /etc/apt/sources.list.d/axonops-apt.list
sudo apt-get update

Select Service to Configure

Install Cassandra Agent

Select the Cassandra Version

Select the Java Version

Install the AxonOps Cassandra Agent and its dependency AxonOps agent:

sudo apt-get install axon-cassandra3.0-agent

Configuration File Locations

AxonOps Cassandra Agent

The AxonOps Cassandra Agent is the jar that is directly loaded by Cassandra. The AxonOps Cassandra Agent then reaches out directly to the AxonOps Agent binary which contacts the AxonOps Server directly.

  • Configuration File: /etc/axonops/axon-agent.yml
  • Binary: /usr/share/axonops/axon-cassandra{version}-agent.jar
  • Version number: /usr/share/axonops/axon-cassandra{version}-agent.version
  • Copyright: /usr/share/doc/axonops/axon-cassandra{version}-agent/copyright
  • Licenses: /usr/share/axonops/licenses/axon-cassandra{version}-agent/

AxonOps Agent

The AxonOps Agent is a dependency of the AxonOps Cassandra Agent. This binary contacts the AxonOps Server directly while minimizing the memory footprint and CPU utilization of the Cassandra process.

  • Configuration File: /etc/axonops/axon-agent.yml
  • Binary: usr/share/axonops/AxonOps agent
  • Logs: /var/log/axonops/AxonOps agent.log
  • Systemd service: /usr/lib/systemd/system/AxonOps agent.service

Agent Configuration

Update the following lines within /etc/axonops/axon-agent.yml.

The highlighted lines should match the host and org keys found within /etc/axonops/axon-server.yml.

axon-server:
    hosts: "axon-server_endpoint" # Your axon-server IP or hostname, e.g. axonops.mycompany.com
    port: 1888 # The default axon-server port is 1888

AxonOps agent:
    org: "my-company" # Your organisation name
    # SSL/TLS Settings from AxonOps Agent to AxonOps Server
    tls:
        mode: "disabled" # disabled, TLS
        # Only set below if mode is TLS
        skipVerify: false # Disables CA and Hostname verification
        caFile: "path_to_certs_on_axon_agent_node.crt" # required if skipVerify is not set and you are using a self-signed cert
        certFile: "path_to_certs_on_axon_agent_node.crt"
        keyFile: "path_to_key_file_on_axon_agent_node.key"

NTP:
    host: "ntp.mycompany.com" # Your NTP server IP address or hostname 

Ensure Proper Agent Configuration Permissions

After editing the file, ensure the file permissions for /etc/axonops/axon-agent.yml are set correctly by running the following commmand:

sudo chmod 0640 /etc/axonops/axon-agent.yml

Configure Cassandra

Add the following line at the end of /etc/cassandra/cassandra-env.sh:

JVM_OPTS="$JVM_OPTS -javaagent:/usr/share/axonops/axon-cassandra3.0-agent.jar=/etc/axonops/axon-agent.yml"

If Cassandra was installed using a tarball, the correct path for the cassandra-env.sh will be <Cassandra Installation Directory>/conf/cassandra-env.sh.

NB. Make sure this configuration is not overridden by automation tools.

Configure Cassandra user group

Configure the Linux user groups by:

  • Adding the axonops user to the cassandra user group.
  • Adding the cassandra user to the axonops user group.
CASSANDRA_GROUP=cassandra
CASSANDRA_USER=cassandra

sudo usermod -aG "$CASSANDRA_GROUP" axonops
sudo usermod -aG axonops "$CASSANDRA_USER"

If Cassandra was setup to use a non-default user or group, CASSANDRA_GROUP and/or CASSANDRA_USER will need be updated accordingly for the above commands to work properly.

Uninstall needrestart Package

Due to recent change with needrestart, as seen in Ubuntu 24.04, uninstalling the needrestart package is currently recommended.

Failure to uninstall the needrestart package may cause the Cassandra service to be restarted when updating the AxonOps agent package.

Apply Changes to Cassandra

To load the AxonOps Java Agent and Cassandra config changes, run the following command:

sudo systemctl restart cassandra

Start the AxonOps Agent

sudo systemctl start axon-agent