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 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.
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).
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.
This specification follows the specification version guidelines given in [[!OSLCCore2]].
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#
|
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. |
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,
For HTTP PUT/POST request formats for Performance Monitoring resources,
For HTTP GET response formats for Query requests,
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]]
See [[!OSLCCore2]] Authentication section. This specification puts no additional constraints on authentication.
See [[!OSLCCore2]] Error Responses section. This specification puts no additional constraints on error responses.
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.
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.
OSLC Performance Monitoring Resources 2.0 Defines the vocabulary terms and constraints for OSLC Performance Monitoring resources. These terms and constraints are specified according to [[!OSLCCoreVocab]].
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.
(this section is informative)
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.
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.
| Number | Requirement | Level | Origin(s) | Meaning |
|---|---|---|---|---|
| Perfmon-1 | Unknown properties and content | MUST | Core | OSLC clients MUST preserve unknown content |
| Number | Requirement | Level | Origin(s) | Meaning |
|---|---|---|---|---|
| Perfmon-2 | Unknown properties and content | MAY | Core | OSLC service providers MAY ignore unknown content |
| Perfmon-3 | Unknown properties and content | MUST | Core | OSLC service providers MUST return an error code if recognized content is invalid. |
| Perfmon-4 | Resource Operations | MUST | Core | OSLC service providers MUST support resource operations via standard HTTP operations |
| Perfmon-5 | Resource Paging | MAY | Core | OSLC services MAY provide paging for resources |
| Perfmon-6 | Partial Resource Representations | MAY | Core | OSLC service providers MAY support HTTP GET requests for retrieval of a subset of a resource’s properties via the oslc.properties URL parameter |
| Perfmon-7 | Partial Resource Representations | MAY | Core | OSLC service providers MAY support HTTP PUT requests for updating a subset of a resource’s properties via the oslc.properties URL parameter |
| Perfmon-8 | Service Provider Resources | MAY | Core | OSLC service providers MAY provide a Service Provider Catalog resource |
| Perfmon-9 | Service Provider Resources | MUST | Core | OSLC service providers MUST provide a Service Provider resource |
| Perfmon-10 | Creation Factories | MAY | Core | OSLC service providers MAY provide creation factories to enable resource creation via HTTP POST |
| Perfmon-11 | Query Capabilities | SHOULD 1 | Perf Mon, Core | OSLC service providers SHOULD provide query capabilities to enable clients to query for resources |
| Perfmon-12 | Query Syntax | MUST 2 | Perf Mon, Core | If a service provider supports a OSLC query capability, its query capabilities MUST support the OSLC Core Query Syntax |
| Perfmon-13 | Delegated UI Dialogs | SHOULD | Core | OSLC service providers SHOULD allow clients to discover, via their service provider resources, any Delegated UI Dialogs they offer. |
| Perfmon-14 | Delegated UI Dialogs | SHOULD | Core | OSLC service providers SHOULD offer delegated UI dialogs for resource creation |
| Perfmon-15 | Delegated UI Dialogs | SHOULD | Core | OSLC service providers SHOULD offer delegated UI dialogs for resource selection |
| Perfmon-16 | UI Preview | SHOULD | Core | OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources |
| Perfmon-17 | HTTP Basic Authentication | MAY | Core | OSLC Services MAY support Basic Auth |
| Perfmon-18 | HTTP Basic Authentication | SHOULD | Core | OSLC Services SHOULD support Basic Auth only over HTTPS |
| Perfmon-19 | OAuth Authentication | MAY | Core | OSLC service providers MAY support OAuth |
| Perfmon-20 | OAuth Authentication | SHOULD | Core | OSLC service providers that support OAuth SHOULD allow clients to discover the required OAuth URLs via their service provider resource |
| Perfmon-21 | Error Responses | MAY | Core | OSLC service providers MAY provide error responses using Core-defined error formats |
| Perfmon-22 | RDF/XML Representations | MUST 3 | Perf Mon, Core | OSLC service providers MUST offer an RDF/XML representation for HTTP GET responses |
| Perfmon-23 | RDF/XML Representations | MUST 3 | Perf Mon, Core | OSLC service providers MUST accept RDF/XML representations on PUT requests. |
| Perfmon-24 | RDF/XML Representations | MUST 3 | Perf Mon, Core | RDF/XML representations on POST requests whose semantic intent is to create a new resource instance. |
| Perfmon-25 | XML Representations | MAY 3 | Perf Mon, Core | OSLC service providers MAY provide a XML representation for HTTP GET, POST and PUT requests that conform to the Core Guidelines for XML. |
| Perfmon-26 | JSON Representations | MAY 3 | Perf Mon, Core | OSLC service providers MAY provide JSON representations for HTTP GET, POST and PUT requests that conform to the Core Guidelines for JSON |
| Perfmon-27 | HTML Representations | SHOULD 3 | Perf Mon, Core | OSLC service providers SHOULD provide HTML representations for HTTP GET requests |
(this section is informative)
(this section is informative)
See OSLC Performance Monitoring 2.0 Appendix B: Resource Shapes
We make this specification available under the terms and conditions set forth in the site Terms of Use, IP Policy, and the Workgroup Participation Agreement for this Workgroup.
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
Also the issues found with this specification and their resolution can be found at OSLC Performance Monitoring 2.0 Issues.
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
| Revision | Date | Editor | Changes Made |
| 01 | 07/06/2016 | Jim Amsden | CSD was approved and published. |