Skip to content

Configuring Tracker for Martini

Martini enables efficient data tracking and logging by allowing you to integrate your own tracker database. By default, it uses Nitrite database, a lightweight embedded NoSQL database, making it ideal for development, testing, and small datasets.

For more scalable and distributed logging, you can configure Martini to use Cassandra or DynamoDB ensuring reliable activity tracking and seamless data retrieval across larger systems.

This guide walks you through the setup process, from configuring the database connection to verifying that Martini properly logs and tracks activity in your chosen database.

Default tracker configuration

By default, the tracker database is configured to use Nitrite, an embedded NoSQL database. Nitrite is lightweight and does not require an external database service, making it ideal for development, testing environments, and small datasets.

Since Nitrite is an embedded database, it stores data locally within the application. This means that all tracker data is saved in a file on disk rather than in a separate database server. While this is convenient for development, it may not be suitable for production environments that require scalability and persistence across multiple instances.

Setup database

Cassandra using Docker

Docker run

  • Pull the Cassandra image (you can also choose a specific version)

    1
    docker pull cassandra:latest

  • Run the following command:

    1
    docker run --name <container_name> -p 9042:9042 -d cassandra:<version>

    Replace <container_name> with a name of your choice then replace <version> with the version of the Cassandra image you pulled.

  • Check if the container is running

Docker compose

  • Ensure that the Docker engine is running. If you're using Docker Desktop, verify that it is active before proceeding.

  • Create a docker-compose.yml file then paste the following:

    1
2
3
4
5
6
7
8
    services:
    cassandra:
        image: cassandra:latest
        container_name: cassandra
        volumes:
            - "<path/to/folder/to/save/cassandra/data>:/var/lib/cassandra"
        ports:
            - "9042:9042"

    Replace <path/to/folder/to/save/cassandra/data> to the actual path of the folder where you want your Cassandra data to be stored.

  • If you need to secure your Cassandra instance with a username and password, you can define these credentials using environment variables in your Docker Compose file:

    1
2
3
            environment:
            - CASSANDRA_USER=cassandra
            - CASSANDRA_PASSWORD=cassandra

  • Open a terminal in the directory containing the docker-compose.yml file, then run the following command:

    1
    docker compose up -d

  • To stop the container, run the following command:

    1
    docker compose down

DynamoDB

  • Sign up for AWS or Login if you already have an account

  • Get an AWS access key

  • Configure your credentials

Follow this guide for a more detailed walkthrough on setting up DynamoDB web service.

Configure the tracker.dbxml file

In the Martini workspace directory, navigate to conf > db-pool > tracker.dbxml.

You can either modify the default configuration or replace it entirely to use the DynamoDB connection.

Cassandra connection for tracker

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
<database>
<name>tracker</name>
<autoStart>true</autoStart>
<type>cassandra</type>
<contactPoints>
    <contactPoint0>127.0.0.1</contactPoint0>
</contactPoints>
<port>9042</port>
<maxSchemaAgreementWaitSeconds>10</maxSchemaAgreementWaitSeconds>
<credentials/>
<compression>NONE</compression>
<metrics>true</metrics>
<ssl>false</ssl>
<poolingOptions>
    <coreConnectionsPerHostLocal>1</coreConnectionsPerHostLocal>
    <coreConnectionsPerHostRemote>1</coreConnectionsPerHostRemote>
    <maxConnectionsPerHostLocal>1</maxConnectionsPerHostLocal>
    <maxConnectionsPerHostRemote>1</maxConnectionsPerHostRemote>
    <newConnectionThresholdLocal>800</newConnectionThresholdLocal>
    <newConnectionThresholdRemote>200</newConnectionThresholdRemote>
    <maxRequestsPerConnectionLocal>1024</maxRequestsPerConnectionLocal>
    <maxRequestsPerConnectionRemote>256</maxRequestsPerConnectionRemote>
    <idleTimeoutSeconds>120</idleTimeoutSeconds>
    <poolTimeoutMillis>5000</poolTimeoutMillis>
    <maxQueueSize>256</maxQueueSize>
    <heartbeatIntervalSeconds>30</heartbeatIntervalSeconds>
</poolingOptions>
<socketOptions>
    <connectTimeoutMillis>5000</connectTimeoutMillis>
    <readTimeoutMillis>12000</readTimeoutMillis>
    <keepAlive>true</keepAlive>
    <reuseAddress>true</reuseAddress>
    <tcpNoDelay>true</tcpNoDelay>
</socketOptions>
<queryOptions>
    <consistencyLevel>LOCAL_ONE</consistencyLevel>
    <serialConsistencyLevel>SERIAL</serialConsistencyLevel>
    <fetchSize>5000</fetchSize>
    <defaultIdempotence>false</defaultIdempotence>
    <prepareOnAllHosts>true</prepareOnAllHosts>
    <reprepareOnUp>true</reprepareOnUp>
    <refreshSchemaIntervalMillis>1000</refreshSchemaIntervalMillis>
    <maxPendingRefreshSchemaRequests>20</maxPendingRefreshSchemaRequests>
    <refreshNodeListIntervalMillis>1000</refreshNodeListIntervalMillis>
    <maxPendingRefreshNodeListRequests>20</maxPendingRefreshNodeListRequests>
    <refreshNodeIntervalMillis>1000</refreshNodeIntervalMillis>
    <maxPendingRefreshNodeRequests>20</maxPendingRefreshNodeRequests>
</queryOptions>
</database>

The default contact point is configured for the Cassandra connection. Feel free to update this value to match your Cassandra instance's configuration.

DynamoDB connection for tracker

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
<database>
<name>tracker</name>
<autoStart>true</autoStart>
<type>dynamodb</type>
<endpoint>[endpoint]</endpoint>
<authenticationProvider>AUTO</authenticationProvider>
<connectionSettings>
    <maxConcurrency>3</maxConcurrency>
    <maxPendingConnectionAcquires>32</maxPendingConnectionAcquires>
    <connectionTimeToLive>20000</connectionTimeToLive>
    <readTimeout>20000</readTimeout>
    <writeTimeout>20000</writeTimeout>
    <connectionTimeout>20000</connectionTimeout>
    <connectionAcquisitionTimeout>20000</connectionAcquisitionTimeout>
    <connectionMaxIdleTime>20000</connectionMaxIdleTime>
    <useIdleConnectionReaper>true</useIdleConnectionReaper>
</connectionSettings>
</database>

Replace the <endpoint> placeholder with the URL of your DynamoDB service. For local setups (e.g., DynamoDB running in Docker), use the local container endpoint (e.g., http://localhost:8000). For AWS-hosted instances, specify the regional endpoint (e.g., https://dynamodb.us-west-2.amazonaws.com).

By default the authenticationProvider is set to AUTO, if you want to choose another way, check the configurations below:

Static Credential Authentication

1
2
3
4
5
6
<authenticationProvider>STATIC</authenticationProvider>
<staticCredentialAuthentication>
    <accessKeyId>[accessKey]</accessKeyId>
    <secretAccessKey>[secretAccessKey]</secretAccessKey>
    <sessionToken>[sessionToken]</sessionToken>
</staticCredentialAuthentication>

Credential Profile Authentication

1
2
3
4
<authenticationProvider>CREDENTIAL_PROFILE</authenticationProvider>
<credentialProfileAuthentication>
    <profileName>[profileName]</profileName>
</credentialProfileAuthentication>

Alternatively, you can set the authenticationProvider to AUTO to enable credential profile authentication.

Configure the override.properties file

Add these configurations to the override.properties file:

1
2
tracker.database-name = tracker
tracker.enable.embedded.database = false

This property is set to true by default and Martini will then use the embedded Nitrite database when using Tracker functionalities. If set to false, Martini will use your external database of choice for Tracker (Cassanda or DynamoDB).

If you want to use DynamoDB as your Tracker database, add these configurations to the override.properties file:

1
2
3
4
tracker.dynamodb.table-name = table1
tracker.dynamodb.state-table-name = table2
tracker.dynamodb.state-content-table-name = table3
tracker.dynamodb.type-table-name = table4

These properties define the DynamoDB table names that Martini will use during connection. When Martini Runtime starts, it reads these values to determine which tables to interact with in the connected DynamoDB instance.

  • If the specified tables exist, Martini will connect to them and use them for tracker operations.

  • If the specified tables do not exist, Martini will create new ones with these names and apply the required schema for tracker functionality.

Specifying the table names here ensures Martini Runtime consistently uses the correct tables across different environments, regardless of whether the tables are already present or need to be created.

Start Martini Runtime

After configuring tracker.dbxml and modifying override.properties, start Martini Runtime. The tracker should automatically start and connect to the database.

You can verify the database status using API Explorer or the Martini Server Admin UI. Both provide different ways to check connectivity and retrieve database information. API Explorer allows you to make direct API calls, while the Server Admin UI provides a graphical interface for managing database connections.

API Explorer

You can verify the database status and retrieve related information by calling the getDatabase API.

Martini Sever Admin UI

Alternatively, you can check the database status through the Server Admin UI:

  1. Open the Server Admin UI
  2. Navigate to Server Admin > Databases > Connections.
  3. Select the tracker database to view its status and details.

Tip

If the tracker database remains stopped upon startup, test the database connection using API Explorer by calling the testConnection API or through Martini Designer. If the connection is unsuccessful, review your configurations to ensure they are set up correctly.

If you've configured to use tables that already exist in DynamoDB and Martini Runtime fails to start, verify that the existing tables follow the correct schema. To obtain a reference schema, allow Martini to create the tables by using new table names, then inspect the table definitions using the describe-table command via the AWS CloudShell or AWS CLI. This ensures your existing tables are compatible with Martini’s expected structure.

Check tracker activity

Cassandra

Martini Designer

  • To check if the tracker database has been populated, click on the Database tab then right-click on the tracker database. Select New, then click on CQL Query.

  • In the Connection and Keyspace dropdown, select tracker.

  • You can choose to query for the document or state and check if there are logs.

Docker CLI

  • Run the following command to enter the Cassandra container and launch CQLSH.

    1
    docker exec -it <cassandra-container-name> cqlsh

    Replace <cassandra-container-name> with the actual name of your Cassandra container.

  • If your Cassandra instance uses authentication, use:

    1
    docker exec -it <cassandra-container-name> cqlsh -u <username> -p <password>

  • After accessing CQLSH, select the keyspace and query the desired table:

    1
2
    USE tracker;
SELECT * FROM <table>;

    Replace <table> with the name of the table you want to inspect.

DynamoDB

  • In the AWS Management Console, navigate to DynamoDB and click on Explore items to view your tables.

  • Select the tracker table, and if the database is populated, you should see a list of items in the table. You may also review the other tables to check a specific category.