Configuration Naming Guidelines - derekm/pravega GitHub Wiki

Related Issues: Issue 4712

Table of Contents:

• Configuration Naming Scheme
• Configuration Naming Guidelines

The new naming scheme has a hierarchical structure of the following form:

<Namespace>.<Configuration-Item>.<Measurement/Unit>*.<Qualifier>*

where * represent "optional"/"situation-dependent" parts. 

The table below describes the parts.

1. Structure your namespaces hierarchically from left to right, from a highest-level concept to the lowest-level.

   The first word of the namespace typically represents the high-level component to which the item like controller, pravegaservice (for Segment Store), autoscale (for Auto Scaler), HDFS, and so on. The configuration files where you define these configurations, define the first word implicitly to all configurations defined therein. For example, all configurations starting with pravegaservice are defined in ServiceConfig.java, where you'll find definitions of configurations like dataLog.impl.name (representing pravegaservice.dataLog.impl.name).

   The subsequent terms in the namespace represent areas and sub-areas. Consider controller.transaction.lease.count.max for an example. In this configuration, controller.transaction.lease namespace contains transaction, which represents that the specific configuration part lease applies to the area transactions.

2. When using units, use their plural form. Use seconds and bytes, instead of second or byte.

3. Use camel cases for compound names. For example, readOnly in pravegaservice.readOnly.enable.

4. Name of all boolean-valued configurations must end with .enable. For example:

   • controller.hostMonitor.enable=false
   • #controller.request.tracing.enable=true

5. There is no need for using the term value in the names, as it is implicit in the absence of any unit or qualifier. For example controller.service.rpc.listener.port, which does not contain any unit or qualifier, configures a port value implicitly.

6. Use location as a qualifier for configurations specifying file paths. One example is controller.security.tls.server.certificate.location, which represents the TLS Server certificate file path for Controller. Similarly, one'd use ...trustStore.pwd.location if the password is specified by a file, but ...truststore.pwd is the password is directly specified as a configuration value such as "super-secret-password".

7. Network service's endpoint configuration must have service in the namespace. A few examples:

   • controller.service.rpc.listener.port = 9090
   • controller.service.rest.listener.port = 9091
   • pravegaservice.service.published.host.nameOrIp

8. For configurations representing connection params for connections to other components, use connect in the namespace like in zk.connect.uri. Doing so makes it explicit that these are connection parameters for another component/system.