From e3accbcf0ecf31a598eea3b2723041a06f08436c Mon Sep 17 00:00:00 2001 From: Vijay N Date: Wed, 29 Oct 2025 15:12:04 +0530 Subject: [PATCH 1/2] Added documentation for property precedence order, per-tenant configuration and /v1/health/config endpoint. --- userguide/aviate/aviate-health.adoc | 68 +++++++++++++++++++++++++++++ 1 file changed, 68 insertions(+) diff --git a/userguide/aviate/aviate-health.adoc b/userguide/aviate/aviate-health.adoc index ddaef4e28..d411d52a3 100644 --- a/userguide/aviate/aviate-health.adoc +++ b/userguide/aviate/aviate-health.adoc @@ -27,6 +27,74 @@ com.killbill.billing.plugin.aviate.enableHealthReporter=true Refer to the https://docs.killbill.io/latest/userguide_configuration.html[__Kill Bill Configuration Guide__] to know more about setting configuration properties. +=== Runtime Properties + +Properties can be specified to configure the Kill Bill system including its plugins. The following https://docs.killbill.io/latest/userguide_configuration#configuration_properties_table[documentation] shows the main configuration properties. + +The values for these properties can come from multiple sources, each with a defined precedence. + +==== Property Resolution Order (Highest to Lowest) +Kill Bill resolves property values in the following order, where higher precedence sources override lower ones: + +* Immutable System Property + +Includes the `user.timezone` property, which is force set to `GMT`. + +This property cannot be overridden. + +* Environment Variables + +Properties prefixed with `KB_` (for example, `KB_org_killbill_dao_url` maps to `org.killbill.dao.url`). + +These are loaded only when `org.killbill.server.lookupEnvironmentVariables` is set to `true` (this is enabled by default). + +These properties take the highest precedence among other configurable sources. + +* Runtime Configuration + +Properties loaded from a configuration file specified via `-Dorg.killbill.server.properties=`. + +If no file is specified, Kill Bill uses JVM system properties defined via `-Dproperty=value`. + +This source has the second-highest precedence among configurable sources. + +* Kill Bill Defaults + +These are default values defined within the Kill Bill codebase. + +They are registered dynamically by various *Config classes during application startup, covering configuration domains such as CatalogConfig, DaoConfig, LifecycleConfig, SecurityConfig, InvoiceConfig, PaymentConfig, OSGIConfig, and others. + +The following defaults are applied only when a property is not defined in any higher precedence source: + + org.killbill.persistent.bus.external.tableName=bus_ext_events + org.killbill.persistent.bus.external.historyTableName=bus_ext_events_history + org.killbill.server.enableJasypt=false + org.killbill.server.lookupEnvironmentVariables=true + org.slf4j.simpleLogger.log.jdbc=ERROR + + + +When a property is defined in multiple sources, Kill Bill applies the value from the highest precedence source and logs a warning indicating which sources defined it and which value was chosen. + +Example warning: + +`Property conflict detected for 'org.killbill.dao.healthCheckConnectionTimeout': +defined in sources [RuntimeConfiguration, EnvironmentVariables] - +using value from 'EnvironmentVariables': '11s'` + + +To make it easier to understand the runtime values of these properties, Kill Bill provides the `/v1/health/config` endpoint. +This endpoint displays the effective configuration currently in use along with information about which source each property value was derived from. + + +==== Per-Tenant Configuration + +In addition to system-wide properties, Kill Bill supports per-tenant configuration, allowing tenants to override specific system properties for their own environment. + +This provides fine-grained control in multi-tenant deployments, enabling different tenants to customize selected settings while still inheriting defaults from the global configuration. + +For more details, see the official documentation: https://docs.killbill.io/latest/plugin_installation#per-tenant-configuration. + === Using Health APIs As mentioned earlier, Aviate Health exposes endpoints that allow monitoring the health of a KB installation and fixing problems if any. Once the aviate plugin is installed, you can start using the Aviate Health APIs. These are documented in our https://apidocs.killbill.io/aviate-health[api docs]. From 26e6981f86d8c2a9ad37ad297a8a9746ce29cb8a Mon Sep 17 00:00:00 2001 From: Vijay N Date: Sat, 10 Jan 2026 08:06:26 +0530 Subject: [PATCH 2/2] Rebased to the latest v3 branch and made required changes to the Runtime Properties section. --- userguide/aviate/aviate-health.adoc | 135 +++++++++++++--------------- 1 file changed, 60 insertions(+), 75 deletions(-) diff --git a/userguide/aviate/aviate-health.adoc b/userguide/aviate/aviate-health.adoc index d411d52a3..fa8612374 100644 --- a/userguide/aviate/aviate-health.adoc +++ b/userguide/aviate/aviate-health.adoc @@ -27,74 +27,6 @@ com.killbill.billing.plugin.aviate.enableHealthReporter=true Refer to the https://docs.killbill.io/latest/userguide_configuration.html[__Kill Bill Configuration Guide__] to know more about setting configuration properties. -=== Runtime Properties - -Properties can be specified to configure the Kill Bill system including its plugins. The following https://docs.killbill.io/latest/userguide_configuration#configuration_properties_table[documentation] shows the main configuration properties. - -The values for these properties can come from multiple sources, each with a defined precedence. - -==== Property Resolution Order (Highest to Lowest) -Kill Bill resolves property values in the following order, where higher precedence sources override lower ones: - -* Immutable System Property - -Includes the `user.timezone` property, which is force set to `GMT`. - -This property cannot be overridden. - -* Environment Variables - -Properties prefixed with `KB_` (for example, `KB_org_killbill_dao_url` maps to `org.killbill.dao.url`). - -These are loaded only when `org.killbill.server.lookupEnvironmentVariables` is set to `true` (this is enabled by default). - -These properties take the highest precedence among other configurable sources. - -* Runtime Configuration - -Properties loaded from a configuration file specified via `-Dorg.killbill.server.properties=`. - -If no file is specified, Kill Bill uses JVM system properties defined via `-Dproperty=value`. - -This source has the second-highest precedence among configurable sources. - -* Kill Bill Defaults - -These are default values defined within the Kill Bill codebase. - -They are registered dynamically by various *Config classes during application startup, covering configuration domains such as CatalogConfig, DaoConfig, LifecycleConfig, SecurityConfig, InvoiceConfig, PaymentConfig, OSGIConfig, and others. - -The following defaults are applied only when a property is not defined in any higher precedence source: - - org.killbill.persistent.bus.external.tableName=bus_ext_events - org.killbill.persistent.bus.external.historyTableName=bus_ext_events_history - org.killbill.server.enableJasypt=false - org.killbill.server.lookupEnvironmentVariables=true - org.slf4j.simpleLogger.log.jdbc=ERROR - - - -When a property is defined in multiple sources, Kill Bill applies the value from the highest precedence source and logs a warning indicating which sources defined it and which value was chosen. - -Example warning: - -`Property conflict detected for 'org.killbill.dao.healthCheckConnectionTimeout': -defined in sources [RuntimeConfiguration, EnvironmentVariables] - -using value from 'EnvironmentVariables': '11s'` - - -To make it easier to understand the runtime values of these properties, Kill Bill provides the `/v1/health/config` endpoint. -This endpoint displays the effective configuration currently in use along with information about which source each property value was derived from. - - -==== Per-Tenant Configuration - -In addition to system-wide properties, Kill Bill supports per-tenant configuration, allowing tenants to override specific system properties for their own environment. - -This provides fine-grained control in multi-tenant deployments, enabling different tenants to customize selected settings while still inheriting defaults from the global configuration. - -For more details, see the official documentation: https://docs.killbill.io/latest/plugin_installation#per-tenant-configuration. - === Using Health APIs As mentioned earlier, Aviate Health exposes endpoints that allow monitoring the health of a KB installation and fixing problems if any. Once the aviate plugin is installed, you can start using the Aviate Health APIs. These are documented in our https://apidocs.killbill.io/aviate-health[api docs]. @@ -165,16 +97,69 @@ The metrics exposed by the Aviate plugin can mainly be categorized in the follow Properties can be specified to configure the Kill Bill system including its plugins. The following https://docs.killbill.io/latest/userguide_configuration#configuration_properties_table[documentation] shows the main configuration properties. +The values for these properties can come from multiple sources, each with a defined precedence. + +==== Property Resolution Order (Highest to Lowest) +Kill Bill resolves property values in the following order, where higher precedence sources override lower ones: + +* Immutable System Property + +Includes the `user.timezone` property, which is force set to `GMT`. + +This property cannot be overridden. + +* Environment Variables + +Properties prefixed with `KB_org_` (for example, `KB_org_killbill_dao_url` maps to `org.killbill.dao.url`). + +These are loaded only when `org.killbill.server.lookupEnvironmentVariables` is set to `true` (this is enabled by default). + +These properties take the highest precedence among other configurable sources. + +* Runtime Configuration + +Properties loaded from a configuration file specified via `-Dorg.killbill.server.properties=`. + +If no file is specified, Kill Bill uses JVM system properties defined via `-Dproperty=value`. + +This source has the second-highest precedence among configurable sources. -The values for these properties can come from a number of sources and the system will evaluate based on the following order: +* Kill Bill Defaults -* Immutable system properties: Properties set by the Kill Bill system - e.g. `user.timezone` set to `GMT` -* Tenant configurations: Properties that have been overridden on a per-tenant level -* Environment variables: Environment variables that have been set using the `KB_org_*` syntax -* Runtime configurations: Properties that can be specified as a system property using the `-D=` syntax or through a system property file identified by the system property `-Dorg.killbill.server.properties=` -* Default property values: Default values if none of the above overrode the default value +These are default values defined within the Kill Bill codebase. -This flexibility is offered by default and it allows to adopt different deployment models along with a fine grained granularity at the tenant level. However, to make it easier to understand the runtime values of these properties, we have created the endpoint `/v1/health/config`: It provides the view of what the system is running along with the required information about where each property value comes from. +They are registered dynamically by various *Config classes during application startup, covering configuration domains such as CatalogConfig, DaoConfig, LifecycleConfig, SecurityConfig, InvoiceConfig, PaymentConfig, OSGIConfig, and others. + +The following defaults are applied only when a property is not defined in any higher precedence source: + + org.killbill.persistent.bus.external.tableName=bus_ext_events + org.killbill.persistent.bus.external.historyTableName=bus_ext_events_history + org.killbill.server.enableJasypt=false + org.killbill.server.lookupEnvironmentVariables=true + org.slf4j.simpleLogger.log.jdbc=ERROR + + + +When a property is defined in multiple sources, Kill Bill applies the value from the highest precedence source and logs a warning indicating which sources defined it and which value was chosen. + +Example warning: + +`Property conflict detected for 'org.killbill.dao.healthCheckConnectionTimeout': +defined in sources [RuntimeConfiguration, EnvironmentVariables] - +using value from 'EnvironmentVariables': '11s'` + + +To make it easier to understand the runtime values of these properties, Kill Bill provides the `/v1/health/config` endpoint. +This endpoint displays the effective configuration currently in use along with information about which source each property value was derived from. + + +==== Per-Tenant Configuration + +In addition to system-wide properties, Kill Bill supports per-tenant configuration, allowing tenants to override specific system properties for their own environment. + +This provides fine-grained control in multi-tenant deployments, enabling different tenants to customize selected settings while still inheriting defaults from the global configuration. + +For more details, see the official documentation: https://docs.killbill.io/latest/plugin_installation#per-tenant-configuration. === Queue Metrics