#
# 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.
#

configs:
- name: bookiePort
  default: '3181'
  description: The port on which the bookie server listens.
- name: allowLoopback
  default: 'false'
  description: |
    Whether the bookie is allowed to use a loopback interface as its primary interface (i.e. the interface used to establish its identity). By default, loopback interfaces are not allowed as the primary interface.

    Using a loopback interface as the primary interface usually indicates a configuration error. For example, it's fairly common in some VPS setups to not configure a hostname or to have the hostname resolve to `127.0.0.1`. If this is the case, then all bookies in the cluster will establish their identities as `127.0.0.1:3181` and only one will be able to join the cluster. For VPSs configured like this, you should explicitly set the listening interface.
- name: listeningInterface
  default: 'eth0'
  description: The network interface on which the bookie listens. If not set, the bookie will listen on all interfaces.
- name: journalDirectory
  default: data/bookkeeper/journal
  description: The directory where Bookkeeper outputs its write-ahead log (WAL)
- name: ledgerDirectories
  default: data/bookkeeper/ledgers
  description: |
    The directory where Bookkeeper outputs ledger snapshots. This could define multiple directories to store snapshots separated by comma, for example `ledgerDirectories=/tmp/bk1-data,/tmp/bk2-data`.

    Ideally, ledger dirs and the journal dir are each in a different device, which reduces the contention between random I/O and sequential write. It is possible to run with a single disk, but performance will be significantly lower.
- name: ledgerManagerType
  default: hierarchical
  description: The type of ledger manager used to manage how ledgers are stored, managed, and garbage collected. See [BookKeeper Internals](http://bookkeeper.apache.org/docs/r4.4.0/bookkeeperInternals.html) for more info.
- name: zkLedgersRootPath
  default: "/ledgers"
  description: The root ZooKeeper path used to store ledger metadata. This parameter is used by the ZooKeeper-based ledger manager as a root znode to store all ledgers.
- name: ledgerStorageClass
  default: org.apache.bookkeeper.bookie.storage.ldb.DbLedgerStorage
  description: Ledger storage implementation class
- name: entryLogFilePreallocationEnabled
  default: 'true'
  description: Enable or disable entry logger preallocation
- name: logSizeLimit
  default: '2147483648'
  description: |
    Max file size of the entry logger, in bytes. A new entry log file will be created when the old one reaches the file size limitation.
- name: minorCompactionThreshold
  default: '0.2'
  description: Threshold of minor compaction. Entry log files whose remaining size percentage reaches below this threshold will be compacted in a minor compaction. If set to less than zero, the minor compaction is disabled.
- name: minorCompactionInterval
  default: '3600'
  description: Time interval to run minor compaction, in seconds. If set to less than zero, the minor compaction is disabled.
- name: majorCompactionThreshold
  default: '0.5'
  description: |
    The threshold of major compaction. Entry log files whose remaining size percentage reaches below this threshold will be compacted in a major compaction. Those entry log files whose remaining size percentage is still higher than the threshold will never be compacted. If set to less than zero, the minor compaction is disabled.
- name: majorCompactionInterval
  default: '86400'
  description: The time interval to run major compaction, in seconds. If set to less than zero, the major compaction is disabled.
- name: compactionMaxOutstandingRequests
  default: '100000'
  description: |
    Sets the maximum number of entries that can be compacted without flushing. When compacting, the entries are written to the entrylog and the new offsets are cached in memory. Once the entrylog is flushed the index is updated with the new offsets. This parameter controls the number of entries added to the entrylog before a flush is forced. A higher value for this parameter means more memory will be used for offsets. Each offset consists of 3 longs. This parameter should _not_ be modified unless you're fully aware of the consequences.
- name: compactionRate
  default: '1000'
  description: The rate at which compaction will read entries, in adds per second.
- name: isThrottleByBytes
  default: 'false'
  description: Throttle compaction by bytes or by entries.
- name: compactionRateByEntries
  default: '1000'
  description: The rate at which compaction will read entries, in adds per second.
- name: compactionRateByBytes
  default: '1000000'
  description: Set the rate at which compaction will readd entries. The unit is bytes added per second.
- name: journalMaxSizeMB
  default: '2048'
  description: Max file size of journal file, in megabytes. A new journal file will be created when the old one reaches the file size limitation.
- name: journalMaxBackups
  default: '5'
  description: The max number of old journal filse to keep. Keeping a number of old journal files would help data recovery in special cases.
- name: journalPreAllocSizeMB
  default: '16'
  description: How space to pre-allocate at a time in the journal.
- name: journalWriteBufferSizeKB
  default: '64'
  description: The of the write buffers used for the journal.
- name: journalRemoveFromPageCache
  default: 'true'
  description: Whether pages should be removed from the page cache after force write.
- name: journalAdaptiveGroupWrites
  default: 'true'
  description: Whether to group journal force writes, which optimizes group commit for higher throughput.
- name: journalMaxGroupWaitMSec
  default: '1'
  description: The maximum latency to impose on a journal write to achieve grouping.
- name: journalAlignmentSize
  default: '4096'
  description: All the journal writes and commits should be aligned to given size
- name: journalBufferedWritesThreshold
  default: '524288'
  description: Maximum writes to buffer to achieve grouping
- name: journalFlushWhenQueueEmpty
  default: 'false'
  description: If we should flush the journal when journal queue is empty
- name: numJournalCallbackThreads
  default: '8'
  description: The number of threads that should handle journal callbacks
- name: rereplicationEntryBatchSize
  default: '5000'
  description: The number of max entries to keep in fragment for re-replication
- name: gcWaitTime
  default: '900000'
  description: |
    How long the interval to trigger next garbage collection, in milliseconds. Since garbage collection is running in background, too frequent gc will heart performance. It is better to give a higher number of gc interval if there is enough disk capacity.
- name: gcOverreplicatedLedgerWaitTime
  default: '86400000'
  description: |
    How long the interval to trigger next garbage collection of overreplicated ledgers, in milliseconds. This should not be run very frequently since we read the metadata for all the ledgers on the bookie from zk.
- name: flushInterval
  default: '60000'
  description: |
    How long the interval to flush ledger index pages to disk, in milliseconds. Flushing index files will introduce much random disk I/O. If separating journal dir and ledger dirs each on different devices, flushing would not affect performance. But if putting journal dir and ledger dirs on same device, performance degrade significantly on too frequent flushing. You can consider increment flush interval to get better performance, but you need to pay more time on bookie server restart after failure.
- name: bookieDeathWatchInterval
  default: '1000'
  description: Interval to watch whether bookie is dead or not, in milliseconds
- name: zkServers
  default: localhost:2181
  description: |
    A list of one of more servers on which zookeeper is running. The server list can be comma separated values, for example: zkServers=zk1:2181,zk2:2181,zk3:2181.
- name: zkTimeout
  default: '30000'
  description: |
    ZooKeeper client session timeout in milliseconds Bookie server will exit if it received SESSION_EXPIRED because it was partitioned off from ZooKeeper for more than the session timeout JVM garbage collection, disk I/O will cause SESSION_EXPIRED. Increment this value could help avoiding this issue
- name: serverTcpNoDelay
  default: 'true'
  description: |
    This settings is used to enabled/disabled Nagle's algorithm, which is a means of improving the efficiency of TCP/IP networks by reducing the number of packets that need to be sent over the network. If you are sending many small messages, such that more than one can fit in a single IP packet, setting server.tcpnodelay to false to enable Nagle algorithm can provide better performance.
- name: openFileLimit
  default: '0'
  description: |
    Max number of ledger index files could be opened in bookie server If number of ledger index files reaches this limitation, bookie server started to swap some ledgers from memory to disk. Too frequent swap will affect performance. You can tune this number to gain performance according your requirements.
- name: pageSize
  default: 8192
  description: |
    Size of a index page in ledger cache, in bytes A larger index page can improve performance writing page to disk, which is efficent when you have small number of ledgers and these ledgers have similar number of entries. If you have large number of ledgers and each ledger has fewer entries, smaller index page would improve memory usage.
- name: pageLimit
  default: '0'
  description: |
    How many index pages provided in ledger cache If number of index pages reaches this limitation, bookie server starts to swap some ledgers from memory to disk. You can increment this value when you found swap became more frequent. But make sure pageLimit*pageSize should not more than JVM max memory limitation, otherwise you would got OutOfMemoryException. In general, incrementing pageLimit, using smaller index page would gain bettern performance in lager number of ledgers with fewer entries case If pageLimit is -1, bookie server will use 1/3 of JVM memory to compute the limitation of number of index pages.
- name: readOnlyModeEnabled
  default: 'true'
  description: |
    If all ledger directories configured are full, then support only read requests for clients. If "readOnlyModeEnabled=true" then on all ledger disks full, bookie will be converted to read-only mode and serve only read requests. Otherwise the bookie will be shutdown. By default this will be disabled.
- name: diskUsageThreshold
  default: '0.95'
  description: |
    For each ledger dir, maximum disk space which can be used. Default is 0.95f. i.e. 95% of disk can be used at most after which nothing will be written to that partition. If all ledger dir partions are full, then bookie will turn to readonly mode if 'readOnlyModeEnabled=true' is set, else it will shutdown. Valid values should be in between 0 and 1 (exclusive).
- name: diskCheckInterval
  default: '10000'
  description: Disk check interval in milli seconds, interval to check the ledger dirs usage.
- name: auditorPeriodicCheckInterval
  default: '604800'
  description: |
    Interval at which the auditor will do a check of all ledgers in the cluster. By default this runs once a week. The interval is set in seconds. To disable the periodic check completely, set this to 0. Note that periodic checking will put extra load on the cluster, so it should not be run more frequently than once a day.
- name: auditorPeriodicBookieCheckInterval
  default: '86400'
  description: |
    The interval between auditor bookie checks. The auditor bookie check, checks ledger metadata to see which bookies should contain entries for each ledger. If a bookie which should contain entries is unavailable, thea the ledger containing that entry is marked for recovery. Setting this to 0 disabled the periodic check. Bookie checks will still run when a bookie fails. The interval is specified in seconds.
- name: numAddWorkerThreads
  default: '0'
  description: number of threads that should handle write requests. if zero, the writes would be handled by netty threads directly.
- name: numReadWorkerThreads
  default: '8'
  description: number of threads that should handle read requests. if zero, the reads would be handled by netty threads directly.
- name: maxPendingReadRequestsPerThread
  default: '2500'
  description: If read workers threads are enabled, limit the number of pending requests, to avoid the executor queue to grow indefinitely.
- name: readBufferSizeBytes
  default: '4096'
  description: The number of bytes we should use as capacity for `BufferedReadChannel`.
- name: writeBufferSizeBytes
  default: '65536'
  description: The number of bytes used as capacity for the write buffer
- name: useHostNameAsBookieID
  default: 'false'
  description: |
    Whether the bookie should use its hostname to register with the coordination service (e.g.: zookeeper service). When `false`, bookie will use its ipaddress for the registration.
- name: statsProviderClass
  default: org.apache.bookkeeper.stats.prometheus.PrometheusMetricsProvider
- name: prometheusStatsHttpPort
  default: 8000
- name: dbStorage_writeCacheMaxSizeMb
  default: '512'
  description: |
    Size of Write Cache. Memory is allocated from JVM direct memory. Write cache is used to buffer entries before flushing into the entry log For good performance, it should be big enough to hold a sub
- name: dbStorage_readAheadCacheMaxSizeMb
  default: '256'
  description: Size of Read cache. Memory is allocated from JVM direct memory. This read cache is pre-filled doing read-ahead whenever a cache miss happens
- name: dbStorage_readAheadCacheBatchSize
  default: '1000'
  description: How many entries to pre-fill in cache after a read cache miss
- name: dbStorage_rocksDB_blockCacheSize
  default: '268435456'
  description: Size of RocksDB block-cache. For best performance, this cache should be big enough to hold a significant portion of the index database which can reach ~2GB in some cases
- name: dbStorage_rocksDB_writeBufferSizeMB
  default: '64'
- name: dbStorage_rocksDB_sstSizeInMB
  default: '64'
- name: dbStorage_rocksDB_blockSize
  default: '65536'
- name: dbStorage_rocksDB_bloomFilterBitsPerKey
  default: '10'
- name: dbStorage_rocksDB_numLevels
  default: '-1'
- name: dbStorage_rocksDB_numFilesInLevel0
  default: '4'
- name: dbStorage_rocksDB_maxSizeInLevel1MB
  default: '256'
