Monitoring APIリファレンス

本マニュアルでは、 Cloudn MonitoringのAPIご利用方法に関してご説明いたします。
右上の “索引” や、右のバーにある検索にて検索が可能です。

1. Cloudn APIについて

Cloudn では、各プロダクトごとにAPIを提供しております。
APIを使用することで、コントロールパネルを介さずにお客様のプログラムから直接リソースを操作することが可能です。

以下、 Cloudn MonitoringのAPIについてご説明いたします。

1.1. Cloudn APIについて

Cloudn では、各プロダクトごとにAPIを提供しております。
APIを使用することで、コントロールパネルを介さずにお客様のプログラムから直接リソースを操作することが可能です。

ご利用にあたっては下記の通りの情報/前提知識が必要となります。

API共通情報

以下、3つの情報がAPIを利用するにあたり必要となります。

  • アクセスキーID
  • 秘密鍵
  • APIエンドポイント

以下の2つを Cloudn ポータルよりログインし、入手します。

  • アクセスキーID

    • APIへのアクセスにおいて、お客様個人のIDを識別するためのキーです。
    • お客様固有のものとなります
  • 秘密鍵

    • APIへのアクセスにおいて、電子署名に利用される鍵です。
    • お客様固有のものとなります

APIエンドポイントについては、各 Cloudn サービスごとに異なります。 下記を参照してください。

アクセスキーID・秘密鍵入手方法

Cloudn ポータルへログイン

下記URLより、パスワード/IDでログインをします。

https://portal.cloudn-service.com/comgi/login

画面下部”APIアクセスキー・秘密鍵管理”をクリック

画面下部に存在する”APIアクセスキー・秘密鍵管理”をクリックします。

ポータルから秘密鍵へのリンク

Cloudn ポータル最下段、アクセスキーID・秘密鍵管理画面へのリンク

Query API->アクセスキーID・秘密鍵をコピーして利用

アクセスキーID・秘密鍵をコピーして利用します。

アクセスキーID・秘密鍵管理画面キャプチャ

アクセスキーID・秘密鍵管理画面

1.2. API情報 ( Cloudn Monitoring)

エンドポイントについて

本サービスにて提供しているAPI Server (End Point)のURIは下記となります。

End Point一覧
リージョン タイプ URI
東日本リージョン FLATタイプ https://mon-api.jp-e1.cloudn-service.com/
東日本リージョン VPCタイプ OpenNW https://mon-vpcopennw-api.jp-e1.cloudn-service.com/
西日本リージョン FLATタイプ https://mon-api.jp-w1.cloudn-service.com/
米国リージョン FLATタイプ https://mon-api.us-e1.cloudn-service.com/

注釈

API リクエスト・レスポンスは “HTTPS” にて行います。 HTTPはサポートされていません。

[参考]前提知識

Cloudn Monitoringについて

Cloudn Monitoringの操作・機能については操作マニュアルを参照してください。

クラウド・エヌ インフォメーションポータル - マニュアル

APIの利用方法について

APIを利用するには、クライアントと呼ばれるツールを利用する方法、
もしくはお客様プログラム上において仕様にしたがってAPIを利用する方法が一般的です。

以下、APIクライアントを利用した利用例・プログラム上でAPIを利用するために必要なリクエストの作成例を示します。

注釈

APIのご利用にあたっては、ご利用前に、 Cloudn ポータルより サービスを「利用中」の状態にする必要があります。

1.3. APIクライアントの利用

概要

Cloudn Monitoringでは、Amazon Web Services CloudWatch (以下CloudWatch) 互換APIを提供しており、
各種AWS対応APIツールを利用することが可能です。

APIクライアントとして、下記に示すツールを用いた例をご説明します。
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
# coding: utf-8

require "cgi"
require "time"
require "digest/hmac"
require "base64"
require "net/http"
require "net/https"
require 'pp'


def cgi_escape(key, value)
  [CGI.escape(key.to_s), CGI.escape(value.to_s)].join("=")
end

end_point = "Please Enter the Endpoint"
access_identifier = "Please Enter your API Access Key"
secret_identifier = "Please enter your Secret Key"

if ARGV.size < 1 then
  puts "usage :./kick_api.rb Action=... parameter=... parameter=..."
  exit 1
end

params = {
  "AWSAccessKeyId" => access_identifier,
  "SignatureMethod" => "HmacSHA256",
  "SignatureVersion" => 2,
  "Version" => "2012-04-23",
  "Timestamp" => Time.now.iso8601
}

ARGV.each do |arg|
  key, value = arg.split("=")
  params[key] = value
end

canonical_querystring = params.sort.collect { |key, value| cgi_escape(key, value) }.join("&")

  string_to_sign ="GET
#{end_point}
/
#{canonical_querystring}"
pp string_to_sign
hmac = Digest::HMAC.new(secret_identifier, Digest::SHA256)
hmac.update(string_to_sign)
signature = Base64.encode64(hmac.digest).chomp

params["Signature"] = signature
querystring = params.collect { |key, value| cgi_escape(key, value) }.join("&")


get = Net::HTTP::Get.new("/?#{querystring}")
https = Net::HTTP.new(end_point, 443)

https.use_ssl = true
https.verify_mode = OpenSSL::SSL::VERIFY_PEER
response = nil
https.start{ |w|
  response = w.request(get)
p response.header
puts response.body

}
pp response

KickAPIの利用

前提条件
  • Ruby1.9.2p0 以上での動作
  • 標準モジュールのみで動作します
KickAPIのダウンロード
上記のリンクよりKickAPIをダウンロードします。
次に、秘密鍵・APIアクセスキーを設定します。
エディタなどでダウンロードしたKickAPIを開き、編集します。

以下、APIアクセスキーを”WNZ9AV783OKRC8C5DL4Q”, 秘密鍵を”Q5j2kslNp5L7mnpJGZwS9AdkJla9V08vZ0JalhGl”、
および米国リージョン・FLATタイプを利用すると仮定し設定します。
vim kick_api.rb

下記の変更を行います。

  • 上記コードでハイライトされた部分を編集します

    • “Please Enter the Endpoint” へ 対象リージョン・タイプのエンドポイントホスト部
    • “Please Enter your API Access Key” へ APIアクセスキーの “WNZ9AV783OKRC8C5DL4Q” を入力
    • “Please Enter your Secret Key” へ 秘密鍵の “Q5j2kslNp5L7mnpJGZwS9AdkJla9V08vZ0JalhGl” を入力

例の場合、変更した点は以下の通りです。

@@ -16,8 +16,8 @@

-end_point = "Please Enter the Endpoint"
-access_identifier = "Please Enter your API Access Key"
-secret_identifier = "Please Enter your Secret Key"
+end_point = "mon-api.us-e1.cloudn-service.com"
+access_identifier = "WNZ9AV783OKRC8C5DL4Q"
+secret_identifier = "Q5j2kslNp5L7mnpJGZwS9AdkJla9V08vZ0JalhGl"

参考

API認証情報については以下を参照してください

エンドポイントについては以下を参照してください

上記ファイルを保存します。

KickAPIの利用
シェルにて下記のように実行します
下記のコマンドで、現在あるメトリクス一覧を取得するAPI ( ListMetrics - メトリクス一覧表示 )
を利用可能です。
$ruby kick_api.rb Action=ListMetrics

コマンド引数は以下の通りです。

  • “Action=”

    • APIのアクション名を指定します。この場合、 “ListMetrics” というActionをコールしています
  • その他パラメータ (例: “MetricName=autoscalinggroup1”)

    • API固有のパラメータを上記の形式で入力します。

上記の様に、クライアントを利用することでAPIの実行に必要な署名の作成といった作業が簡略化されます。

1.4. リクエスト作成方法

APIクライアントなどを使用せずにAPIリクエストを利用する方法を示します。

APIリクエスト形式

Cloudn Monitoringサービスのリクエストは、Query API形式となります。
例えば、本サービスによって管理するメトリクスの一覧を取得する、ListMetrics API リクエストは、以下のようになります。
https://mon-api.jp-e1.cloudn-service.com/?Action=ListMetrics&Version=2010-08-01&SignatureVersion=2&SignatureMethod=HmacSHA256&Timestamp=2013-02-01T05%3A54%3A53.578Z&AWSAccessKeyId=<APIKey>&Signature=<Signature>
上記では例として Monitoring でサポートされるメトリクス情報を取得するリクエストを記載しています。
APIリクエストは、主に命令の種類とそのオプションの値を含み、下記の要素で構成されます。
https://mon-api.jp-e1.cloudn-service.com/
Action=ListMetrics
Version=2010-08-01
SignatureVersion=2
SignatureMethod=HmacSHA256
Timestamp=2013-02-01T05%3A54%3A53.578Z
AWSAccessKeyId=<APIKey>
Signature=<Signature>

構成要素は以下の通りです。

  • 1行目: APIサーバ/エンドポイントURL
  • 2行目: Monitoringへのコマンド (Action)
  • 3行目: コマンドに渡すオプションとその値
  • 4-8行目: 署名情報

リクエスト本文に署名を付ける手順を説明します。

署名

APIリクエストには、リクエスト内容を保証するために、署名(Signature)を加えます。
署名は、リクエスト本文(1の要素を元に作成)を元に、ユーザのSECRETKEYとHMAC-SHA-256ハッシュアルゴリズムを組み合わせて作成します。
予めサービス利用に必要な公開鍵と秘密鍵を配布しています。
サービス上ではこれをAPIアクセスキーと秘密鍵と呼びます。
APIアクセスキーと秘密鍵については アクセスキーID・秘密鍵入手方法 を参照してください。
署名の作成手順
以下では署名とHTTPリクエストの生成方法について解説します。


リクエストのコマンドパラメータを作成します。
メトリクス一覧情報を取得するリクエスト作成を例に、コマンドパラメータを記載します。
コマンド, パラメータ
Action ListMetrics
Version 8/1/10
SignatureVersion 2
SignatureMethod HmacSHA256
Timestamp 2014-08-14T11:11:15+09:00
AWSAccessKeyId <APIKEY>

注釈

コマンド,およびパラメータは大文字小文字を区別します

注釈

Timestamp key は、リクエスト発行時の時刻をiso8601形式で作成します。

  • (例): 2014-08-14T11:10:03+09:00
    • マイクロ秒は必要ありません。
    • 日付時刻の間のdelimiterは “T” です
    • オフセットを(+-)00:00の形式で付与する必要があります

次に署名を作成します。

作成したコマンドパラメータを、ASCIIの昇順で並べ替え、値をURLエンコードします。
本操作は署名の作成のために行うもので、リクエスト本文自体が並べ替えられるわけではありません。
(リクエスト本文はソートされている必要はありません)
コマンド, パラメータ
AWSAccessKeyId <APIKEY>
Action ListMetrics
SignatureMethod HmacSHA256
SignatureVersion 2
Timestamp 2014-08-14T11%3A11%3A15%2B09%3A00
Version 8/1/10
上表の “コマンド, パラメータ” 行と “値” 行を、”=” にてつないだものを “&” で接続し、
HTTPリクエストの要素を添えて署名対象文字列(“data”)の作成します。

以下の文字列をここでは “data” とします:

GET
mon-api.jp-e1.cloudn-service.com
/
AWSAccessKeyId=<APIKey>&Action=ListMetrics&SignatureMethod=HmacSHA256&SignatureVersion=2&Timestamp=2013-01-30T18%3A09%3A45Z&Version=2010-08-01

注釈

“AWSAccessKeyId=〜”クエリまでは各要素を改行しますが、クエリ部分は改行せず1行で作成します

作成した文字列”data”に対して、HMAC-SHA256と秘密鍵から署名を生成し、 これをHTTPリクエストに含められるようにBase64でエンコードします。

  • HMAC-SHA256:

    • 暗号化形式です
    • OpenSSL等のライブラリの機能を利用し、作成します
    • (例:Rubyであればgemライブラリの ruby-hmac(0.4.0) など)
  • SECRETKEY:

    • 弊社から配布された物をご利用ください
  • HMACによる署名サンプル:

    • 5df60c66d6715d33c5b49af3428c0cbb84918a0baa96c29f3b32670a742bdc29
  • 署名サンプル:(Base64エンコード後)

    • NWRmNjBjNjZkNjcxNWQzM2M1YjQ5YWYzNDI4YzBjYmI4NDkxOGEwYmFhOTZjMjlmM2IzMjY3MGE3NDJiZGMyOQ==

注釈

署名内に改行が入らないようにご注意ください

署名(Signature)をリクエスト本文に付け加え、リクエスト文字列を作成します。
パラメータの値は予めURLエンコードしておきます。
コマンド、パラメータの記述を コマンド、パラメータ=値(valueはURLエンコード済)とし、各パラメータを&で繋ぎます。

なお、HTTPリクエストでは項目をソートする必要はありません。
Action=ListMetrics&SignatureMethod=HmacSHA256&SignatureVersion=2&AWSAccessKeyId=<APIKEY>&Version=2010-08-01&Timestamp=2013-01-30T18%3A09%3A45Z&Signature=NWRmNjBjNjZkNjcxNWQzM2M1YjQ5YWYzNDI4YzBjYmI4NDkxOGEwYmFhOTZjMjlmM2IzMjY3MGE3NDJiZGMyOQ%3D%3D%0D%0A
作成したリクエスト本文を元に、HTTPSでエンドポイントに対しGETリクエストを実行します。
エンドポイントは エンドポイントについて を参照してください。
GET /? Action=ListMetrics&SignatureMethod=HmacSHA256&SignatureVersion=2&AWSAccessKeyId=<APIKEY>&Version=2010-08-01&Timestamp=2013-01-30T18%3A09%3A45Z&Signature=NWRmNjBjNjZkNjcxNWQzM2M1YjQ5YWYzNDI4YzBjYmI4NDkxOGEwYmFhOTZjMjlmM2IzMjY3MGE3NDJiZGMyOQ%3D%3D%0D%0A

1.5. API仕様

APIに関する各種仕様です。

共通パラメータ仕様

Common Parameters
パラメーター名 説明 Required
Action 実行するAction(コマンド)です。 - Default : None - Type : String Yes
AuthParams 未サポート No
AWSAccessKeyId リクエストの認証に必要なAccess Key IDを指定します。 - Default : None - Type : String Yes
Expires 未サポート No
SecurityToken 未サポート No
Signature リクエストへの署名です。 署名を生成する方法については、 署名 を参照してください。 - Default : None - Type : String Yes
SignatureMethod リクエストへの署名のハッシュアルゴリズムです。 - Default : None - Valid Values : (HmacSHA256 | HmacSHA1) - Type : String Yes
SignatureVersion リクエストへの署名のバージョンです。 - Default : None - Valid Values : 2 - Type : String Yes
Timestamp リクエストを発出した日時です。 表記方法は「YYYY-MM-DDThh:mm:ssZ」で、ISO8601準拠です。 - Default : None - Type : String Yes
Version 使用するAPIバージョンです。 - Default : None - Valid Values : 2010-08-01 - Type : String Yes

Action用ARN

Monitoring で利用可能なAction用のARN (Amazon Resource Name) を示します。

アクション
メール通知 arn:cloudn:monitoring:jp-e1: <mailaddress> - [例]: arn:cloudn:monitoring:jp-e1:someone@example.com
オートスケーリングポリシー実行 オートスケーリングポリシー設定時に払い出されるARNを指定する。 詳しくは、AutoScaling API マニュアルを参照下さい

Namespace情報

本サービスにて利用可能なNamespaceとMetricsの関係は以下の通りです。

Namespace
Metrics
Cloudn/Compute
CPUUtilization
DiskReadOps
DiskWriteOps
DiskReadBytes
DiskWriteBytes
NetworkIn
NetworkOut
StatusCheckFailed_Instance
StatusCheckFailed_System
StatusCheckFailed
Cloudn/DataDisk
VolumeReadBytes
VolumeWriteBytes
VolumeReadOps
VolumeWriteOps
Cloudn/AutoScale
GroupMinSize
GroupMaxSize
GroupDesiredCapacity
GroupInServiceInstances
GroupPendingInstances
GroupTerminatingInstances
GroupTotalInstances
Cloudn/LBA
RequestCount
HealthyHostCount
UnHealthyHostCount
Cloudn/RDB
BinLogDiskUsage
CPUUtilization
DatabaseConnections
FreeableMemory
FreeStorageSpace
ReplicaLag
SwapUsage
ReadIOPS
WriteIOPS
ReadLatency
WriteLatency
ReadThroughput
WriteThroughput
ReplicaSQLStatus [1]
ReplicaIOStatus [1]

参考

各メトリクスの説明は Monitoring操作マニュアル を参照して下さい。

脚注

[1](1, 2) ReadReplicaインスタンスのみ有効です。

各種フォーマット

DateTime

日時で用いるフォーマットです。

  • YYYY-MM-DDThh:mm:ssZ

で指定します。 (ISO8601準拠)

Statistic

統計で指定する情報で、以下が指定可能です。

  • SampleCount

  • Average

    • 平均を表します
  • Sum

    • 合計を表します
  • Minimum

    • 一定期間中の最低値を表します
  • Maximum

    • 一定期間中の最大値を表します
Unit

単位として以下が指定可能です。

  • Seconds
  • Microseconds
  • Milliseconds
  • Bytes
  • Kilobytes
  • Megabytes
  • Gigabytes
  • Terabytes
  • Bits
  • Kilobits
  • Megabits
  • Gigabits
  • Terabits
  • Percent
  • Count
  • Bytes/Second
  • Kilobytes/Second
  • Megabytes/Second
  • Gigabytes/Second
  • Terabytes/Second
  • Bits/Second
  • Kilobits/Second
  • Megabits/Second
  • Gigabits/Second
  • Terabits/Second
  • Count/Second
  • None
HistoryItemType

アラーム履歴の種類は以下が指定可能です。

  • ConfigurationUpdate

    • アラーム設定のアップデート
  • StateUpdate

    • アラーム状態のアップデート
  • Action

    • アラームアクションの実行
ComparisonOperator
比較演算子の種類は以下が仕様可能です。
閾値が左辺にあるとした場合で説明します。
  • GreaterThanOrEqualToThreshold
    • “>=” を表します
  • GreaterThanThreshold
    • “>” を表します
  • LessThanThreshold
    • “<” を表します
  • LessThanOrEqualToThreshold
    • “<=” を表します

2. AmazonWebService CloudWatch互換API

AmazonWebService CloudWatch互換のAPIについて説明します。

2.1. メトリクス管理

メトリクスを管理するためのAPIについて説明します

GetMetricStatistics - メトリクス統計情報取得

概要

メトリックを指定して統計情報を取得する。

リクエスト
リクエストメソッド
  • GET
リクエストパラメータ
パラメーター名 説明 Required
Dimensions.member.N [1]
Dimensionを指定する。
DimensionはName-Value Pairで構成されるため、
Dimensions.member.N.NameとDimensions.member.N.Valueを指定する必要がある.
(N= 1, 2, 3, ….., 100)
- [例]: 下記の2つを同時に指定する
- Dimensions.member.1.Name=InstanceId
- Dimensions.member.1.Value=deadbeef-2929-dead-beef-cafe292983129
Yes
MetricName メトリック名を指定する。最大255文字まで指定が可能。 Yes
Namespace Namespaceを指定する Yes
Period 統計を適用してからの時間 (秒) Yes
Statistic.Member.N 統計手法を指定します。 指定フォーマットの詳細は Statistic Yes
Unit [1]
メトリックに対する計測単位。
指定フォーマットの詳細は Unit
No
EndTime
指定した日時までの統計情報を取得する。
指定フォーマットは DateTime
Yes
StartTime
指定した日時からの統計情報を取得する。
指定フォーマットは DateTime
Yes

参考

下記のAPIで、必要なパラメーターが取得可能です。

脚注

[1](1, 2) Amazon Web Servicesでは必須ではありませんが、本サービスでは必須パラメータとなります
レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
GetMetricStatisticsResponse レスポンスコンテナ ResponseMetadata, GetMetricStatisticsResult
ResponseMetadata メタデータのコンテナ RequestId
RequestId リクエストID  
GetMetricStatisticsResult 結果を各のするコンテナ Datapoints, Label
Datapoints 統計データを格納するコンテナ Timestamp, Average, Maximum, Minimum, SampleCount, Sum, Unit
Timestamp 統計データを取得した日時  
Average 平均値  
Maximum 最大値  
Minimum 最小値  
SampleCount 平均等の計算に用いたサンプリングの回数  
Sum 合計値  
Unit 単位を示す。  
Label 指定したメトリックの名前  
サンプルAPIコール&レスポンス
サンプルAPIコール
$ruby kick_api.rb Action=GetMetricStatistics \
 Statistics.member.1="Maximum" \
 StartTime="2014-08-18T11:23:22+0900" \
 Namespace="Cloudn/Compute" \
 Dimensions.member.1.Name="InstanceId" \
 Dimensions.member.1.Value="1e52dd2d-bb9d-41f2-a32b-782a7117c906" \
 Period="60" \
 EndTime="2014-08-18T11:28:22+0900" \
 Unit="Bytes" \
 MetricName="CPUUtilization"
サンプルAPIレスポンス
<GetMetricStatisticsResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <GetMetricStatisticsResult>
    <Datapoints/>
    <Label>CPUUtilization</Label>
  </GetMetricStatisticsResult>
  <ResponseMetadata>
    <RequestId>b2dc3c11-d115-8971-9245-3458d0910f85</RequestId>
  </ResponseMetadata>
</GetMetricStatisticsResponse>

ListMetrics - メトリクス一覧表示

概要

利用可能なメトリクス一覧を取得する。

リクエスト
リクエストメソッド
  • GET
リクエストパラメータ
Request Parameters
パラメーター名 説明 Required
Dimensions.member.N
Dimensionを指定する。
DimensionはName-Value Pairで構成されるため、
Dimensions.member.N.NameとDimensions.member.N.Valueを指定する必要がある.
(N= 1, 2, 3, ….., 10)
- [例]:下記の2つを同時に指定する
- Dimensions.member.1.Name=InstanceId
- Dimensions.member.1.Value=deadbeef-2929-dead-beef-cafe292983129
No
MetricName メトリクス名を指定する No
Namespace Namespaceを指定する No
NextToken
以前にListを実行した際に返されたTokenを指定する。
Tokenは、他にも取得可能なデータがあることを意味する
No
Body
  • 無し
レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
ListMetricsResponse レスポンスコンテナ ResponseMetadata, ListMetricsResult
ResponseMetadata メタデータのコンテナ RequestId
RequestId リクエストID  
ListMetricsResult Listmetricsの結果を格納するコンテナ  
NextToken 他に取得可能なデータの有無を示すトークン  
Metrics Metric情報を格納するコンテナ  
Namespace Namespace情報  
Dimensions Dimension member
member Dimensionの要素 (親ノード: Dimensions) Name, Value
Name Dimensionの名前 (親ノード: Dimensions.member)  
Value Dimensionの値 (親ノード: Dimensions.member)  
サンプルAPIコール&レスポンス
サンプルAPIコール
$ruby kick_api.rb Action=ListMetrics
サンプルAPIレスポンス
<ListMetricsResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <ListMetricsResult>
    <Metrics>
      <member>
        <Dimensions>
          <member>
            <Name>InstanceId</Name>
            <Value>ar17e9ff-5211-4c2d-bfa4-e3ea2328cc57</Value>
          </member>
        </Dimensions>
        <MetricName>StatusCheckFailed_System</MetricName>
        <Namespace>Cloudn/Compute</Namespace>
      </member>
    </Metrics>
  </ListMetricsResult>
  <ResponseMetadata>
    <RequestId>7771ea09-4a2d-b738-6967-9f2714ecaa8e</RequestId>
  </ResponseMetadata>
</ListMetricsResponse>

PutMetricData - カスタムメトリクス作成・データ投入

概要

カスタムメトリクスの作成およびカスタムメトリクスのデータ登録の両方を同時に行います。

参考

本APIの詳細な使い方は以下を御覧ください

リクエスト
リクエストメソッド
  • POST / GET
リクエストパラメータ
パラメーター名 説明 Required
MetricData.member.N.MetricName カスタムメトリクス名を指定する。 Yes
Namespace [2] Namespaceを指定する。 Yes
MetricData.member.N.Value 当該カスタムメトリクスに対して登録したい値。 Yes
MetricData.member.N.Dimensions.member.M.Name 任意のDimensionのNameを指定する。 DimensionはName-Value Pairで構成されるため、 MetricData.member.1.Dimensions.member.1.Nameと MetricData.member.1.Dimensions.member.1.Valueを指定する必要がある。 | - [例]: 下記2つをセットで指定する | - MetricData.member.1.Dimensions.member.1.Name=InstanceName | - MetricData.member.1.Dimensions.member.1.Value=SampleVM Yes
MetricData.member.N.Dimensions.member.M.Value 任意のDimensionのValueを指定する。 DimensionはName-Value Pairで構成されるため、 MetricData.member.1.Dimensions.member.1.Nameと MetricData.member.1.Dimensions.member.1.Valueを指定する必要がある。 | - [例]: 下記2つをセットで指定する | - MetricData.member.1.Dimensions.member.1.Name=InstanceName | - MetricData.member.1.Dimensions.member.1.Value=SampleVM Yes
MetricData.member.N.Unit
メトリクスに対する計測単位。
指定フォーマットの詳細は Unit
Yes

注釈

N, MはそれぞれAPIコールの中で指定するmemberの数字を指定します。
(1〜100まで指定可能)

つまり、1 APIコールの中では、100 memberまで同時に登録可能です。

脚注

[2]弊社サービスと同様のNamespaceは指定不可能です。 Namespace情報 を参照してください。
レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
PutMetricDataResponse レスポンスコンテナ ResponseMetadata
ResponseMetadata メタデータのコンテナ RequestId
RequestId リクエストID  
サンプルAPIコール&レスポンス
サンプルAPIコール
$ruby kick_api.rb Action=PutMetricData \
 MetricData.member.1.MetricName="samplemetric" \
 Namespace="Namespace" \
 MetricData.member.1.Value="50" \
 MetricData.member.1.Dimensions.member.1.Name="name" \
 MetricData.member.1.Dimensions.member.1.Value="vm" \
 MetricData.member.1.Unit="Percent"
サンプルAPIレスポンス
<PutMetricDataResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <ResponseMetadata>
    <RequestId>796963d4-f6bd-7dd9-b468-b98f61c4af59</RequestId>
  </ResponseMetadata>
</PutMetricDataResponse>

2.2. アラーム管理

アラームを管理するためのAPIについて説明します

DescribeAlarms - アラーム情報取得

概要

アラーム情報を取得する。

リクエスト
リクエストメソッド
  • GET
リクエストパラメータ
パラメーター名 説明 Required
ActionPrefix アクションネームのprefixを指定する No
AlarmNamePrefix アラームネームのprefixを指定する No
AlarmNames.member.N
取得対象とするアラームの名前を指定する
(N= 1, 2, 3, ….., 100)
No
MaxRecords 取得するアラーム数の上限を指定する No
NextToken
以前にDescribeAlarmsを実行した際に返されたTokenを指定する。
Tokenは、他にも取得可能なデータがあることを意味する
No
StateValue
アラームの状態を指定します。
有効な値:
(OK | ALARM | INSUFFICIENT_DATA)
No
レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
DescribeAlarmsResponse レスポンスコンテナ ResponseMetadata, DescribeAlarmsResult, NextToken
ResponseMetadata メタデータのコンテナ RequestId
RequestId リクエストID  
DescribeAlarmsResult 結果を格納するコンテナ MetricAlarms
NextToken 他に取得可能なデータの有無を示すトークン  
MetricAlarms アラームを格納するコンテナ member
member アラームの各要素を格納するコンテナ AlarmDescription, AlarmArn, StateReasonData, AlarmName, StateUpdatedTimestamp, AlarmConfigurationUpdatedTimestamp, StateValue, OKActions, ActionEnabled, Namespace, Threshhold, EvaluationPeriods, Statistic, AlarmActions, StateReadson, Unit, Dimensions, ComparisonOperator, MetricName
AlarmDescription アラームの説明  
StateUpdatedTimestamp アラームの状態が変化した最後の日時  
StateReasonData JSON形式でアラームの状態を提示する  
AlarmArn アラームのARN (Amazon Resource Name)  
AlarmConfigurationUpdatedTimestamp アラーム設定の最終更新日時  
AlarmName アラームの名前  
StateValue アラームのステート (OK | ALARM)  
Period 計測期間  
OKActions アラートが解消し、OK状態になった際のアクション  
ActionsEnabled アクションを実行するか否か  
Namespace ネームスペース  
Threshold 閾値  
EvaluationPeriods 閾値に達してからの期間  
Statistic 統計手法。下記のいずれか  
AlarmActions 閾値を超えた際の、アクションがARNで提示  
StateReason データ取得時点のステートの理由を可読な形で提示  
Unit 計測単位  
Dimensions Dimension member
member Dimensionの要素 (親ノード: Dimensions) name, Value
name Dimensionの名前 (親ノード: Dimensions.member)  
Value Dimensionの値 (親ノード: Dimensions.member)  
ComparisonOperator 比較演算子  
MetricName メトリック名  

参考

StartDate, EndDateで用いるフォーマットについては下記を参照してください

サンプルAPIコール&レスポンス
サンプルAPIコール
$ruby kick_api.rb Action=DescribeAlarms
サンプルAPIレスポンス
<DescribeAlarmsResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
    <DescribeAlarmsResult>
        <MetricAlarms>
            <member>
                <AlarmDescription>example for API reference</AlarmDescription>
                <StateUpdatedTimestamp>2014-08-18T00:39:55Z</StateUpdatedTimestamp>
                <InsufficientDataActions/>
                <StateReasonData/>
                <AlarmArn>arn:cloudn:monitoring:jp-e1:1107:alarm:example</AlarmArn>
                <AlarmConfigurationUpdatedTimestamp>2014-08-18T00:39:55Z</AlarmConfigurationUpdatedTimestamp>
                <AlarmName>example</AlarmName>
                <StateValue/>
                <Period>300</Period>
                <OKActions/>
                <ActionsEnabled>true</ActionsEnabled>
                <Namespace>Cloudn/Compute</Namespace>
                <Threshold>20</Threshold>
                <EvaluationPeriods>2</EvaluationPeriods>
                <Statistic>Sum</Statistic>
                <AlarmActions/>
                <StateReason/>
                <Unit/>
                <Dimensions>
                    <member>
                        <Name>InstanceId</Name>
                        <Value>99klw02c-6ee7-43cb-ba41-0af8j8a6c8df</Value>
                    </member>
                </Dimensions>
                <ComparisonOperator>GreaterThanThreshold</ComparisonOperator>
                <MetricName>CPUUtilization</MetricName>
            </member>
        </MetricAlarms>
    </DescribeAlarmsResult>
    <ResponseMetadata>
        <RequestId>e0c3c7c9-442e-d769-968b-e62faa638fef</RequestId>
    </ResponseMetadata>
</DescribeAlarmsResponse>

DescribeAlarmsForMetric - アラーム情報取得

概要

メトリクスを指定してアラームを取得する。

リクエスト
リクエストメソッド
  • GET
リクエストパラメータ
パラメーター名 説明 Required
Dimensions.member.N
Dimensionを指定する。
DimensionはName-Value Pairで構成されるため、
Dimensions.member.N.NameとDimensions.member.N.Valueを指定する必要がある.
(N= 1, 2, 3, ….., 100)
- [例]: 下記2つを同時に指定する
- Dimensions.member.1.Name=InstanceId
- Dimensions.member.1.Value=deadbeef-2929-dead-beef-cafe292983129
No
MetricName メトリクス名を指定する Yes
Namespace Namespaceを指定する Yes
Period 統計を適用してからの時間 (秒) No
Statistic 統計手法を指定します。 指定フォーマットの詳細は Statistic No
Unit メトリックに対する計測単位。 指定フォーマットの詳細は Unit No
レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
DescribeAlarmsForMetricResponse レスポンスコンテナ ResponseMetadata, DescribeAlarmsResult, NextToken
ResponseMetadata メタデータのコンテナ RequestId
RequestId リクエストID  
DescribeAlarmsFroMetricResult 結果を格納するコンテナ MetricAlarms
NextToken 他に取得可能なデータの有無を示すトークン  
MetricAlarms アラームを格納するコンテナ member
member アラームの各要素を格納するコンテナ AlarmDescription, AlarmArn, StateReasonData, AlarmName, StateUpdatedTimestamp, AlarmConfigurationUpdatedTimestamp, StateValue, OKActions, ActionEnabled, Namespace, Threshhold, EvaluationPeriods, Statistic, AlarmActions, StateReadson, Unit, Dimensions, ComparisonOperator, MetricName
AlarmDescription アラームの説明  
StateUpdatedTimestamp アラームの状態が変化した最後の日時  
StateReasonData JSON形式でアラームの状態を提示する  
AlarmArn アラームのARN (Amazon Resource Name)  
AlarmConfigurationUpdatedTimestamp アラーム設定の最終更新日時  
AlarmName アラームの名前  
StateValue アラームのステート (OK | ALARM | INSUFFICIENT_DATA )  
Period 計測期間  
OKActions アラートが解消し、OK状態になった際のアクション  
ActionsEnabled アクションを実行するか否か  
Namespace ネームスペース  
Threshold 閾値  
EvaluationPeriods 閾値に達してからの期間  
Statistic 統計手法。 返り値の詳細は Statistic を参照  
AlarmActions 閾値を超えた際の、アクションがARNで提示される。  
StateReason データ取得時点のステートの理由を可読な形で提示  
Unit 計測単位  
Dimensions Dimension member
member Dimensionの要素 (親ノード: Dimensions)  
name Dimensionの名前 (親ノード: Dimensions.member)  
Value Dimensionの値 (親ノード: Dimensions.member)  
ComparisonOperator 比較演算子  
MetricName メトリック名  
サンプルAPIコール&レスポンス
サンプルAPIコール
$ruby kick_api.rb Action=DescribeAlarmsForMetric \
Namespace="Cloudn/Compute" \
MetricName="CPUUtilization"
サンプルAPIレスポンス
<DescribeAlarmsForMetricResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
    <DescribeAlarmsForMetricResult>
        <MetricAlarms>
            <member>
                <AlarmDescription/>
                <StateUpdatedTimestamp>2014-08-18T01:05:11Z</StateUpdatedTimestamp>
                <InsufficientDataActions/>
                <StateReasonData>{&quot;version&quot;:&quot;1.0&quot;,&quot;startDate&quot;:&quot;&quot;,&quot;queryDate&quot;:&quot;2014-08-18T01:05:11Z&quot;,&quot;statistic&quot;:&quot;Sum&quot;,&quot;period&quot;:300,&quot;recentDatapoints&quot;:&quot;0.7716&quot;,&quot;threshold&quot;:20}</StateReasonData>
                <AlarmArn>arn:cloudn:monitoring:jp-e1:1107:alarm:example</AlarmArn>
                <AlarmConfigurationUpdatedTimestamp>2014-08-18T01:28:09Z</AlarmConfigurationUpdatedTimestamp>
                <AlarmName>example</AlarmName>
                <StateValue>OK</StateValue>
                <Period>300</Period>
                <OKActions>arn:cloudn:monitoring:jp-e1:test@example.com</OKActions>
                <ActionsEnabled>false</ActionsEnabled>
                <Namespace>Cloudn/Compute</Namespace>
                <Threshold>20</Threshold>
                <EvaluationPeriods>2</EvaluationPeriods>
                <Statistic>Sum</Statistic>
                <AlarmActions/>
                <StateReason>Alarm updated to OK. Reason: Threshold Crossed: 1 datapoint (0.7716) was not GreaterThanThreshold to the threshold (20).</StateReason>
                <Unit/>
                <Dimensions>
                    <member>
                        <Name>InstanceId</Name>
                        <Value>1a31ee2i-jj9a-42f2-a32b-782a7117c906</Value>
                    </member>
                </Dimensions>
                <ComparisonOperator>GreaterThanThreshold</ComparisonOperator>
                <MetricName>CPUUtilization</MetricName>
            </member>
        </MetricAlarms>
    </DescribeAlarmsForMetricResult>
    <ResponseMetadata>
        <RequestId>a8bd6585-7de5-7360-928e-b9ebab752e8d</RequestId>
    </ResponseMetadata>
</DescribeAlarmsForMetricResponse>

DescribeAlarmHistory - アラーム履歴取得

概要

アラームの履歴を取得する。

リクエスト
リクエストメソッド
  • GET
リクエストパラメータ
パラメーター名 説明 Required
AlarmName アラーム名を指定する No
HistoryItemType アラームのタイプを指定する。 Valid Value: (ConfigurationUpdate | StateUpdate | Action) No
MaxRecords 取得するアラーム数の上限を指定する No
NextToken 以前にDescribeAlarmHistoryを実行した際に返されたTokenを指定する。 Tokenは、他にも取得可能なデータがあることを意味する No
StartDate 指定した日時から発生したアラームを取得する(未対応) No
EndDate 指定した日時までに発生したアラームを取得する(未対応) No

参考

StartDate, EndDateで用いるフォーマットについては下記を参照してください

アラームのは以下で取得可能です

レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
DescribeAlarmHistoryResponse レスポンスコンテナ ResponseMetadata, DescribeAlarmHistoryResult, NextToken
ResponseMetadata メタデータのコンテナ RequestId  
RequestId リクエストID  
DescribeAlarmHistoryResult 結果を格納するコンテナ AlarmHistoryItems
NextToken 他に取得可能なデータの有無を示すトークン  
AlarmHistoryItems アラーム履歴を格納するコンテナ member
member アラーム履歴の各要素を格納するコンテナ Timestamp, HistoryItemType, AlarmName, HistoryData, HistorySummary
Timestamp アラーム発生時刻  
HistoryItemType アラームの種別  
AlarmName アラーム名  
HistoryData JSONフォーマットによるデータの実体  
HistorySummary 可読な形式のアラーム履歴のサマリー  
サンプルAPIコール&レスポンス
サンプルAPIコール
$ruby kick_api.rb Action=DescribeAlarmHistory
サンプルAPIレスポンス
<DescribeAlarmHistoryResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
    <DescribeAlarmHistoryResult>
        <AlarmHistoryItems>
            <member>
                <Timestamp>2014-08-18T00:40:14Z</Timestamp>
                <HistoryItemType>StateUpdate</HistoryItemType>
                <AlarmName>example</AlarmName>
                <HistoryData>{&quot;version&quot;:&quot;1.0&quot;,&quot;newState&quot;:{&quot;stateValue&quot;:&quot;OK&quot;,&quot;stateReason&quot;:&quot;Alarm updated to OK. Reason: Threshold Crossed: 1 datapoint (0.7629) was not GreaterThanThreshold to the threshold (20).&quot;,&quot;stateReasonData&quot;:{&quot;version&quot;:&quot;1.0&quot;,&quot;startDate&quot;:&quot;&quot;,&quot;queryDate&quot;:&quot;2014-08-18T00:40:14Z&quot;,&quot;statistic&quot;:&quot;Sum&quot;,&quot;period&quot;:300,&quot;recentDatapoints&quot;:&quot;0.7629&quot;,&quot;threshold&quot;:20}}}</HistoryData>
                <HistorySummary>Alarm updated to OK</HistorySummary>
            </member>
        </AlarmHistoryItems>
    </DescribeAlarmHistoryResult>
    <ResponseMetadata>
        <RequestId>4ecc9389-9ce4-7bee-467d-16650252a302</RequestId>
    </ResponseMetadata>
</DescribeAlarmHistoryResponse>

EnableAlarmActions - アラームアクション有効化

概要

アラームに設定されたアクションを有効にする。

リクエスト
リクエストメソッド
  • GET
リクエストパラメータ
Parameters
パラメーター名 説明 Required
AlarmNames.member.N
アラームネームを指定する。
パラメータ名に含まれるNは、1-100の範囲で指定する。
(N=1, 2, 3, 4, ..., 100)
Yes

注釈

一部のアクションだけ有効化/無効化することはできません。

レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
EnableAlarmActionsResponse レスポンスコンテナ ResponseMetadata
ResponseMetadata メタデータのコンテナ RequestId
RequestId リクエストID  

参考

レスポンスには実行リクエストIDのみが含まれます。 実行後は DescribeAlarms - アラーム情報取得 を使用することで、 <ActionsEnabled>true</ActionsEnabled> となっていることを確認可能です。

サンプルAPIコール&レスポンス
サンプルAPIコール
$ruby kick_api.rb Action=DisableAlarmActions \
AlarmNames.member.1="example"
サンプルAPIレスポンス
<DisableAlarmActionsResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <ResponseMetadata>
    <RequestId>a7299ccb-71cb-5eb8-4f47-1db26c58fb7b</RequestId>
  </ResponseMetadata>
</DisableAlarmActionsResponse>

DisableAlarmActions - アラームアクション無効化

概要

アラームに設定されたアクションを無効にする。

リクエスト
リクエストメソッド
  • GET
リクエストパラメータ
パラメーター名 説明 Required
AlarmNames.member.N
アラームネームを指定する。
パラメータ名に含まれるNは、1-100の範囲で指定する。
(N=1, 2, 3, 4, ..., 100)
Yes

注釈

一部のアクションだけ有効化/無効化することはできません。

レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
DisableAlarmActionsResponse レスポンスコンテナ ResponseMetadata
ResponseMetadata メタデータのコンテナ RequestId
RequestId リクエストID  

参考

レスポンスには実行リクエストIDのみが含まれます。 実行後は DescribeAlarms - アラーム情報取得 を使用することで、 <ActionsEnabled>false</ActionsEnabled> となっていることを確認可能です。

サンプルAPIコール&レスポンス
サンプルAPIコール
$ruby kick_api.rb Action=DisableAlarmActions \
AlarmNames.member.1="example"
サンプルAPIレスポンス
<DisableAlarmActionsResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <ResponseMetadata>
    <RequestId>a7299ccb-71cb-5eb8-4f47-1db26c58fb7b</RequestId>
  </ResponseMetadata>
</DisableAlarmActionsResponse>

PutMetricAlarm - アラーム設定

概要

アラームを設定する。

リクエスト
リクエストメソッド
  • GET
リクエストパラメータ
パラメーター名 説明 Required
Dimensions.member.N
Dimensionを指定する。
DimensionはName-Value Pairで構成されるため、
Dimensions.member.N.NameとDimensions.member.N.Valueを指定する必要がある.
(N= 1, 2, 3, ….., 100)
- [例]:下記の2つを指定する
- Dimensions.member.1.Name=InstanceId
- Dimensions.member.1.Value=deadbeef-2929-dead-beef-cafe292983129
Yes
MetricName メトリック名を指定する Yes
Namespace Namespaceを指定する Yes
Period [4] 統計を適用してからの時間 (秒) Yes
Statistic [4] 統計手法を指定します。 指定フォーマットの詳細は Statistic Yes
Unit [5]
メトリックに対する計測単位。
指定フォーマットの詳細は Unit
No
OKActions.member.N アラーム回復時 (OKに復帰した際) に、実行されるアクションをARNで指定する No
AlarmActions.member.N アラーム発生時に実行されるアクションをARNで指定する No
AlarmDescription アラームの説明 No
AlarmName [6] アラーム名 Yes
ComparisonOperator 比較演算子。 指定フォーマットの詳細は ComparisonOperator Yes
EvaluationPeriods [4] 閾値と比較する周期を指定する Yes
InsufficientDataActions.member.N [4] “INSUFFICIENT_DATA” になった際に実行されるアクションを定義する No
Threshold 閾値 Yes
ActionsEnabled アクションを実行するか否かを指定する (true|false) No

脚注

[4](1, 2, 3, 4) Amazon Web Services APIと互換性を保つため必須パラメータとして指定する必要がありますが、未対応のため値は反映されません。
[5]未対応のため反映されません。
[6]AlarmNameは半角英数字と「-」「_」「.」以外は登録できません。
Body
  • 無し
レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
PutMetricAlarmResponse レスポンスコンテナ ResponseMetadata, DescribeAlarmsResult, NextToken
ResponseMetadata メタデータのコンテナ RequestId
RequestId リクエストID  
サンプルAPIコール&レスポンス
サンプルAPIコール
$ruby kick_api.rb Action=PutMetricAlarm \
Dimensions.member.1.Name="InstanceId" \
Dimensions.member.1.Value="1e52dd2d-bb9d-41f2-a32b-782a7117c906" \
MetricName="CPUUtilization" \
Namespace="Cloudn/Compute" \
Period="300" \
Statistic="Sum" \
AlarmName="example" \
ComparisonOperator="GreaterThanThreshold" \
EvaluationPeriods="2" \
Threshold="20"
サンプルAPIレスポンス
<PutMetricAlarmResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <ResponseMetadata>
    <RequestId>9e5d84d0-234b-dd4b-ef58-a0c456a2e899</RequestId>
  </ResponseMetadata>
</PutMetricAlarmResponse>

DeleteAlarms - アラーム削除

概要

作成したアラームを削除します。

リクエスト
リクエストメソッド
  • GET
リクエストパラメータ
パラメーター名 説明 Required
AlarmNames.member.N
アラームネームを指定する。
パラメータ名に含まれるNは、1-100の範囲で指定する。
(N=1, 2, 3, 4, ..., 100)
Yes

参考

必要なパラメータは以下のAPIで取得可能です

Body
  • 無し
レスポンス
レスポンス (Body)
  • 形式:XML
Response(Body)
Node名 説明 子Node
DeleteAlarmsResponse レスポンスコンテナ ResponseMetadata
ResponseMetadata メタデータのコンテナ RequestId
RequestId リクエストID  
サンプルAPIコール&レスポンス

下記設定値に対しての例を示します。

  • AlarmName: example
サンプルAPIコール
$ruby kick_api.rb Action=DeleteAlarms \
AlarmNames.member.1=example
サンプルAPIレスポンス
<DeleteAlarmsResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <ResponseMetadata>
    <RequestId>b6479377-a3c7-d4ab-58f4-5acf53b1e15a</RequestId>
  </ResponseMetadata>
</DeleteAlarmsResponse>

3. [付録] チュートリアル

3.1. カスタムメトリクスを利用する

カスタムメトリクスを利用するためのチュートリアルです。

カスタムメトリクスの概要

カスタムメトリクスとは
カスタムメトリクスとは, お客様が任意のメトリクスを Cloudn Monitoringで設定可能とするサービスです。
お客様サーバーなどへスクリプトなどからMonitoringへデータを送ることで、お客様の任意のメトリクスを Monitoring上一つのGUIで便利に一元管理することができます。
カスタムメトリクスの仕組み

カスタムメトリクスの仕組みは以下の通りです。

データの抽出/送信
対象リソースから監視したいデータを抽出していただきます。
例えば、ウェブサーバを運用されているお客様は一サーバが受け付けているHTTPリクエスト数や、メモリの利用状況を監視されたいかもしれません。
こういったデータをスクリプト等で対象サーバから抽出していただきます。
データ取得後、今度はそのデータを Cloudn Monitoringサーバに送っていただく必要があります。
データの送信
PutMetricData - カスタムメトリクス作成・データ投入 を利用し、抽出したデータを Cloudn Monitoringのサーバにプッシュしていただきます。
より信頼性のあるメトリクスにするためには本「データ抽出 -> API実行」サイクルを
cron等で自動的に定期実行されるよう設定されていることが望ましいです。
データの表示
プッシュされてからおよそ1分後、お客様のカスタムメトリクスはMonitoringのGUIに表示されます。
なお、プッシュ頻度にもよりますが、ある程度メトリクスの「データ抽出→API実行」サイクルが繰り返されてからグラフを確認されることをお勧めします。
ある程度メトリクスが蓄積されてからの方がデータの動向がわかります。

参考

PutMetricData - カスタムメトリクス作成・データ投入 APIにて、設定が可能です。

警告

カスタムメトリクスは、2週間以上使用されていなければ自動的に削除されますことご注意ください。

当該カスタムメトリクスに対し2週間以上データ投入がなければ使用されていないと判断されます。 (API等でカスタムメトリクスを削除することはできません。)

カスタムメトリクスのデータはデフォルトで提供しているメトリクスと同様、最近2週間のデータまで保持します。

サンプルスクリプトを使う

本項では、本ドキュメントと一緒に提供されているサンプルスクリプトの利用方法について説明します。
サンプルスクリプトはLinux上で動作することを想定された、メモリ・スワップ・平均負荷のメトリクスを取得するシェルです。
デフォルトで本スクリプトを利用すれば3カスタムメトリクスができます。
手順

下記スクリプトをメモリ・スワップ・平均負荷のスタッツを取得する対象のサーバーへ配置します。

  • kick_api.rb (以下、KickAPI)

    • セットアップや動作環境については APIクライアントの利用 を参照してください
    • エンドポイントやAPIキーの設定などを完了し、Monitoring APIを利用できる状態である必要があります
    • kick_api.rb を配置した場所のフルパスを控えておきます
    • 今回の例では、 /usr/bin/monitoring 配下に配置を行います
  • sample_PutMetrics.sh (以下、sample_PutMetrics)

次に、sample_PutMetricsの設定を行います。
vim などのエディタでsample_PutMetricsを編集します。
$vim sample_PutMetrics.sh
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
#!/bin/bash

#######################Requirement#######################
##                                                     ##
## - bash (The path should be configured as /bin/bash) ##
## - kick_api.rb                                       ##
## - bc                                                ##
## - grep (should be installed as default package)     ##
## - free (should be installed as default package)     ##
## - tr (should be installed as default package)       ##
## - cut (should be installed as default package)      ##
## - uptime (should be installed as default package)   ##
## - echo  (should be installed as default package)    ##
## - Ruby 1.9.1 or later                               ##
##                                                     ##
#########################################################

# Define the path to KickAPI
# PATH_TO_KICKAPI="/usr/bin/kick_api.rb"
PATH_TO_KICKAPI=""

# Define the namespace and dimension name-value pair for the resource you will be creating custom metrics for:
NAMESPACE="examplenamespace"
DIMENSIONNAME="dimensionname"
DIMENSIONVALUE="dimensionvalue"

# Calculate memory usage
MEMTOTAL=`free -m | grep 'Mem' | tr -s ' ' | cut -d ' ' -f 2`
MEMUSED=`free -m | grep 'buffers/cache' | tr -s ' ' | cut -d ' ' -f 3`
MEMUSAGE=`echo "${MEMUSED} / ${MEMTOTAL} * 100" | bc -l`
echo "${MEMUSAGE}"

# Calculate swap usage
SWAPTOTAL=`free -m | grep 'Swap' | tr -s ' ' | cut -d ' ' -f 2`
SWAPUSED=`free -m | grep 'Swap' | tr -s ' ' | cut -d ' ' -f 3`
SWAPUSAGE=`echo "${SWAPUSED} / ${SWAPTOTAL} * 100" | bc -l`
echo "${SWAPUSAGE}"

# Get load average data of the last minute, the last 5 minutes, and the last 15 minutes, respectively.
LOADAVG1=`uptime | tr -s ' ' | cut -d ' ' -f 9 | cut -d ',' -f 1`
#LOADAVG5=`uptime | tr -s ' ' | cut -d ' ' -f 10 | cut -d ',' -f 1`
#LOADAVG15=`uptime | tr -s ' ' | cut -d ' ' -f 11`

# Pass the memory usage, swap usage, and load average data to the "value" parameter of the PutMetricData API and execute
ruby ${PATH_TO_KICKAPI} Action=PutMetricData MetricData.member.1.MetricName="MemoryUsage" Namespace="${NAMESPACE}" MetricData.member.1.Value="${MEMUSAGE}" MetricData.member.1.Dimensions.member.1.Name="${DIMENSIONNAME}" MetricData.member.1.Dimensions.member.1.Value="${DIMENSIONVALUE}" MetricData.member.1.Unit="Percent"
ruby ${PATH_TO_KICKAPI} Action=PutMetricData MetricData.member.1.MetricName="SwapUsage" Namespace="${NAMESPACE}" MetricData.member.1.Value="${SWAPUSAGE}" MetricData.member.1.Dimensions.member.1.Name="${DIMENSIONNAME}" MetricData.member.1.Dimensions.member.1.Value="${DIMENSIONVALUE}" MetricData.member.1.Unit="Percent"
ruby ${PATH_TO_KICKAPI} Action=PutMetricData MetricData.member.1.MetricName="LoadAveragePercentageFromPastMinute" Namespace="${NAMESPACE}" MetricData.member.1.Value="${LOADAVG1}" MetricData.member.1.Dimensions.member.1.Name="${DIMENSIONNAME}" MetricData.member.1.Dimensions.member.1.Value="${DIMENSIONVALUE}" MetricData.member.1.Unit="Percent"
#ruby ${PATH_TO_KICKAPI} Action=PutMetricData MetricData.member.1.MetricName="LoadAveragePercentageFromPast5Minutes" Namespace="${NAMESPACE}" MetricData.member.1.Value="${LOADAVG5}" MetricData.member.1.Dimensions.member.1.Name="${DIMENSIONNAME}" MetricData.member.1.Dimensions.member.1.Value="${DIMENSIONVALUE}" MetricData.member.1.Unit="Percent"
#ruby ${PATH_TO_KICKAPI} Action=PutMetricData MetricData.member.1.MetricName="LoadAveragePercentageFromPast15Minutes" Namespace="${NAMESPACE}" MetricData.member.1.Value="${LOADAVG15}" MetricData.member.1.Dimensions.member.1.Name="${DIMENSIONNAME}" MetricData.member.1.Dimensions.member.1.Value="${DIMENSIONVALUE}" MetricData.member.1.Unit="Percent"

以下の点を編集します

  • 20行目、 PATH_TO_KICKAPI="" に先ほど控えたkick_api.rbのフルパスを記載します

    • 例として、今回は PATH_TO_KICKAPI="/usr/bin/monitoring/kick_api.rb" と設定します
  • 23-25行目、利用したいNamespace, ディメンジョン名、ディメンジョン値を入力します

シェルに実行権限を与え、テストを実施します。

$chmod +x sample_PutMetrics.sh
$./sample_PutMetrics.sh

以下の通りHTTP 200 Status Codeが返ってくれば成功です。

#<Net::HTTPOK 200 OK readbody=true>
<PutMetricDataResponse xmlns="http://monitoring.amazonaws.com/doc/2010-08-01/">
  <ResponseMetadata>
    <RequestId>07aac1b1-fd90-f1d0-8d03-1253c942854d</RequestId>
  </ResponseMetadata>
</PutMetricDataResponse>
#<Net::HTTPOK 200 OK readbody=true>

上記で動作を確認したら、cronへスクリプトの実行を登録することで、 定期的にMonitoringへメトリクスを送信することが可能です。

注釈

本サンプルスクリプトの動作条件は以下の通りです。

  • KickAPIが動作する環境であること

  • “/bin/bash” にbashが存在すること

  • 以下のコマンドが利用できること
    • bc
    • grep
    • free
    • tr
    • cut
    • uptime
    • echo

なお、カスタムメトリクスの送信から初メトリクス表示まで1分程度かかることがあります。

上述した使い方はあくまでカスタムメトリクスのある一つの利用方法です。

カスタムメトリクスを使って他にも色んなメトリクスを管理することができます。
監視したい項目をすべてMonitoringに集めていただくことによって、リソース一元管理の実現と、それによる運用負担の軽減を実現することができます。
カスタムメトリクスを利用すれば、 Cloudn のリソースに限らず、数値化できるデータすべてを管理することができます。

Monitoringのエンドポイントに届く先であれば、どんなデータでも溜めることができます。