Axon Framework Client

The Axon Framework client is in charge of instrumenting the components in your Axon applications. This instrumentation allows metrics to be collected and sent to the Axoniq Platform servers. In addition, it registers specific operations that can be triggered from Axoniq Platform, such a pausing and starting event processors. The client is open-source and can be found on GitHub.

Summary

The Axon Framework connector has been designed with privacy concerns in mind. It only collects aggregated metrics and names of components, but never the message payload unless specifically enabled by the user for the dead-letter queue (DLQ).

All data is sent over a secure SSL connection using the RSocket protocol and stored for a maximum of 30 calendar days. A select set of operations are opened by the client, and can only be invoked by users with the appropriate rights assigned in Axoniq Platform.

You can find more information about the data collected on the data collection page, and more about the possible operations on the operations page.

Firewall configuration

The Axon Framework connector needs to establish a connection to the Axoniq Platform servers. This happens over port 7000 to IP address 34.149.46.65. If your organization has a firewall, you need to allow this connection.

Bi-directional communication

RSocket provides bidirectional communication between the client and the server. During the setup phase, a payload is sent to the server to authenticate the client. If this fails, the connection is closed before any data is accepted.

When the connection is established, the client sends metrics to the server periodically. The client can also receive commands from the server, such as stopping a processor, triggered via the Axoniq Platform user interface.

Figure 1. Handshake between client and server

Note that in some cases, for example, when enabling automatic scaling, the server can send commands to the client without user intervention. For more information, see the automatic scaling of segments page.

Installation

The installation of the Axon Framework connector depends on your framework version and setup. Axoniq Platform guides you through the installation process in the Resource Center. You can find the Resource Center in the bottom left of the user interface after logging in. Pick an access token in the guide to fill in the configuration with its credentials.

Figure 2. Resource Center with installation guides

You can access this wizard in various parts of the user interface:

On the Dashboard page, click "Add more applications"
On the Applications page, at the right-hand side of the screen

Step 1: Dependency

You will need to add a dependency to your project. Pick the tab that matches your setup. The Axoniq Framework (AF 5) tabs use the new io.axoniq.platform client. The AF 4 tabs use the legacy io.axoniq.console client.

Spring Boot
Non-Spring Boot
Spring Boot (AF 4)
Non-Spring Boot (AF 4)

Add the Axoniq Framework BOM, the Axoniq Framework Spring Boot starter, and the Axoniq Platform client starter. The starter auto-configures the framework and connects to Axon Server on localhost:8124 by default.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.axoniq.framework</groupId>
            <artifactId>axoniq-framework-bom</artifactId>
            <version>5.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>io.axoniq.framework</groupId>
        <artifactId>axoniq-spring-boot-starter</artifactId>
    </dependency>
    <dependency>
        <groupId>io.axoniq.platform</groupId>
        <artifactId>axoniq-platform-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

For plain Java projects, pull in the Axon Framework event-sourcing and modelling modules, the Axon Server connector, and the Axoniq Platform client. Versions are managed by the BOM.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>io.axoniq.framework</groupId>
            <artifactId>axoniq-framework-bom</artifactId>
            <version>5.0.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

<dependencies>
    <dependency>
        <groupId>org.axonframework</groupId>
        <artifactId>axon-eventsourcing</artifactId>
    </dependency>
    <dependency>
        <groupId>org.axonframework</groupId>
        <artifactId>axon-modelling</artifactId>
    </dependency>
    <dependency>
        <groupId>io.axoniq.framework</groupId>
        <artifactId>axon-server-connector</artifactId>
    </dependency>
    <dependency>
        <groupId>io.axoniq.platform</groupId>
        <artifactId>axoniq-platform-framework-client</artifactId>
    </dependency>
</dependencies>

For applications still on Axon Framework 4, use the legacy console client starter.

<dependency>
    <groupId>io.axoniq.console</groupId>
    <artifactId>console-framework-client-spring-boot-starter</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

For Axon Framework 4 in a non-Spring Boot setup, use the plain console client.

<dependency>
    <groupId>io.axoniq.console</groupId>
    <artifactId>console-framework-client</artifactId>
    <version>LATEST_VERSION</version>
</dependency>

Step 2: Configure

After adding the dependency, configure the connector with the environment ID and access token from Axoniq Platform.

Spring Boot
Non-Spring Boot
Spring Boot (AF 4)
Non-Spring Boot (AF 4)

Set the connection properties in your application.properties (or application.yml):

spring.application.name=my-axoniq-app

axoniq.platform.credentials=ENVIRONMENT_ID:ACCESS_TOKEN

import io.axoniq.platform.framework.AxoniqPlatformConfiguration;
import org.axonframework.config.EventSourcingConfigurer;

AxoniqPlatformConfiguration platformConfig = new AxoniqPlatformConfiguration(
        "ENVIRONMENT_ID",
        "ACCESS_TOKEN",
        "my-application"
);

EventSourcingConfigurer configurer = EventSourcingConfigurer.create()
    .componentRegistry(cr -> cr.registerComponent(
        AxoniqPlatformConfiguration.class,
        c -> platformConfig
    ));

configurer.buildConfiguration().start();

For Axon Framework 4 applications, set the legacy console properties in your application.properties or application.yml:

axoniq.console.application-name=My Application
axoniq.console.credentials=ENVIRONMENT_ID:ACCESS_TOKEN
axoniq.console.dlq-mode=FULL

For Axon Framework 4 applications, configure the legacy console module on your Configurer:

public void configure(Configurer configurer) {
    AxoniqConsoleConfigurerModule
        .builder(
            "ENVIRONMENT_ID",
            "ACCESS_TOKEN",
            "My application"
        )
        .dlqMode(AxoniqConsoleDlqMode.FULL)
        .build()
        .configureModule(configurer);
}

Licensing

The commercial modules of Axoniq Framework need a license. An application that connects to Axoniq Platform with the configuration above receives its license over that connection, and a new one whenever it is renewed. To run without a connection, or to learn which license wins when there are several, see Licensing.

Access tokens

The credentials property combines the ID of the environment to connect to with the secret of an access token. The token needs the Axon Framework connector scope, or All connectors, and must cover that environment.

In the Resource Center, the token picker fills in the credentials for you. It lists the tokens you are allowed to reveal that fit the current environment:

The access token picker in the Axoniq Framework installation guide

If no token is available to you, the guide shows placeholders. Ask a workspace admin to issue a token, or to make one revealable by members.

When a token is revoked or expires, applications using it are disconnected immediately. See Access Tokens for issuing, rotating and revoking tokens.