History   View   Links to this page Revision from: 2012 September 25 | 02:55 pm
This is the revision from 2012 September 25 at 02:55 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 - 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

Contents

  • 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 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 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 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 MAY 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 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_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 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-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 Representation Range Description
    OSLC Performance Monitoring: Start of additional properties
    dcterms:date exactly one True dateTimeStamp n/a n/a The time at which the record was collected
    pm:process zero-or-many True Resource Reference n/a A process running, for example, in a computer system, consuming resources
    pm:disk zero-or-many True Resource Reference n/a A disk attached, for example, to a computer system
    pm:availabilityStatus zero-or-one True Resource Reference n/a An indication of availability
    pm:monitoringAgent zero-or-many True Resource Reference n/a Software that monitors a resource’s availability, performance, capacity, or utilization
    ems:observes zero-or-many True Resource Reference n/a Something observed and measured about a resource

    Availability Status properties 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:

    • http://open-services.net/ns/perfmon#NotRunning - used to indicate that the resource is not running in its host environment
    • http://open-services.net/ns/perfmon#Running - used to indicate that the resource is running in its host environment
    • http://open-services.net/ns/perfmon#Unknown - used to indicate that the availability status of the resource is unknown

    Resource: crtv:Process

    Process Properties

    Prefixed Name Occurs Read-only Value-type Representation Range Description
    OSLC Performance Monitoring: Start of additional properties
    ems:observes zero-or-many True Resource 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
    ems:observes zero-or-many True Resource Either n/a Typically refers to a resource of type ems:Measure

    Resource: foaf:Agent

    Agent Properties

    • Name: Agent
    • Description: An agent (eg. person, group, software or physical artifact).
    • Type URI http://xmlns.com/foaf/0.1/Agent
    • Note that measurements can be observed about an agent
    Prefixed Name Occurs Read-only Value-type Representation Range Description
    OSLC Performance Monitoring: Start of additional properties
    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 metric classes are subclasses of ems:Metric.

    Table of Performance Metric Standard URIs
    URI Description
    http://open-services.net/ns/perfmon#PercentageSpaceUsed Number of megabytes used on a logical disk divided by total number of megabytes.
    http://open-services.net/ns/perfmon#VirtualMemoryUtilization Percentage of virtual memory in use by a computer system or process as a percentage of all available virtual memory.
    http://open-services.net/ns/perfmon#RealMemoryUtilization Percentage of real memory in use by a computer system or process as a percentage of all available real memory.
    http://open-services.net/ns/perfmon#CPUUtilization Percentage of CPU time used by a computer system or process as a percentage of total available CPU time.
    http://open-services.net/ns/perfmon#ResponseTime Time it takes for a response to be returned to a request
    http://open-services.net/ns/perfmon#NumFailedSqlStmts The number of failed SQL statements returned from a database to a client
    http://open-services.net/ns/perfmon#HeapUsage The amount of memory heap used by an application
    http://open-services.net/ns/perfmon#TableReorgNeeded Indicates whether a database’s tables need to be reorganized
    http://open-services.net/ns/perfmon#PctBufferPoolUsed Percentage of buffer pool used by a database server
    http://open-services.net/ns/perfmon#GarbageCollectionCount The number of times GC has been run during the lifetime of an application
    http://open-services.net/ns/perfmon#PercentageFreeMemoryAfterGC Percentage of free memory on application JVM’s heap following a garbage collection. Indicator of memory leak or misconfiguration.
    http://open-services.net/ns/perfmon#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
    http://open-services.net/ns/perfmon#PercentageTimeJCAThreadPoolMaxed Represents the proportion of time a JCA application’s thread pool has been totally consumed since application start time. Indicator of thread pool contention and slowing response times
    http://open-services.net/ns/perfmon#PercentageTimeDBThreadPoolMaxed Represents the proportion of time a database application’s thread pool has been totally consumed since application start time. Indicator of thread pool contention and slowing response times
    http://open-services.net/ns/perfmon#VMCPUPercentReady The amount of time a Virtual Machine’s CPU has spent in the ready state. A relatively high number indicates under utilization
    http://open-services.net/ns/perfmon#TotalCPUAvailable The amount of MHz available to a physical server
    http://open-services.net/ns/perfmon#OverCommmittedDiskUtilization The percentage of the total capacity of a storage volume that has been overcommitted.

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

    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