[Oslc-pm] Review of PerfMon spec

[Steve K Speicher]

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