From 740964bf8ecaaa1f2d0051ef89c528f14316ba12 Mon Sep 17 00:00:00 2001 From: Roland Hochmuth Date: Fri, 18 Jul 2014 22:25:45 -0600 Subject: [PATCH] Changed document names to Monasca. Removed overivew. Updated README Change-Id: Ibbbe137da6a0abc197a57a44ba6f5ca328a2aa69 --- README.md | 10 +- docs/mon-api-overview.md | 134 ------------------ docs/{mon-api-spec.md => monasca-api-spec.md} | 0 3 files changed, 2 insertions(+), 142 deletions(-) delete mode 100644 docs/mon-api-overview.md rename docs/{mon-api-spec.md => monasca-api-spec.md} (100%) diff --git a/README.md b/README.md index 7fe2fa76f..bca1299bb 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Overview -`mon-api` is a RESTful API server that is designed with a layered architecture [layered architecture](http://en.wikipedia.org/wiki/Multilayered_architecture). +`monasca-api` is a RESTful API server that is designed with a layered architecture [layered architecture](http://en.wikipedia.org/wiki/Multilayered_architecture). ## Build @@ -35,13 +35,7 @@ Requests flow through the following architectural layers from top to bottom: ## Documentation -There are several forms of documentation for the Monitoring API. - -* Overview: [/docs/mon-api-overview.md](/docs/mon-api-overview.md). This describes some of the concepts in the Monitoring API. - -* API Specification: [/docs/mon-api-spec.md](/docs/mon-api-spec.md). This is the RESTful API specification. - -* swagger-ui: When running mon-api the API docs along with the API test interface can be accessed at, [http://localhost:8080/swagger-ui/](http://localhost:8080/swagger-ui/). Note: the trailing "/" is necessary for the Swagger UI to work properly. Currently, this is the best way to review the specification. +* API Specification: [/docs/monasca-api-spec.md](/docs/monasca-api-spec.md). # License diff --git a/docs/mon-api-overview.md b/docs/mon-api-overview.md deleted file mode 100644 index 4978dd605..000000000 --- a/docs/mon-api-overview.md +++ /dev/null @@ -1,134 +0,0 @@ - -# Monitoring API Overview - -## 1. Overview - -This document provides an overview of the Monitoring API. - -## 2. Architecture View - -Monitoring as a Service provides APIs for the following: - -* Posting and querying metrics. -* Querying statistics about metrics. -* Creating notification methods. -* Creating and updating alarms. -* Querying the state of alarms and the alrm state history. - -### 2.1 Overview - -The Monitoring API provides a RESTful JSON interface for interacting with and managing monitoring related resources. - -The API supports a number of resources. These include: - -+ Versions - Provides information about the supported Monitoring API versions. - -+ Metrics: The metric resource allows the storage of metrics. - -+ Measurements: Operations for accessing measurements of metrics. - -+ Statistics: Operations for accessing statistics about metrics. - -+ Alarms: The alarm resource identifies a one or more metrics scoped by name and dimensions, which should trigger a set of actions when the value of a threshold is exceeded. - -+ Notification Methods: The notification method resource represents a method, such as email, which can be associated with an alarm via an action. When an alarm is triggered notification methods associated with the alarm are triggered. - -#### 2.1.1 High Level and Usage - -Before using the API, you must first get a valid auth token. All API operations require auth token specified in the header of the http request. - -##### 2.1.1.1 Sending metrics - -##### 2.1.1.2 Creating an alarm - -#### 2.1.2 Name, Dimensions, and Metrics - -##### 2.1.2.1 Name - -Defines the name of a metric. - -##### 2.1.2.2 Dimensions - -Additional data associated with a metric that is used to identiy it. - -Dimensions may only use the characters from: a-z A-Z 0-9 . \_. The dimension value may only use the characters from: a-z A-Z 0-9 . - \_. - -### 2.2 Alarm Expressions - -The alarm expression syntax allows the creation of simple to complex alarms to handle a wide variety of needs. Alarm expressions are evaluated every 60 seconds. - -An alarm expression is a boolean equation which if it evaluates to true with the incoming metrics, will then trigger a notification to be sent. - -Syntax: - -At the highest level, you have an expression, which is made up of one or more subexpressions, joined by boolean logic. Parenthesis can be used for separators. In a BNF style format: - - expression - : subexpression - | '(' expression ')' - | expression logical_operator expression - -The logical_operators are: 'and' (also &&), 'or' (also ||). - -Each subexpression is made up of several parts with a couple of options: - - subexpression - : metric relational_operator threshold_value - | function '(' metric ',' period ')' relational_operator threshold_value ('times' periods)? - -The relational_operators are: 'lt' (also <), 'gt' (also >), 'lte' (also <=), 'gte' (also >=). - -Threshold values are always in the same units as the metric that they are being compared to. - -The first subexpression shows a direct comparison of a metric to a threshold_value, done every 60 seconds. - - Example: - - cpu_perc:{hostname=host.domain.com} > 95 - -The second subexpression shows a function operation done on all collected metrics within a specific period and compared to a threshold_value, then triggered if it happens periods number of times. - - Example: - - avg(cpu_perc:{hostname=host.domain.com},85) > 90 times 3 - -Note that period is the number of seconds for the measurement to be done on. They can only be in a multiple of 60. Periods is how many times in a row that this expression must be true before triggering the alarm. Both period and periods are optional and default to 60 and 1 respectively. - -Functions work on all metric measurements during the period time frame. - -+ min (returns the minimum of all the values) -+ max (returns the maximum of all the values) -+ sum (returns the sum of all the values) -+ count (returns the number of metric observations) -+ avg (returns the average of all the values) - -The metric is a complex identifier that says the name and optional dimensions. - - metric - : name ':' '{' dimensions '}')? - - Examples: - - cpu_perc:{hostname=host.domain.com} - -Larger example: - - (avg(cpu_perc:{hostname=hostname.domain.com}) > 90 ) or ( avg(disk_read_ops:{hostname=hostname.domain.com,device=vda,120) > 1000 times 3) - -# License - -Copyright (c) 2014 Hewlett-Packard Development Company, L.P. - -Licensed under the Apache License, Version 2.0 (the "License"); -you may not use this file except in compliance with the License. -You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - -Unless required by applicable law or agreed to in writing, software -distributed under the License is distributed on an "AS IS" BASIS, -WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or -implied. -See the License for the specific language governing permissions and -limitations under the License. - \ No newline at end of file diff --git a/docs/mon-api-spec.md b/docs/monasca-api-spec.md similarity index 100% rename from docs/mon-api-spec.md rename to docs/monasca-api-spec.md