[wildfly-dev] Metrics & runtime attribute registration

[Brian Stansberry]

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:
> Hey guys,
>
> We had interesting discussion with Brian on
> https://github.com/wildfly/wildfly-core/pull/848#issuecomment-119778986
> about how we register runtime/metric attribute on resources.
>
> There are many cases where subsystems only register attributes /
> resources only when server is booting into normal mode.
> but if it server is booted only to "admin mode" all that runtime/metrics
> attributes are not registered and as such not seen in the model.
>
> Registering runtime attributes only in normal mode can cause that
> results of :read-resource-description/read-resource
> wouldn't return attributes that are on resources if server is started in
> admin mode or even CLI standalone.
> Our metadata already provides information if attributes is
> runtime/metric/configuration.
>
> This can cause problems for tooling that relies on output of those two
> operations.
>
> Looking at current state of the code, we do use both ways of registering
> attributes either conditionally or always.
> This probably originates from times where there was no good api/way to
> mark attribute/resource as runtime.
>
> I am personally am in favor of always registering runtime attributes as
> this makes sure that user isn't surprised by some extra/missing
> attributes based on fact how it is starting the server.
>
>
> What do you guys think? Should we always register it or have it
> conditionally?
>
> --
> tomaz
>
>
>
>
> _______________________________________________
> wildfly-dev mailing list
> wildfly-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/wildfly-dev
>


-- 
Brian Stansberry
Senior Principal Software Engineer
JBoss by Red Hat