This specification defines the OSLC Performance Monitoring domain, a RESTful web services interface for the management
of domain specifica and supporting resources defined in the OSLC Core specification. To support these scenarios, this
specification defines a set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP
response codes, content type handling and resource formats.
This specification is being provided under the RF on Limited Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification,
and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page
(https://www.oasis-open.org/committees/oslc-domains/ipr.php).
Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.
Citation format:
When referencing this specification the following citation format should be used:
All capitalized terms in the following text have the
meanings assigned to them in the OASIS Intellectual Property Rights Policy (the
"OASIS IPR Policy"). The full Policy may be
found at the OASIS website.
This document and translations of it may be copied and
furnished to others, and derivative works that comment on or otherwise explain
it or assist in its implementation may be prepared, copied, published, and
distributed, in whole or in part, without restriction of any kind, provided
that the above copyright notice and this section are included on all such
copies and derivative works. However, this document itself may not be modified
in any way, including by removing the copyright notice or references to OASIS,
except as needed for the purpose of developing any document or deliverable
produced by an OASIS Technical Committee (in which case the rules applicable to
copyrights, as set forth in the OASIS IPR Policy, must be followed) or as
required to translate it into languages other than English.
The limited permissions granted above are perpetual and will
not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is
provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that
believes it has patent claims that would necessarily be infringed by
implementations of this OASIS Committee Specification or OASIS Standard, to
notify OASIS TC Administrator and provide an indication of its willingness to
grant patent licenses to such patent claims in a manner consistent with the IPR
Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC
Administrator if it is aware of a claim of ownership of any patent claims that
would necessarily be infringed by implementations of this specification by a
patent holder that is not willing to provide a license to such patent claims in
a manner consistent with the IPR Mode of the OASIS Technical Committee that
produced this specification. OASIS may include such claims on its website, but
disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of
any intellectual property or other rights that might be claimed to pertain to
the implementation or use of the technology described in this document or the
extent to which any license under such rights might or might not be available;
neither does it represent that it has made any effort to identify any such
rights. Information on OASIS' procedures with respect to rights in any document
or deliverable produced by an OASIS Technical Committee can be found on the
OASIS website. Copies of claims of rights made available for publication and
any assurances of licenses to be made available, or the result of an attempt
made to obtain a general license or permission for the use of such proprietary
rights by implementers or users of this OASIS Committee Specification or OASIS
Standard, can be obtained from the OASIS TC Administrator. OASIS makes no
representation that any information or list of intellectual property rights
will at any time be complete, or that any claims in such list are, in fact,
Essential Claims.
The name "OASIS" is a trademark of OASIS, the owner and developer of this
specification, and should be used only to refer to the organization and its
official outputs. OASIS welcomes reference to, and implementation and use of,
specifications, while reserving the right to enforce its marks against
misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark
for above guidance.
Introduction
(this section is informative)
This specification builds on the [OSLCCore2] to define the resources and operations supported by an Open Services
for Lifecycle Collaboration (OSLC) Performance Monitoring provider. This version of the specification has version 2.0
to indicate that it is an [OSLCCore2] compliant specification.
Performance Monitoring resources define records whose content is most useful in the testing and operational stages of
the software development, test, and deployment lifecycle. They represent individual resources as well as their relationships
to other resources and to other linked resources outside of the Performance Monitoring domain. The intent of this specification
is to define the set of HTTP-based RESTful interfaces in terms of HTTP methods: GET, POST, PUT and DELETE, HTTP response
codes, MIME type handling and resource formats. The capabilities of the interface definitions are driven by key integration
scenarios and therefore do not represent a complete set of operations on resources or resource types. The resource
formats and operations may not exactly match the native models supported by existing implementations, but are intended
to be compatible with them.
Performance Monitoring, as referenced in this specification, refers to the collection of data about Information Technology
(IT) systems such as servers, workstations, services, and transactions to assess their operational health and enable
proactive manual human intervention before emerging problems escalate into widespread degradation or outages. See the
Performance Monitoring Scenarios page for several specific examples.
IPR Policy
This Committee Specification Public Review Draft is being developed under the
RF on Limited Terms Mode of the
OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any
patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing
terms, please refer to the Intellectual Property Rights section of the TC’s web page (
https://www.oasis-open.org/committees/oslc-domains/ipr.php).
Terminology
Service Provider - an implementation of the OSLC Performance Monitoring specification as a server. OSLC
Performance Monitoring clients consume these services.
Performance Monitoring Record - Defines the unit of information made available by a Performance Monitoring
service provider. The information could be numeric metrics, status, or some other kind of property of interest to
monitoring consumers.
Monitored resource - An entity such as a software server or computer system that is monitored by a software
agent to ensure its performance and availability. In this specification when we use the word ‘resource’
to mean a monitored resource rather than an OSLC resource, we try to qualify the word to make our intent clear.
References
Typographical Conventions and Use of RFC Terms
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples,
and notes in this specification are non-normative. Everything else in this specification is
normative.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY,
and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
Base Requirements
Specification Versioning
This specification follows the specification version guidelines given in [OSLCCore2].
Namespaces
Defined
OSLC Performance Monitoring defines the namespace shown in the table below. This namespace URI and prefix are used
to designate the resources and their properties defined in this specification.
Use of the suggested prefix is RECOMMENDED, because doing so aids debugging and other situations where humans read
the data.
Suggested namespace prefix
Namespace URI
pm
http://open-services.net/ns/perfmon#
Re-used from other specifications
In addition to the namespace URIs and namespace prefixes defined in the [OSLCCore2], OSLC Performance Monitoring
also re-uses vocabulary terms from other namespaces. The namespace prefixes in the table below are used in this
specification, and match the recommendations made by the specification that defines each.
Namespace prefix used
Namespace URI
Usage
ems
http://open-services.net/ns/ems#
Vocabulary is required for Performance Monitoring providers to expose metrics. Defined in the
OSLC Estimation and Measurement domain.
crtv
http://open-services.net/ns/crtv#
Vocabulary is expected to be commonly used by Performance Monitoring providers, but is not required. Defined
in the
OSLC Reconciliation domain.
Resource Formats
In addition to the requirements for
[OSLCCore2ResourceRepresentations], this section outlines further refinements and restrictions.
See
HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC
Performance Monitoring resource.
For HTTP GET requests on all OSLC Performance Monitoring and OSLC Core defined resource types,
Performance Monitoring Providers MUST provide RDF/XML representations. If provided, the RDF/XML representation SHOULD
follow the guidelines outlined in the
[OSLCCore2RepresentationGuidance] for RDF/XML.
Performance Monitoring Providers MAY provide XML and JSON representations. The XML and JSON representations SHOULD
follow the guidelines outlined in the
[OSLCCore2RepresentationGuidance].
Performance Monitoring Consumers requesting RDF/XML SHOULD be prepared for any valid RDF/XML document. Performance
Monitoring Consumers requesting XML SHOULD be prepared for representations that follow the guidelines outlined
in the
[OSLCCore2RepresentationGuidance].
Performance Monitoring Providers SHOULD support an [X]HTML representation and a user interface (UI) preview as defined
by
[OSLCCore2UIGuidance]
For HTTP PUT/POST request formats for Performance Monitoring resources,
Performance Monitoring Providers MUST accept RDF/XML representations and MAY accept XML representations. Performance
Monitoring Providers accepting RDF/XML SHOULD be prepared for any valid RDF/XML document. If XML is accepted, Performance
Monitoring Providers SHOULD be prepared for representations that follow the guidelines outlined in the
[OSLCCore2RepresentationGuidance].
Performance Monitoring Providers MAY accept XML and JSON representations. Performance Monitoring Providers accepting
XML or JSON SHOULD be prepared for representations that follow the guidelines outlined in the
[OSLCCore2RepresentationGuidance].
For HTTP GET response formats for Query requests,
Performance Monitoring Providers MUST provide RDF/XML and MAY provide JSON, XML, and Atom Syndication Format XML.
When Performance Monitoring Consumers request:
application/rdf+xml Performance Monitoring Providers MUST respond with RDF/XML representation without restrictions.
application/xml Performance Monitoring Providers SHOULD respond with OSLC-defined abbreviated XML representation as defined in
the
[OSLCCore2RepresentationGuidance]
application/atom+xml Performance Monitoring Providers SHOULD respond with Atom Syndication Format XML representation as defined in
the
[OSLCCore2RepresentationGuidance]
If supported, the Atom Syndication Format XML representation SHOULD use RDF/XML representation without restrictions
for the atom:content entries representing the resource representations.
Authentication
See
[OSLCCore2] Authentication section. This specification puts no additional constraints on authentication.
Error Responses
See
[OSLCCore2] Error Responses section. This specification puts no additional constraints on error responses.
Pagination
Performance Monitoring Providers SHOULD support pagination of query results and MAY support pagination of a single
resource’s properties as defined by the OSLC Core Specification.
Labels for Relationships
Relationships to other resources are represented as properties whose values are the URI of the object or target resource.
When a relationship property is to be presented in a user interface, it may be helpful to provide an informative
and useful textual label for that relationship instance. (This in addition to the relationship property URI and the
object resource URI, which are also candidates for presentation to a user.)
[OSLCCore2LinksGuidance] allows OSLC providers to support a
dcterms:title link property in resource representations, using the anchor approach (reification), but this specification discourages
its use (providers SHOULD NOT use it, and consumers SHOULD NOT depend on it). At the time this specification was
written, the W3C RDF working group was on a path to remove reification from the next version of RDF, and it was noted
that reification never was normatively defined even in the RDF/XML syntax W3C Recommendation, where it occurs informatively.
Support for all HTTP methods in
the conformance table is not required for all Performance Monitoring resources. The following table summarizes the
requirements for each resource definition, HTTP method, and media type combination. A value of
N/A means this specification does not impose any constraints on it.
Resource
RDF/XML
XML
JSON
HTML
Other
Performance Monitoring Record
GET
MUST
MAY
SHOULD
SHOULD
MAY
PUT
MAY
MAY
MAY
N/A
MAY
POST
MAY
MAY
MAY
N/A
MAY
DELETE
N/A
N/A
N/A
N/A
N/A
Performance Monitoring service providers SHOULD support deletion of any resources for which they allow creation.
Performance Monitoring Specification Guidelines
(this section is informative)
Linking a Performance Monitoring Record to the Resource it Describes
In addition to a Performance Monitoring Record having a predicate to refer to the monitored resource is is part of
using pm:isPartOf, a Performance Monitoring record may be a class type for a monitored resource, such that the pm:isPartOf
predicate value refers to itself as the object value.
Extending Metrics
Choose the correct metric categor(ies) for your metric.
Decide whether your class should be part of the ‘perfmon’ namespace or a private namespace.
Create an RDFS class for your metric.
Create an instance of a PerformanceMonitoringRecord
Put a timestamp on it to indicate when it was collected
Put an ems:observes predicate in your PerformanceMonitoringRecord and have it refer to an ems:Measure instance
Use your metric in the ems:Measure instance
Use ems:unitOfMeasure to specify whether the metric is a rate, a ratio, a quantity, a time, etc.
Relate PerformanceMonitoringRecord to monitored resource using isPartOf property
Conformance
This specification is based on
[OSLCCore2]. OSLC Performance Monitoring consumers and service providers MUST be compliant with both
the core specification and this Performance Monitoring specification, and SHOULD follow all the guidelines and recommendations
in both these specifications.
The following table summarizes the requirements from OSLC Core Specification as well as some (but not all) additional
requirements specific to Performance Monitoring. See the full content of the Performance Monitoring specification for
all requirements. Note that this specification further restricts some of the requirements for OSLC Core Specification
as noted in the Origin column of the compliance table. See further sections in this specification or the OSLC Core
Specification to get further details on each of these requirements.
Any consumer or service provider behaviors are allowed unless explicitly prohibited by this or dependent specifications;
conditional permissive requirements, especially those qualified with “MAY”, are implicitly covered by the
preceding clause. While technically redundant in light of that broad permission, OSLC specifications do still make
explicit MAY-qualified statements in cases where the editors believe doing so is likely to add clarity.
OSLC service providers SHOULD provide HTML representations for HTTP GET requests
1The OSLC Core Specification indicates service providers MAY provide Query Capabilities. This specification
strengthens the requirement.
2The OSLC Core Specification indicates service providers MAY support the OSLC Query Syntax. This specification
makes OSLC Query Syntax support a MUST requirement for service providers providing query capabilities.
3Support for all common HTTP methods is not required for all resources defined by this specification. See
the
HTTP Method support table for details.
The working group participants who author and maintain this working draft specification, monitor a distribution list
where issues or questions can be raised, see
Performance Monitoring Mailing List
The following individuals have participated in the creation of this specification and are gratefully acknowledged:
Participants:
Fabio Ribeiro, Koneksys (Editor)
Jim Amsden, IBM (Chair)
Graham Bachelor, IBM (Chair)
Janet Andersen
Jim Conallen
John Arwe
Julie Bielski
Michael Fiedler
Steve Speicher
Tuan Dang
