[wildfly-dev] Metrics & runtime attribute registration

[Brian Stansberry]

Silence is assent. ;) So I've opened 
https://issues.jboss.org/browse/WFCORE-831.

On 7/15/15 1:26 PM, Brian Stansberry wrote:
> 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