docs: add env var examples for performance tuning

[linconvidal]

Hi team!

This PR adds examples of environment variables in the .env files to assist those looking to fine-tune performance. These variables were previously suggested as a mitigation for issues caused by the accumulation of long queries.

I’m also proposing the creation of a new Wiki page to document these and other potential performance optimization options. I’ve included what I could gather from previous discussions, but feel free to expand, adjust, or refine it as needed.

---

• New Wiki page: 7. Advanced-Configuration-and-Performance ↓

---

Advanced Configuration and Performance

This guide provides details on how to tune cardano-rosetta-java for various workloads and resource constraints. It covers:

1. Pruning (Disk Usage Optimization)
2. Database Pool Settings (HikariCP)
3. Tomcat Thread Configuration
4. Example .env Settings

---

1. Pruning (Disk Usage Optimization)

Pruning removes spent (consumed) UTXOs from local storage, keeping only unspent UTXOs. This can reduce on-disk storage from ~1TB down to ~400GB, but discards historical transaction data.

• Only unspent outputs are preserved.
• You can still validate the chain’s current state (and spend tokens), since active UTXOs remain.
• Enable Pruning: Set PRUNING_ENABLED=true in your environment (e.g., in .env.dockerfile or .env.docker-compose).
• Disable Pruning (default): Set PRUNING_ENABLED=false.

1.1. When to Enable Pruning

• Low Disk Environments: If you need to minimize disk usage and only require UTXO data for current balances.
• Exploratory / Dev Environments: If historical queries are not critical.

1.2. When to Avoid Pruning

• Full Historical Data Requirements: If you need the complete transaction history—whether for exchange operations, audit trails, or compliance mandates—do not enable pruning. Pruning discards spent UTXOs, which removes older transaction data and prevents certain types of historical lookups or reporting.

---

2. Database Pool Settings (HikariCP)

cardano-rosetta-java uses HikariCP as the JDBC connection pool. Tuning these values can help manage concurrency and performance.

Variable	Purpose	Common Defaults	Possible Tuning
SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE	Max number of DB connections in the pool	10 (example)	20–100
SPRING_DATASOURCE_HIKARI_LEAKDETECTIONTHRESHOLD	Time (ms) before a connection leak warning is logged	30,000	300,000
SPRING_DATASOURCE_HIKARI_CONNECTIONTIMEOUT	Max time (ms) to wait for a free connection before error	30,000	300,000

2.1. Example

If you’re dealing with high API request volume, consider:

SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE=50
SPRING_DATASOURCE_HIKARI_LEAKDETECTIONTHRESHOLD=300000
SPRING_DATASOURCE_HIKARI_CONNECTIONTIMEOUT=300000

• This allows up to 50 connections in the pool.
• The large leak detection threshold (5 minutes) can help in debugging slow queries.

2.2 When to Increase Pool Size

• If your logs show “connection timeout” or “pool is exhausted,” your current pool size may be insufficient.
• Only increase SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE if your database has the resources (CPU, RAM, I/O) to handle additional connections.

---

3. Tomcat Thread Configuration

By default, Spring Boot (Tomcat) handles incoming HTTP requests with a thread pool. If you anticipate very high concurrency, you might adjust:

• SERVER_TOMCAT_THREADS_MAX: Maximum number of threads Tomcat uses to handle requests.
  • Start with the default (200).
  • Increasing this limit can help in high-concurrency scenarios, but if your system’s bottleneck is elsewhere (e.g., database, network, or CPU), you may see limited performance gains.
  • Only increase if profiling shows that Tomcat threads are maxed out and your DB can keep up.
  • Check CPU/memory usage carefully; going too high can lead to contention and slowdowns.

---

4. Example .env Settings

Below is a snippet of how you might configure .env.dockerfile or .env.docker-compose for higher throughput:

# --- Pruning Toggle ---
PRUNING_ENABLED=false
# Keep full history, requires ~1TB of disk space

# --- HikariCP Database Pool ---
SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE=50
SPRING_DATASOURCE_HIKARI_LEAKDETECTIONTHRESHOLD=300000
SPRING_DATASOURCE_HIKARI_CONNECTIONTIMEOUT=300000

# --- Tomcat Thread Pool ---
# SERVER_TOMCAT_THREADS_MAX=200
# Uncomment and set a higher value if needed:
# SERVER_TOMCAT_THREADS_MAX=400

---

Further Reading

• Rosetta API Reference
• Yaci-Store Repository
• Spring Boot Docs (for more advanced server and DB config)

[linconvidal]

Oh, I just realized that I forgot to include my suggestion for adding these environment variables to our existing Wiki page as well.

# Environment Variables

With environment variables, the behavior of the compiled application can be configured. The following table lists the available environment variables and their **default** values. You can see example `.env` files in the root folder of the project:

- `.env.IntegrationTest` - used for integration tests with yaci devkit
- `.env.docker-compose` - standard docker-compose setup (copy and adjust as needed)
- `.env.dockerfile` - example environment settings for building + running in Docker

| Variable                                          | Description                                                                    | Default                                    |
|---------------------------------------------------|--------------------------------------------------------------------------------|--------------------------------------------|
| `LOG`                                             | Log level                                                                      | `INFO`                                     |
| `NETWORK`                                         | Network name                                                                   | `mainnet`                                  |
| `MITHRIL_SYNC`                                    | Sync from Mithril snapshot                                                     | `true`                                     |
| `PROTOCOL_MAGIC`                                  | Cardano protocol magic                                                         | `764824073`                                |
| `DB_IMAGE_NAME`                                   | Postgres Docker image name                                                     | `postgres`                                 |
| `DB_IMAGE_TAG`                                    | Postgres Docker image tag                                                      | `14.11-bullseye`                           |
| `DB_NAME`                                         | Postgres database                                                              | `rosetta-java`                             |
| `DB_USER`                                         | Postgres admin user                                                            | `rosetta_db_admin`                         |
| `DB_SECRET`                                       | Postgres admin secret                                                          | `weakpwd#123_d`                            |
| `DB_HOST`                                         | Postgres host                                                                  | `db`                                       |
| `DB_PORT`                                         | Postgres port                                                                  | `5432`                                     |
| `DB_SCHEMA`                                       | Database schema                                                                | `mainnet`                                  |
| `DB_PATH`                                         | Database path                                                                  | `/data`                                    |
| `CARDANO_NODE_HOST`                               | Cardano node host                                                              | `cardano-node`                             |
| `CARDANO_NODE_PORT`                               | Cardano node port                                                              | `3001`                                     |
| `CARDANO_NODE_VERSION`                            | Cardano node version                                                           | `8.9.2`                                    |
| `CARDANO_NODE_SUBMIT_HOST`                        | Cardano node submit API host                                                   | `cardano-submit-api`                       |
| `NODE_SUBMIT_API_PORT`                            | Cardano node submit API port                                                   | `8090`                                     |
| `CARDANO_NODE_SOCKET_PATH`                        | Cardano node socket path                                                       | `/node`                                    |
| `CARDANO_NODE_SOCKET`                             | Cardano node socket file                                                       | `${CARDANO_NODE_SOCKET_PATH}/node.socket`  |
| `CARDANO_NODE_DB`                                 | Cardano node DB path                                                           | `/node/db`                                 |
| `CARDANO_CONFIG`                                  | Cardano node config path                                                       | `/config/${NETWORK}`                       |
| `API_DOCKER_IMAGE_TAG`                            | Docker tag for API image                                                       | `main`                                     |
| `API_SPRING_PROFILES_ACTIVE`                      | API spring profile                                                             | `staging`                                  |
| `API_PORT`                                        | Rosetta API exposed port                                                       | `8082`                                     |
| `ROSETTA_VERSION`                                 | Rosetta version                                                                | `1.4.13`                                   |
| `TOPOLOGY_FILEPATH`                               | Topology file path                                                             | `./config/${NETWORK}/topology.json`        |
| `GENESIS_SHELLEY_PATH`                            | Shelley genesis file                                                           | `./config/${NETWORK}/shelley-genesis.json` |
| `GENESIS_BYRON_PATH`                              | Byron genesis file                                                             | `./config/${NETWORK}/byron-genesis.json`   |
| `GENESIS_ALONZO_PATH`                             | Alonzo genesis file                                                            | `./config/${NETWORK}/alonzo-genesis.json`  |
| `GENESIS_CONWAY_PATH`                             | Conway genesis file                                                            | `./config/${NETWORK}/conway-genesis.json`  |
| `INDEXER_DOCKER_IMAGE_TAG`                        | Yaci indexer Docker version                                                    | `main`                                     |
| `PRUNING_ENABLED`                                 | If pruning of spent UTXOs should be enabled                                    | `false`                                    |
| `SPRING_DATASOURCE_HIKARI_MAXIMUMPOOLSIZE`        | Maximum number of database connections in the HikariCP pool                    | `12`                                       |
| `SPRING_DATASOURCE_HIKARI_LEAKDETECTIONTHRESHOLD` | Time in ms before HikariCP logs a potential connection leak                    | `60000` (60 seconds)                       |
| `SPRING_DATASOURCE_HIKARI_CONNECTIONTIMEOUT`      | Max time in ms to wait for a free connection before throwing an exception      | `100000` (100 seconds)                     |
| `SERVER_TOMCAT_THREADS_MAX`                       | Max Tomcat worker threads for incoming requests                                | `200`                                      |
| `YACI_SPRING_PROFILES`                            | Yaci indexer spring profile                                                    | `postgres`                                 |
| `DEVKIT_ENABLED`                                  | Devkit enabled                                                                 | `false`                                    |

[Kammerlo]

Thank you very much @linconvidal ! This helps a lot.

[Kammerlo]

Additionally I copied your wiki proposal here: https://github.com/cardano-foundation/cardano-rosetta-java/wiki/7.-Advanced-Configuration-and-Performance
I will give you access, that you can change it by yourself in the main repo :)