History   View   Links to this page Revision from: 2012 October 7 | 08:29 pm
This is the revision from 2012 October 7 at 08:29 pm   View the current live version of the article.
OSLC_logo.png

Open Services for Lifecycle Collaboration
Performance Monitoring Specification Version 2.0

Status: 2.0 Draft Specification - 8 October 2012

NOTE: This version of the specification has version 2.0 to indicate that it is an OSLC Core 2.0 compliant specification. This specification is the initial version of an OSLC Performance Monitoring specification.

This Version

Latest Version

Previous Version

  • N/A

Authors

Contributors

Table of Contents

Contents

  • Resource Properties
  • Service Provider HTTP Method Support
  • Performance Monitoring Specification Guidelines
  • Appendix A: Samples
  • Appendix B: Resource Shapes
  • Appendix C: Notices and References

    • License

    Creative Commons Attribution License
    This work is licensed under a Creative Commons Attribution License.

    Notation and Conventions

    The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.

    Introduction

    (this section is informative)

    This specification builds on the OSLC Core Specification to define the resources and operations supported by an Open Services for Lifecycle Collaboration (OSLC) Performance Monitoring provider.

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

    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.

    Base Requirements

    Compliance

    This specification is based on OSLC Core Specification. 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.

    Requirements on OSLC Consumers

    Requirement Level Origin(s) Meaning
    Unknown properties and content MUST Core OSLC clients MUST preserve unknown content

    Requirements on OSLC Service Providers

    Requirement Level Origin(s) Meaning
    Unknown properties and content MAY Core OSLC service providers MAY ignore unknown content
    Resource Operations MUST Core OSLC service providers MUST support resource operations via standard HTTP operations
    Resource Paging MAY Core OSLC services MAY provide paging for resources
    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
    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
    Service Provider Resources MAY Core OSLC service providers MAY provide a Service Provider Catalog resource
    Service Provider Resources MUST Core OSLC service providers MUST provide a Service Provider resource
    Creation Factories MAY Core OSLC service providers MAY provide creation factories to enable resource creation via HTTP POST
    Query Capabilities SHOULD1 Perf Mon, Core OSLC service providers SHOULD provide query capabilities to enable clients to query for resources
    Query Syntax MUST2 Perf Mon, Core If a service provider supports a OSLC query capability, its query capabilities MUST support the OSLC Core Query Syntax
    Query Syntax MAY Core OSLC query capabilities MAY support other query syntax
    Delegated UI Dialogs SHOULD Core OSLC service providers SHOULD allow clients to discover, via their service provider resources, any Delegated UI Dialogs they offer.
    Delegated UI Dialogs SHOULD Core OSLC service providers SHOULD offer delegated UI dialogs for resource creation
    Delegated UI Dialogs SHOULD Core OSLC service providers SHOULD offer delegated UI dialogs for resource selection
    UI Preview SHOULD Core OSLC Services SHOULD offer UI previews for resources that may be referenced by other resources
    HTTP Basic Authentication MAY Core OSLC Services MAY support Basic Auth
    HTTP Basic Authentication SHOULD Core OSLC Services SHOULD support Basic Auth only over HTTPS
    OAuth Authentication MAY Core OSLC service providers MAY support OAuth
    OAuth Authentication SHOULD Core OSLC service providers that support OAuth SHOULD allow clients to discover the required OAuth URLs via their service provider resource
    Error Responses MAY Core OSLC service providers MAY provide error responses using Core-defined error formats
    RDF/XML Representations MUST3 Perf Mon, Core OSLC service providers MUST offer an RDF/XML representation for HTTP GET responses
    RDF/XML Representations MUST3 Perf Mon, Core OSLC service providers MUST accept RDF/XML representations on PUT requests.
    RDF/XML Representations MUST3 Perf Mon, Core RDF/XML representations on POST requests whose semantic intent is to create a new resource instance.
    XML Representations MAY3 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.
    JSON Representations MAY3 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
    HTML Representations SHOULD3 Perf Mon, Core 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.

    Specification Versioning

    See OSLC Core Specification Versioning section.

    Namespaces

    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. This namespace URI and prefix are used to designate the resources defined in this specification and their properties.

    Suggested namespace prefix Namespace URI Usage
    pm http://open-services.net/ns/perfmon# Defined in this specification
    ems http://open-services.net/ns/ems# Defined in the OSLC Estimation and Measurement domain
    crtv http://open-services.net/ns/crtv# Defined in the OSLC Reconciliation domain

    Resource Formats

    In addition to the requirements for OSLC Defined Resource Representations, 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 OSLC Core Representations Guidance for RDF/XML.
    • Performance Monitoring Providers MAY provide XML and JSON representations. The XML and JSON representations SHOULD follow the guidelines outlined in the OSLC Core Representations Guidance.
    • 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 OSLC Core Representations Guidance.
    • Performance Monitoring Providers SHOULD support an [X]HTML representation and a user interface (UI) preview as defined by UI Preview Guidance

    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 OSLC Core Representations Guidance.
    • 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 OSLC Core Representations Guidance.

    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 OSLC Core Representations Guidance
    • application/atom+xml Performance Monitoring Providers SHOULD respond with Atom Syndication Format XML representation as defined in the OSLC Core Representations Guidance
    • 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 OSLC Core Authentication section. This specification puts no additional constraints on authentication.

    Error Responses

    See OSLC Core 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.) OSLC Core Links Guidance 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.

    Resource Definitions

    Resources defined by this specification can have properties other than those described here, in any namespace. It is recommended that any additional properties exist in their own unique namespace and not use the namespaces defined in this specification.

    A list of properties is defined for each type of resource. Most of these properties are identified in OSLC Core Appendix A: Common Properties. Any exceptions are noted. Relationship properties refer to other resources. These resources may be any RDF resource; that is, they may or may not be in any OSLC domain, including Performance Monitoring.

    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 class type, allowing clients an easy way to query for resources that also have associated metrics. Two other options are shown near the bottom of this specification in the section entitled Performance Monitoring Specification Guidelines.

    pm_domain5.JPG

    For all resource types defined in this specification, all required properties (those defined with an occurrence of exactly-one or one-or-many) MUST exist for each resource and must be provided when requested. All other properties are optional, and might not exist on some or any resources; those that do not exist will not be present in the returned representation even if requested, while those that do exist MUST be provided if requested. Providers MAY define additional provider-specific properties; providers SHOULD use their own namespaces for such properties, or use standard Dublin Core or RDF namespaces and properties where appropriate.

    If no specific set of properties is requested, all properties are returned - both those defined in this specification as well as any provider-specific ones. See Selective Property Values in the OSLC Core Specification.

    Question to WG: Do we want this paragraph? Appears it was copied from Automation. we are otherwise silent on oslc.properties.

    Consumers of OSLC Performance Monitoring services should note that some resources may have a very large number of related resources, and that some resources may be very large and/or expensive to compute. For this reason, consumers are strongly encouraged to use the oslc.properties parameter to limit the properties returned from a request to the subset required. See Selective Property Values in the OSLC Core Specification.

    Resource: Performance Monitoring Record

    • Name: PerformanceMonitoringRecord
    • Description: A resource representing performance monitoring information.
    • Type URI http://open-services.net/ns/perfmon#PerformanceMonitoringRecord

    PerformanceMonitoringRecord Properties

    Prefixed Name Occurs Read-only Value-type Representation Range Description
    OSLC Core: Common Properties
    rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs (RDF).
    dcterms:title zero-or-one unspecified XMLLiteral n/a n/a A name given to the resource (reference: Dublin Core). The title of the resource represented as rich text in XHTML content. Its value SHOULD include only content that is valid inside an XHTML <span> element (OSLC Core - Common).
    dcterms:description zero-or-one unspecified XMLLiteral n/a n/a An account of the resource (Dublin Core). The value SHOULD be represented as rich text in XHTML syntax, and SHOULD include only content that is valid and suitable inside an XHTML <div> element (OSLC Core - Common).
    dcterms:identifier zero-or-one True String n/a n/a An unambiguous reference to the resource within a given context (Dublin Core). A unique identifier for a resource. Typically read-only and assigned by the service provider when a resource is created. Not typically intended for end-user display (OSLC Core - Common).
    dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (Dublin Core)
    dcterms:modified zero-or-one True DateTime n/a n/a Date on which the resource was changed (Dublin Core). Timestamp of latest resource modification (OSLC Core - Common).
    oslc:instanceShape zero-or-one True Resource Reference oslc:ResourceShape A link to the resource’s OSLC Resource Shape that describes the possible properties, occurrence, value types, allowed values and labels. This shape information is useful in displaying the subject resource as well as guiding clients in performing modifications (OSLC Core - Common).
    oslc:serviceProvider zero-or-one True Resource Reference oslc:ServiceProvider A link to the resource’s OSLC Service Provider (OSLC Core - Common).
    Prefixed Name Occurs Read-only Value-type Representation Range Description
    OSLC Performance Monitoring: Start of additional properties
    dcterms:date zero-or-one True dateTime n/a n/a The time at which the record was collected (Dublin Core). Performance Monitoring service providers MUST provide an explicit time zone facet value (Performance Monitoring). This requirement is necessary to avoid differences in interpretation between servers and clients in different time zones; it is functionally equivalent to using the dateTimeStamp datatype from XML Schema 1.1, but avoids any side effects on SPARQL queries.
    ems:observes one-or-many True Resource Reference n/a Something observed and measured about a resource.
    dcterms:isPartOf zero-or-one True Resource Reference n/a A related resource in which the described resource is physically or logically included (Dublin Core).

    Resource: ems:Measure

    The OSLC Estimation and Measurement domain defines ems:Measure. This specification extends it with the properties below.

    Measure Properties

    Prefixed Name Occurs Read-only Value-type Representation Range Description
    OSLC Performance Monitoring: Start of additional properties
    pm:metricQualifier zero-or-many True Resource Either n/a Adds whatever additional qualifiers are needed on a metric to satisfy a scenario

    Metric Qualifier Values OSLC Performance Monitoring service providers can identify metricQualifiers using terms in the OSLC Performance Monitoring vocabulary or in other vocabularies, for example in the service provider’s own vocabulary. Examples of metric qualifiers can be found in OSLC Performance Monitoring 2.0 Appendix A: Samples.

    Performance Monitoring Metrics

    Performance Monitoring metrics are metrics that can be measured on a resource and give an indication of its performance, availability, utilization, or capacity. The Performance Monitoring metric classes are subclasses of ems:Metric.

    Table of Performance Metric Standard URIs
    URI Description
    http://open-services.net/ns/perfmon#ResourceUsed How much of a resource is currently consumed
    http://open-services.net/ns/perfmon#Request A request on a resource, originating from an end user or a system component
    http://open-services.net/ns/perfmon#ResourceExhausted Amount of time for which a resource has been exhausted
    http://open-services.net/ns/perfmon#ResourceAvailable How much resource is available out of the total
    http://open-services.net/ns/perfmon#ResponseTime Time it takes for a response to be returned to a request

    Examples:

    <!– language: lang-xml –>

    <rdf:Description rdf:about="http://example.org/rec001">
    <rdf:type rdf:resource="http://open-services.net/ns/ems#Measure"/>
    <dcterms:title>
        Virtual Memory Utilization
    </dcterms:title>
    <ems:metric rdf:resource="http://open-services.net/ns/perfmon#ResourceUsage"/>
    <ems:numericValue rdf:datatype="http://www.w3.org/2001/XMLSchema#double">
        50
    </ems:numericValue>
    <pm:metricQualifier rdf:resource="http://open-services.net/ns/perfmon#virtualmemory"/>
    <ems:unitOfMeasure rdf:resource="http://dbpedia.org/Percentage"/>
</rdf:Description>

<rdf:Description rdf:about="http://example.org/rec001">
    <rdf:type rdf:resource="http://open-services.net/ns/ems#Measure"/>
    <dcterms:title>
        Average Login Request Failure
    </dcterms:title>
    <ems:metric rdf:resource="http://open-services.net/ns/perfmon#Rate"/>
    <ems:numericValue rdf:datatype="http://www.w3.org/2001/XMLSchema#double">
        10
    </ems:numericValue>
    <ems:unitOfMeasure rdf:resource="http://qudt.org/vocab/unit#PerSecond"/>
</rdf:Description>

    Resource Properties

    In addition to resource definitions, this specification defines properties below that can occur in any RDF resource. In the scenarios currently addressed, they are most commonly used with resources of types such as the following, but this list is exemplary, not limiting: crtv:Process, crtv:StorageVolume, crtv:ComputerSystem, crtv:SoftwareServer, crtv:Database, crtv:SoftwareModule, crtv:ResourcePool, foaf:Agent. Not all properties will be semantically sensible with all resource types.

    Prefixed Name Occurs Read-only Value-type Representation Range Description
    pm:process zero-or-many True Resource Reference n/a A process running, for example, in a computer system. Typically refers to a resource with type crtv:ComputerSystem, but it may refer to other resource types.
    pm:disk zero-or-many True Resource Reference n/a A disk attached, for example, to a computer system. Typically refers to a resource with type crtv:ComputerSystem, but it may refer to other resource types.
    pm:monitoringAgent zero-or-many True Resource Reference n/a Software that monitors a resource’s availability, performance, capacity, or utilization. Typically refers to a resource with type foaf:Agent, but it may refer to other resource types.
    pm:mobilityEnabled zero-or-one True Literal boolean n/a An indication about whether the resource can move about dynamically.
    pm:tableReorganizationNeeded zero-or-one True Literal boolean n/a Indicates whether a database’s tables need to be reorganized.
    pm:availabilityStatus zero-or-many True Resource Reference n/a An indication of availability. If any value is present, then at least one of them MUST be from the list of URIs defined below. Additional values MAY be present from other namespaces, e.g. to provide more detailed product-specific status. All values present MUST be semantically compatible.

    Availability Status properties

    Question to WG: which is right, “reference” (not Either) in the table above, or “inline is valid too” in the paragraph below.

    OSLC Performance Monitoring service providers can identify the availabilityStatus using references to property values in the OSLC Performance Monitoring vocabulary or to property values that are not in the Performance Monitoring vocabulary (i.e. in the service provider’s own vocabulary). It is expected that the availabilityStatus values will be URI references to property values, but inline resources defining the availabilityStatus property values are also valid. Performance Monitoring service providers MUST use at least one availabilityStatus (Performance Monitoring Record) defined in the OSLC Performance Monitoring vocabulary in addition to any availabilityStatus values not in the Performance Monitoring vocabulary.

    The additional property values for pm:availabilityStatus are:

    URI Description
    http://open-services.net/ns/perfmon#NotRunning Not running in its host environment
    http://open-services.net/ns/perfmon#Running Running in its host environment
    http://open-services.net/ns/perfmon#Unknown Unknown

    Performance Monitoring Service Provider Capabilities

    Service Discovery and Description

    Resource Shapes

    Performance Monitoring service providers MAY support Resource Shapes as defined in OSLC Core Specification Appendix A

    Service Provider Resource

    Performance Monitoring service providers MUST provide a Service Provider Resource that can be retrieved at a implementation dependent URI.

    Performance Monitoring service providers MAY provide a Service Provider Catalog Resource that can be retrieved at a implementation dependent URI.

    Performance Monitoring service providers MUST provide a oslc:serviceProvider property for their defined resources that will be the URI to a Service Provider Resource.

    Creation Factories

    If an OSLC Performance Monitoring service provider supports the creation of resources, there MUST be at least one Creation Factory entry in its Services definition.

    See the HTTP Method support table for further clarification on support for HTTP methods and media types for each OSLC Performance Monitoring resource.

    Query Capabilities

    There SHOULD be at least one Query Capability entry in the Services definition.

    The Query Capability MUST at least support these parameters:

    • oslc:where
    • oslc:select

    If shape information is NOT present with the Query Capability, service providers SHOULD use the default properties defined in OSLC Core RDF/XML Examples to contain the result.

    Delegated UIs

    OSLC Performance Monitoring service providers support the selection and creation of Performance Monitoring resources as defined by Delegated UIs in OSLC Core.

    Performance Monitoring providers support requirements for delegated UIs as follows:

    Performance Monitoring Resource Selection Creation
    PerformanceMonitoringRecord SHOULD MAY

    Service Provider HTTP Method Support

    Support for all HTTP methods in the compliance 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 N/A
    PUT MAY MAY MAY N/A N/A
    POST MAY MAY MAY N/A N/A
    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

    In addition to making a Performance Monitoring record a class type for a monitored resource, providers may also choose to either make a Performance Monitoring Record a predicate of the monitored resource subject or make the monitored resource a predicate of a Performance Monitoring record instance. If the Performance Monitoring record is a predicate, it MUST be of type http://open-services.net/ns/perfmon#PerformanceMonitoringRecord.

    Appendix A: Samples

    (this section is informative)

    See OSLC Performance Monitoring 2.0 Appendix A: Samples

    Appendix B: Resource Shapes

    (this section is informative)

    See OSLC Performance Monitoring 2.0 Appendix B: Resource Shapes

    Appendix C: Notices and References

    Contributors

    Reporting Issues on the Specification

    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.

    Authors and Contact Information

    Intellectual Property Covenant

    The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant and/or Patent License for implementations of the Performance Monitoring 2.0 Specification, as described in the open-services.net Terms of Use.

    References