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

[Emanuel Muckenhuber]

On 01/26/2011 01:18 AM, Brian Stansberry wrote:
> 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.
>

This does seem to go a bit beyond metrics - In general it's the logical 
configuration view vs. the actual runtime state of a domain. Where i'm 
not sure it makes much sense trying to combine them into one single view 
(well let's say one which can be retrieved with recursive=true).

First from a tooling perspective i don't think you want to have the 
metrics from possibly 100 servers together with the configuration (where 
you rather either pick one of them). Also if we allow system property 
replacement for standalone the actual runtime state is again different 
from the configuration. So having the runtime information as i.e. a 
separate operation sounds more interesting to me. This should also make 
the "cost" of the operation more obvious. Obviously we could  create 
some convenience operations which just get both.

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

I do like the concept of using wildcards to query the domain model in 
general - also for standalone, otherwise you would have to e.g. first 
query the description to know which subsystems are present in order to 
retrieve the model for them. Additionally a query mechanism based on 
server-groups might be interesting as well.

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

Well as said i'm not a big fan of having runtime state as an simple 
attribute. Declaring it as part of the metadata makes sense though.

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

Sounds good to me.

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

I don't like either of them, although "impact" might not be much better :)

> 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);
>

Having a metric handler per attribute-name / metric-name seems too much. 
I'd rather have an optional attribute-name, so the metric handler can 
either filter or just get one metric.

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

A third one might be useful, like when you change a system property. It 
can be applied to the runtime without requiring a restart. However it 
will most likely only affect the runtime after a restart.

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

Yeah, i think operations should be able to declare their impact.

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

Yeah, additional metadata for this kind of information sounds reasonable 
as well (applies to both).