Status

Current state: Under Discussion

Discussion thread: https://lists.apache.org/thread/ckb3tqnjf0h66rd0mlpfblpvkrvp3wq6

JIRA: Unable to render Jira issues macro, execution error.

Released: <Solr Version>

Please keep the discussion on the mailing list rather than commenting on the wiki (wiki discussions get unwieldy fast). Confluence supports inline comments that can also be used.

Motivation

System properties and environment variable names have been ad-hoc in Solr with no fixed syntax or structure. E.g we have both metricsEnabled, enable.packages and  solr.clustering.enabled. Want to set a standard, both for environment variables and system properties.

Public Interfaces

Configuration of Solr will be affected. Anywhere users configure Solr with environment variable or system property will need to change.

Proposed Changes

Some simple syntax rules are introduced

  • Environment variables will follow the SOLR_CATEGORY_FOO_BAR naming (SOLR_ prefix, uppercase, underscores)
  • System properties will follow the solr.category.foo.bar naming (solr. prefix, lowercase, dots, no camelCase)
  • Both system property and environment variable always supported (already enforced by EnvUtils)

Furtuermore, we propose to strucure all vars/props in a hierarchy with at least a top-category and perhaps sub categories. Some examples

  • Instead of enable.packages → solr.packages.enabled  / SOLR_PACKAGES_ENABLED. 
  • Instead of enable.update.log, → solr.index.updatelog.enabled / SOLR_INDEX_UPDATELOG_ENABLED

There is a working wiki document at System property naming structure where we can collaborate on nailing down the new naming for all props, please contribute.

Implementation

We can implement an aliasing feature in EnvUtils so both old and new property will work with only a central configuration, and no need to double System.getProperty calls everywhere.

The renaming will then happen in a series of JIRAs, one per feature (e.g. highlighting or packages)

The new rules should be documented in dev-docs/ to be official.

Consider having a central registry of all properties in use? Probably not needed as we can analyze all java calls to EnvUtils.getProperty()

Compatibility, Deprecation, and Migration Plan

  • All current sys.props will still work throughout 9.x, as an alias, with deprecation warning printed to logs
  • New sys.prop names will be introduced in a series of PRs (one per top-category?, see JIRA)
  • Cut over all sysProp reading to the new EnvUtils class, so that class can handle the old/new aliasing in one place (new property file?)
  • In 10.0 (or even 11.0 if we want longer transition period), remove the aliases

Test Plan

The centralized aliasing logic will have own tests.

Each property that is cut over to new naming should consider adding test of both old and new property.

Rejected Alternatives

  • Status Quo
  • Randomly changing properties without a plan
  • No labels