This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.
TWiki> Main Web>PerformanceMonitoringHome>PmSpecificationV2 (revision 17)
OSLC_logo.png

Open Services for Lifecycle Collaboration
Performance Monitoring Specification Version 2.0

Status: 2.0 Draft Specification - 2 August 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 PreviousVersion
  • N/A
Authors

Contributors

Table of Contents

License

88x31.png
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 operational stage 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 don't represent a complete setup of operations on resources or resource types. The resource formats and operations may not match exactly 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 PmScenarios? 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 Resource - A resource managed by a Performance Monitoring service provider. The types of resources defined by this specification are ComputerSystem,
!SoftwareServer, DatabaseServer, Database, SoftwareModule, Process, StorageVolume.

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 MUST Core OSLC service providers MUST 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 capabilities, the 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.

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 an 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 Recommendation where it occurs informatively.

Resource Definitions

The Performance Monitoring resource properties are not limited to the ones defined in this specification; service providers may provide additional properties. 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 in any OSLC domain (including Performance Monitoring).

The diagram below shows the relationships between Performance Monitoring Resources. We need to draft resource definition(s) before more editing.

pm_domain3.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 OSLC Core Specification.

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 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 exactly-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-many True Resource Reference oslc:ServiceProvider A link to the resource's OSLC Service Provider (OSLC Core - Common).

Prefixed Name Occurs Read-only Value-type Represen-tation Range Description
OSLC Performance Monitoring: Start of additional properties
pm:collectedAt exactly one True DateTime? n/a n/a The time at which the record was collected at the target resource
pm:topProcessesforCPUutil zero-or-one True Resource Reference rdfs:Seq The top processes in terms of CPU utilization
pm:topProcessesforVirtMemUtil zero-or-one True Resource Reference rdfs:Seq The top processes in terms of virtual memory utilization
pm:topProcessesforRealMemUtil zero-or-one True Resource Reference rdfs:Seq The top processes in terms of real memory utilization
pm:monitoringAgent zero-or-many True Resource Reference foaf:Agent An agent that performs monitoring of availability, performance, capacity, or utilization of a resource
ems:observes zero-or-many True Resource Reference   Something observed and measured about a resource

Resource: Process

Process 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 (<a target="_blank" href="#RdfXmlSyntax">RDF</a>).
dcterms:title exactly-one unspecified XMLLiteral n/a n/a A name given to the resource (reference: <a target="_blank" href="#DcTerms">Dublin Core</a>). 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 (<a target="_blank" href="#OSLCCore">OSLC Core</a> - Common).
dcterms:description zero-or-one unspecified XMLLiteral n/a n/a An account of the resource (<a target="_blank" href="#DcTerms">Dublin Core</a>). 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 (<a target="_blank" href="#OSLCCore">OSLC Core</a> - Common).
dcterms:identifier zero-or-one True String n/a n/a An unambiguous reference to the resource within a given context (<a target="_blank" href="#DcTerms">Dublin Core</a>). 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 (<a target="_blank" href="#OSLCCore">OSLC Core</a> - Common).
dcterms:created zero-or-one True DateTime n/a n/a Timestamp of resource creation (<a target="_blank" href="#DcTerms">Dublin Core</a>)
dcterms:modified zero-or-one True DateTime n/a n/a Date on which the resource was changed (<a target="_blank" href="#DcTerms">Dublin Core</a>). Timestamp of latest resource modification (<a target="_blank" href="#OSLCCore">OSLC Core</a> - Common).
oslc:serviceProvider zero-or-many True Resource Reference oslc:ServiceProvider A link to the resource's OSLC Service Provider (<a target="_blank" href="#OSLCCore">OSLC Core</a> - Common).

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Performance Monitoring: Start of additional properties
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs (<a target="_blank" href="#RdfXmlSyntax">RDF</a>).
ems:observes zero-or-many True Resourcel Reference n/a Typically refers to a resource of type ems:Measure

Resource: crtv:StorageVolume

StorageVolume? Properties

Prefixed Name Occurs Read-only Value-type Representation Range Description
OSLC Performance Monitoring: Start of additional properties
rdf:type zero-or-many unspecified Resource Reference n/a The resource type URIs (<a target="_blank" href="#RdfXmlSyntax">RDF</a>).
ems:observes zero-or-many True Resource Either n/a Typically refers to a resource of type ems:Measure

Performance Monitoring Metrics

Performance Monitoring metrics are metrics that can be measured on a resource and give an indication of the performance, availability,

utilization, or capacity. The Performance Monitoring metrics are subclasses of ems:Metric.

The URI for the ems: prefix is <http://open-services.net/ns/ems/metric#>

Table of Performance Metric Standard URIs

URI Description
metric:FreeMegabytes Number of megabytes free on a logical disk.
metric:VirtualMemoryUtilization Percentage of virtual memory used by a process as a percentage of all available virtual memory.
metric:RealMemoryUtilization Percentage of real memory used by a process as a percentage of all available real memory.
metric:CPUUtilization Percentage of CPU time used by a process as a percentage of total available CPU time.
metric:ResponseTime Response time.
metric:NumFailedSqlStmts The number of failed SQL statements returned from a database to a client
metric:HeapUsage The amount of memory heap used by an application
metric:TableReorgNeeded Indicates whether a database's tables need to be reorganized
metric:PctBufferPoolUsed Percentage of buffer pool used by a database server
metric:OperationalStatus The operational status of a resource
metric:GarbageCollectionCount The number of times GC has been run during the lifetime of an application
metric:AvailabilityStatus  
metric:PercentageFreeMemoryAfterGC Percentage of free memory on application JVM's heap following a garbage collection. Indicator of memory leak or misconfiguration.
metric:PercentageTimeThreadPoolMaxed Represents the proportion of time an application's thread pool has been totally consumed since application start time. Indicator of thread pool contention and slowing response times
metric:PercentageTimeJCAThreadPoolMaxed  
metric:PercentageTimeDBThreadPoolMaxed  
metric:AverageTimetoGetJMSMessage  
metric:AverageResponseTime  

Performance Monitoring Metrics Units of Measure

The Performance Monitoring metric units of measure are a subclass of ems:UnitOfMeasure.

The URI for the ems: prefix is http://open-services.net/ns/ems/unit#.

Table of pm:Unit of Measure Standard URIs for Performance Metrics

URI Description
unit:Megabytes qudt:Capacity
unit:Percentage dbpedia:Percentage

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 Factories 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 MUST be at least one Query Capabilities 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.

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.

Appendix A: Samples

(this section is informative)

See PmSpecificationV2Samples

Appendix B: Resource Shapes

(this section is informative)

See PmSpecificationV2Shapes?

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

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

Attachments Attachments
Topic attachments
I Attachment Action Size Date Who Comment
jpgJPG Monitoring_Resources.JPG manage 13.7 K 20 Jun 2012 - 16:47 JulianneBielski Monitoring Resources
jpgJPG pm_domain.JPG manage 17.2 K 01 Aug 2012 - 18:53 JulianneBielski  
jpgJPG pm_domain2.JPG manage 17.9 K 02 Aug 2012 - 17:22 JulianneBielski Performance Monitoring Record resource graph
jpgJPG pm_domain3.JPG manage 18.1 K 29 Aug 2012 - 21:02 JulianneBielski  
Edit | Attach | Print version | History: r20 < r19 < r18 < r17 < r16 | Backlinks | Raw View | Raw edit | More topic actions...
Topic revision: r17 - 29 Aug 2012 - 21:02:53 - JulianneBielski
Main.PmSpecificationV2 moved from Main.PmSpecificationV1 on 08 May 2012 - 16:50 by JohnArwe - put it back
 
This site is powered by the TWiki collaboration platform Copyright � by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback