[jboss-as7-dev] Attributes, metrics, additional descriptive information for such

[Brian Stansberry]

Emanuel,

FYI I think this pretty much summarizes the various IRC etc discussions 
today about metrics. Thoughts?

1) Metrics are represented in the model description at the same level as 
"configuration" attributes.

2) Metrics are represented in a "read-resource" result the same as 
configuration attributes.

3) Metrics are stored in a ModelNodeRegistration in the same map as 
attributes
a) but they need to have a custom read handler registered, as the 
default model-reading one won't work

4) Multi-server queries will not be done via the domain/host level 
resources. This eliminates the "expense" issue of treating metrics
as attributes on a domain resource (expense due to need to read the 
metrics across all servers in order to
generate the full result.) Instead, domain and host level resources will 
not have metrics, and attributes will just return
the domain/host level value.

Instead, for multi-server results, wildcards and lists will be used:
e.g. host=*,server=*,subsystem=web,connector=http attribute=pool-size
e.g. host=[hostA,hostB],server=*,subsystem=web,connector=http 
attribute=pool-size
e.g. server-group=group1,host=*,server=*,subsystem=web,connector=http 
attribute=pool-size
e.g. 
server-group=[group1,group2],host=*,server=*,subsystem=web,connector=http attribute=pool-size

This needs thought as to how to implement; sounds nice conceptually.

5) The model description for an attribute will include two additional 
pieces of metadata:

storage (alternative term -- applies-to): Either
configuration = Derived from and stored in the persistent configuration 
(i.e. domain.xml/host.xml/standalone.xml).
runtime = Derived from and stored in runtime state only, and not in any 
persistent configuration.

There's an ongoing debate over "storage" vs "applies-to".

access-type: One of
read-only = Not modifiable via a simple write-attribute operation. Value 
will not change without some sort of management action.
read-write = Modifiable via a simple write-attribute operation. Value 
will not change without some sort of management action.
metric = Value may change without any management action. Not directly 
modifiable via a management action.


6) The value for said "storage" and "access-type" fields in the 
attribute description will be generated by the
READ_RESOURCE_DESCRIPTION operation handler. It will not come from the 
resource's DescriptionProvider (i.e. we
don't rely on developers correctly adding this metadata for each attribute.)

TBD:

1) "storage" vs "applies-to"

2) How to ensure the "storage" and "access-type" fields are correctly 
set? Likely replace/overload ModelNodeRegistration's

void registerReadOnlyAttribute(String attributeName, OperationHandler 
readHandler);
void registerReadWriteAttribute(String attributeName, OperationHandler 
readHandler, OperationHandler writeHandler);

with

void registerReadOnlyAttribute(String attributeName, OperationHandler 
readHandler, Storage storage);
void registerReadWriteAttribute(String attributeName, OperationHandler 
readHandler, OperationHandler writeHandler, Storage storage);
void registerMetric(String attributeName, OperationHandler readHandler);

2) We briefly touched on the concept of a "runtime entity" aka a 
"runtime resource". A resource that
only exists in the registry, but has no persistent representation in 
domain.xml,
host.xml or standalone.xml.
a) Said runtime resource cannot have attributes with storage=configuration
b) We briefly mentioned having recursive model reads stop at runtime 
resources, in order to avoid excessive cost.

3) If we have runtime resources, this status should probably be 
reflected in the resource description.
And probably should be stored directly in the ModelNodeRegistration, 
e.g. via

ModelNodeRegistration registerSubModel(PathElement address, 
DescriptionProvider descriptionProvider, Storage storage);

4) Does storage/applies-to have a 3rd value: "both"? IOW does 
"configuration" always imply "runtime"?

5) The "storage/applies-to" concept is relevant to operations in 
general, not just reads/write of attributes.

6) We need to know whether execution of an operation (including 
write-attribute) on a server puts that server
in a state where it requires a restart. If the operation will always 
trigger a restart requirement, we use
the interface implemented by the handler for the operation to determine 
this. Some operations may or may
not trigger a restart requirement; it depends on the value of the 
parameters and the current state when
they are applied.

Clients are likely to want to know about the restart impact before 
executing an operation (i.e. if it will/may/won't
trigger the need to restart).  So this should be added to the 
operation/attribute description.

7) Some operations can be applied to the runtime even if a previous 
operation has triggered the requirement
for a restart is required. Some may always work, some may or may not 
work depending on the params and
the runtime state. We currently have no mechanism for informing the 
server controller of this kind of thing;
we just disable all runtime updates once restart is required. It would 
be better to make this information
available to the server controller. Clients may want to know as well, so 
this should be added to the
operation/attribute description.

-- 
Brian Stansberry
Principal Software Engineer
JBoss by Red Hat