[Oslc-pm] Review of PerfMon spec
Steve K Speicher
sspeiche at us.ibm.com
Fri Nov 30 15:34:14 EST 2012
Jim Conallen and I have reviewed the Performance Monitoring 2.0 (dated Nov
28 [1]) and some related documents
This review is NOT a review from the Core WG, though we are 2 Core WG
members who decided to provide some feedback.
Sorry these are in no particular order. Some are nit picky and some may
have a bigger impact:
1. In the scenarios (separate reference), and throughout the spec the term
'resource' is used to refer to the things that are being monitored. We
take this to be a term in the domain (i.e. web app server). This term is
also used across the OSLC to represent the things being passed in and out
of the REST calls. A word of explanation of this might be useful for the
first time reader.
2. What is a 'resource registry' can this term be defined better?
3. Typos in query support section.
"The Query Capability MUST the oslc:where parameter and SHOULD support the
oslc:select parameter:" This sentence ends with a colon. missing a word
between 'MUST' and 'the'. Query parameters have dots not colons in them
(oslc:where should be oslc.where). The oslc.prefix MUST supported if the
full syntax of the oslc.where is (required when specifying properties,
full URI can not be used).
4. If other query syntaxes are supported, how does the client know what
they are? The OSLC Core provides no guidance on query syntax other than
simple query. There are a number of things a PerfMon provider may do, not
sure it is worth listing all. Recommend getting rid of that MAY section
altogether.
5. This spec depends on other specifications that have not finalized (ESM
and Recon). Either coordinate the finalization with or after the dependent
specs, or remove the dependency on these specs.
6. Why does spec guidance provide prefix suggestions for other domains? It
may be appropriate to suggest a prefix for the perfmon domain, but not
others. It is expected define prefixes that are used throughout the rest
of the spec, but not so suggest that others use them.
The namespaces section should look more like the other specs and just
state: "In addition to the namespace URIs and namespace prefixes defined
in the OSLC Core specification, OSLC Performance Monitoring defines the
namespace URI of http://open-services.net/ns/perfmon# with a namespace
prefix of pm."
7. dcterms:isPartOf has an occurs value of "one-or-one". Should this be
exactly-one?
8. In the samples Turtle is used. Turtle is never even mentioned in the
specification. Recommend either include turtle as a MAY representation in
the spec, or remove it from the samples.
9. #Reporting-Issues-on-the-Specification The Issues link is to a
non-existent page.
10. In the sample the property dcterms:date is used, and in the spec it is
specified as xsd:dateTime. In the sample it is not typed, and looks like
a string.
11. #Contributors Commas between the contributors names. Or does Janet
have a lot of middle names?
12. #Performance-Monitoring-Specification-Guidelines Recommend that the
Guidelines section either provide a lot more useful information or pull
it, as it does not seem to provide much useful information. We couldn't
make much sense out of how it would be applied and there are two sections
that are empty
13. #Appendix-B.3A-Resource-Shapes Shapes appendix is empty.
14. #Intellectual-Property-Covenant The patent non-assert document is
missing or unlinked
15. Common Resource Type Vocabulary is not a recommended or good name. It
overloads the term "resource", will raise separately with Recon WG. We
should not propagate this name but work with them to resolve it.
16. PMR is used but never defined. Mixture of casing of such as
PerformandMonitoringRecord (no prefix) , etc suggest consistently
referring to the resource or the class name
17. Mixture of formatting issues: MUST/MAY/SHOULD not always BOLD, etc
18. Intro mentions IT, be good to define the acronym for completeness
19. Why are last 2 of 4 scenarios in table have no data in table?
http://open-services.net/wiki/performance-monitoring/Performance-Monitoring-Scenarios/#Current-Iteration-Scenarios
20.
http://open-services.net/wiki/performance-monitoring/Scenario-Coverage-Report/
missing business goal like other scenarios (or some intro upfront text)
21. #Terminology definition of PMR is quite thin, be good to pull up some
of the text from the more detailed PMR definition like "This could be
numeric metrics, status, or some other kind of property of interest to
monitoring consumers."
22. #Resource-Definitions Not sure what these sentences are saying about a
predicate "The diagram below shows an example of one way that a
Performance Monitoring Record resource may relate to the resources it
describes. With this option, the monitored resource has a Performance
Monitoring record as a predicate."
23. #Resource-Definitions 1st paragraph is redundant with 2nd to last in
the context of "Providers MAY define additional provider-specific
properties; providersSHOULD use their own namespaces for such properties,
or use standard Dublin Core or RDF namespaces and properties where
appropriate.". Recommend removing 1st paragraph.
24. #Performance_Monitoring_Record
rdf:type -- at least should include
perfmon:PerformanceMonitoringRecord, right?
ems:observes -- read the description a couple times and still not sure
I get it.
...about a resource “EMS” -- what is *resource EMS*?
...MAY be of any type Core -- what does it mean to be *of any type
Core*?
When it refers to "the resource" talking about the subject or object
resource?
25. #Resource.3A-ems.3AMeasure The Turtle example has a weird trailing ;
and then ., suggest removing the ;. There is an unneeded comment "#
rdf:type". Note: the turtle samples in the appendix have the same
problem. It would be good to add the @prefix definitions to make it a
valid Turtle doc.
26. #Metric-Categories consider Turtle example. Also RDFS is used and not
defined.
27. #Resource-Properties
pm:mobilityEnabled -- the description had me wanting more. I'm mobile,
would I be a valid value for this property? Not sure what "move about
dynamically" means
pm:availabilityStatus -- "All values present MUST be semantically
compatible" how do I know if I do or don't conform to this?
[1] -
http://open-services.net/wiki/performance-monitoring/OSLC-Performance-Monitoring-Specification-Version-2.0/revision/1321/
Feel free to contact us with any clarifications needed.
Thanks,
jim conallen
Steve Speicher
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-pm_open-services.net/attachments/20121130/50cd196f/attachment.html>
More information about the Oslc-Pm
mailing list