Re: [wildfly-dev] Metrics & runtime attribute registration

Based on the discussion in this thread and some related chats in hipchat, I propose the requirements below for this general topic, and very much welcome comments. Note that this thread is about metrics, but handling of non-metric runtime-only attributes and operations all have the same concerns. I've placed an * next to requirements that involve some code change in the WildFly Core kernel. If we can reach a consensus around these requirements, that consensus can become a JIRA to implement the * items. I. If an Extension's initialize method is executing in a process type where the extension CAN install runtime services, the extension MUST register all metrics, other runtime-only attributes, and runtime-only operations, regardless of whether the process is running in --admin-only mode. II. If an Extension's initialize method is executing in a process type where the extension CANNOT install runtime services, the extension MUST NOT register any metrics, other runtime-only attributes, or runtime-only operations.[1] For example, most extensions will not register these when executing on a HostController. III.* The ExtensionContext.isRuntimeOnlyRegistrationValid() MUST return the proper value to tell the extension which of conditions I and II apply. IV.* The AttributeDefinition class MUST expose a 'public ModelNode getUndefinedMetricValue()' method and the builders for it MUST expose a 'public void setUndefinedMetricValue(ModelNode value)' method. (See VI.A below for the purpose of this.) A.* If assertions are enabled and an AttributeDefinition that is passed to ManagementResourceRegistration registerReadOnlyAttribute or registerReadWriteAttribute returns a defined ModelNode from getUndefinedMetricValue(), an AssertionError MUST be thrown. Non-metrics cannot provide undefined metric values. B.* If assertions are enabled and an AttributeDefinition that is passed to ManagementResourceRegistration registerMetric returns a defined ModelNode from getDefaultValue(), an AssertionError MUST be thrown. Metrics cannot provide default values. C.* If assertions are enabled and an AttributeDefinition that is passed to ManagementResourceRegistration registerMetric returns a defined ModelNode from getUndefinedMetricValue() and also returns 'true' from isAllowNull(), an AssertionError MUST be thrown. This is an inconsistent setting, as the undefined metric value will ensure the client never sees an undefined result. V. The read-attribute handler for a metric or runtime-only attribute MUST set a result value consistent with the attribute description regardless of whether the expected runtime services are disabled due to running in --admin-only or some other configuration option such as a 'statistics-enabled' attribute being set to 'false'. Specifically, if the handler might not set a defined value in that situation, the isAllowNull() method from the attribute's AttributeDefinition MUST return 'true'. VI. The read-attribute handler for metrics that have a logical defined value even if runtime services are not present SHOULD set that value as the result when runtime services are not present. For example, for many 'counter' metrics a value of 0 is a logical defined value. A. The read-attribute handler for such a metric MAY choose to not set a result value itself when there are no runtime services, and instead delegate to the kernel to have the kernel set the result. To configure such a delegation, the AttributeDefinition for the metric must return a defined value from its getUndefinedMetricValue() method. (See IV.) B.* The kernel's handler for read-attribute MUST check if the registered handler for the attribute has not set a defined result. If it has not, and the attribute is a metric, and its definition's getUndefinedMetricValue() method returns a defined value, the kernel handler must set that value as the result. This behavior MUST occur regardless of the value of any 'include-defaults' parameter passed to the hander. The 'include-defaults' parameter is unrelated to metrics. VII. The read-attribute handler for metrics that do not have a logical defined value if runtime services are not present SHOULD return an undefined result and SHOULD NOT return an arbitrary meaningless value such as -1 or Integer.MAX_VALUE. This is not a MUST/MUST NOT requirement because it is understood that backwards compatibility requirements may prevent changes to some attributes, and also that some integrated libraries may return such values without the subsystem handler's being aware of that. VIII. The read-attribute handler for a custom runtime-only operation MUST set a result value consistent with the operation description regardless of whether the expected runtime services are disabled due to running in --admin-only or some other configuration option. Specifically, if the handler might not set a defined value in that situation, the isReplyAllowNull() method from the attribute's OperationDefinition MUST return 'true'. A. However, it is permissible for a custom runtime-only operation handler to throw an OperationFailedException in this situation. The 'runtime-only'=>true entry in the operation's descriptive metadata provides an indication to callers that this is a possible result. I think that's about it. ;) [1] At some point in the future the restriction on runtime-only operations may be lifted, in order to support executing the operation on all servers in a domain. On 7/13/15 4:26 PM, Tomaž Cerar wrote: -- Brian Stansberry Senior Principal Software Engineer JBoss by Red Hat