[wildfly-dev] Metrics & runtime attribute registration

Mon Aug 24 09:56:27 EDT 2015

The basic thrust of this thread was that the *API* should not be 
changing based on things like --admin-only or statistics-enabled=false. 
The results obtained by invoking ops can change, though, so long as 
those results are consistent with the published metadata.

So, I don't see a problem with c). VII.A. in the WFCORE-831 description 
covers (admittedly in a not-so-elegant way) how the results obtained can 
change:

"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."

Where this starts to break down is if the API promises that a particular 
resource will exist, and it just can't. Carrying the WFCORE-831 
semantics for metrics all the way forward to creating fictitious 
resources is too far.

If a child runtime-only resource is registered under foo=* that's not 
such a problem as there's no promise that any particular value of "*" 
will exist. But /deployment=x.war/subsystem=logging is more of a problem.

Extending the VIII.A type thing to a child resource (i.e so throwing 
NoSuchResourceException is ok, because the resource is 'runtime-only' 
sounds bad. People invoke custom ops like 'flush-ds' intentionally. But 
trying to walk a resource tree is something much more likely to be done 
automatically by a tool.

How forgiving is the read-resource handler? IIRC there's logic in there 
to ignore some sorts of runtime-only failures, to avoid their causing 
recursive reads to fail.

On 8/24/15 8:38 AM, Kabir Khan wrote:
> I am looking at https://issues.jboss.org/browse/WFCORE-831. Basically what is new is registering the same ‘stuff’ for an admin-only server, as for a normal server. Does this only apply to attributes?
> Having a glance of the usage of EC.isRuntimeOnlyRegistrationValid(), in addition to toggling registration of attributes we currently use is to toggle:
>
> a) Register runtime resources in the main subsystem model model (probably some examples in messaging)
> b) Register deployment resources (e.g. logging and datasources)
> c) Register runtime operations (e.g. jdr report, Ds flush)
>
> I don't think having b) and c) makes sense if it is an admin-only server, but perhaps a) does? Still, where would the data for a) come from?
>
>
>> On 20 Jul 2015, at 15:32, Brian Stansberry <brian.stansberry at redhat.com> wrote:
>>
>> 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
>> _______________________________________________
>> 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