docs/_docs/general-tips.adoc

// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements.  See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to You under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License.  You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
= General Configuration Tips

== Configuring Default Cluster Storage

When cluster is created, the default distribution zone is used for storage configuration. While we recommend creating distribution zones for your clusters, you can still use the default zone and configure it to suit your needs.

To get default storage configuration, use the `cluster config show ignite.zone` command. Below is an example of the default configuration in the JSON format.

NOTE: In Ignite 3, you can create and maintain the configuration in either JSON or HOCON format.

[source, json]
----
{
  "ignite" : {
    "zone" : {
      "defaultDataStorage" : "aipersist",
      "defaultDistributionZone" : {
        "dataNodesAutoAdjustScaleDown" : 2147483647,
        "dataNodesAutoAdjustScaleUp" : 0,
        "dataStorage" : {
          "dataRegion" : "default",
          "name" : "aipersist"
        },
        "filter" : "$..*",
        "partitions" : 25,
        "replicas" : 1,
        "zoneId" : 0
      },
      "distributionZones" : [ ],
      "globalIdCounter" : 0
    }
  }
}
----

To change type of storage used for new distribution zones, change the `zone.defaultDataStorage` value to `aimem` or `rocksDb`. You can also change the default data region used for new distribution zones by setting the `zone.defaultDistrubutionZone.dataStorage.dataRegion` parameter. You will need to restart the cluster after changing the data region parameters.

You can also change these properties for link:sql-reference/distribution-zones[distribution zones] you have created for yourself.

You can get information about the data region by using the `cluster config show ignite.aipersist` CLI command. Here is how the default data region may look like:

[source, json]
----
{
  "ignite" : {
    "checkpoint" : {
      "checkpointDelayMillis" : 200,
      "checkpointThreads" : 4,
      "compactionThreads" : 4,
      "frequency" : 180000,
      "frequencyDeviation" : 40,
      "logReadLockThresholdTimeoutMillis" : 0,
      "readLockTimeoutMillis" : 10000,
      "useAsyncFileIoFactory" : true
    },
    "defaultRegion" : {
      "memoryAllocator" : {
        "type" : "unsafe"
      },
      "replacementMode" : "CLOCK",
      "size" : 268435456
    },
    "pageSizeBytes" : 16384,
    "regions" : [ ]
  }
}
----

To change the size of the default region, use the `cluster config update` command:

[source,shell]
----
cluster config update --url http://localhost:10300 ignite.aipersist.defaultRegion.size:9999999
----

== Configuring Local Paths

By default, all files generated by Ignite are stored in the installation folder. However, depending on your environment, you may need to change the path to your files. You can use the `{IGNITE_HOME}\etc\vars.env` file to change the storage paths of your files. You can change paths to the following:

- Work directory, where data is stored.
- Log folder, where logs are placed.
- The folder from which libraries are loaded.
- The configuration file that is used to set up the default node.

Additionally, in the node configuration you can set:

- The location CMG information is stored to by setting the `ignite.system.cmgPath` property.
- The location metastorage information is stored to by setting the `ignite.system.metastoragePath` property.
- The location data partitions are stored in by setting the `ignite.system.partitionsBasePath` property.
- The location RAFT logs are stored in by setting the `ignite.system.partitionsLogPath` property. These logs are separate from node logs.

== Configuring Heap Usage

Ignite stores data in off-heap memory, reserved individually for each link:administrators-guide/config/storage/persistent[storage engine] as required. However, Java Heap memory is still used to handle intermediary objects generated by workloads. For example:

- Cluster and node metadata. This includes information about what nodes are part of the cluster, internal logs, table link:administrators-guide/data-partitions#version-storage[version chain], what keys are locked for transactions and all other information required for Ignite to operate normally.
- Intermediary query results. This may lead to needing more heap memory when executing queries on especially large data sets.
- link:developers-guide/compute/compute[Compute] operations are likely to use heap memory to store data. Specific requirements for compute jobs vary depending on what job is being performed.

By default, Ignite allocates 16GB to heap storage. Depending on your environment and workload, you may want to change this value. Smaller heap would mean faster garbage collection, and less resources allocated to Ignite. Larger heap allows to handle more objects, but garbage collection may take longer.

To configure allocated heap, you can use the `JVM_MAX_MEM` and `JVM_MIN_MEM` variables stored in the `{IGNITE_HOME}\etc\vars.env` file. These variables are the equivalent of setting the `Xmx` and `Xms` variables in JVM.

== Configuring Server Logging

By default, Ignite 3 uses the `java.util.logging` (JUL) logging framework. It utilizes the `etc/ignite.java.util.logging.properties` configuration and outputs logs to the folder the `LOG_DIR` variable points to (can be configured in the `etc/vars.env` file). By default, logs are stored in the `{IGNITE_HOME}/log` folder. You can provide a custom configuration file using the `java.util.logging.config.file` property.

For more information on configuring JUL logging, see the link:https://docs.oracle.com/en/java/javase/11/core/java-logging-overview.html[Java Logging Overview] in Oracle documentation.

NOTE: You can also configure client logging for the link:developers-guide/clients/java#logging[Java client].