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 this configuration to the override.properties file:

1
tracker.enable.embedded.database = false

This property is set to true by default because MR uses the embedded tracker instead of the database. When set to true, activity is recorded in MR's Tracker feature and is not logged in the database. Setting it to false enables logging and populates the tracker database.

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.

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

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.