GrowthForecast

GrowthForecastは様々な値をWebAPI経由でグラフ化できるWebツールです。シンプルなAPIでリアルタイムにグラフを作成、更新でき、Webインターフェイスからグラフの表示をカスタマイズしたり、複数のメトリクスを重ね合わせたグラフを作成できます

MySQLのデータを1行のコードでグラフ化できます

$ crontab -l
*/5 * * * * curl -F number=`mysql -BN -e 'select count(*) from member' game` http://example.com/api/socialgame/member/register 2>&1 | logger -t post_gf -p local0.info

cronで定期的にGrowthForecastにPOSTするだけで、設定なしでグラフが作れます


(1) 依存パッケージの導入

RRDToolが依存するライブラリを導入します。以下のライブラリをyum、apt、homebrew等OSのパッケージマネージャを利用してインストールします

  • glib
  • xml2
  • pango
  • cairo

CentOS

$ sudo yum groupinstall "Development Tools"
$ sudo yum install pkgconfig glib2-devel gettext libxml2-devel pango-devel cairo-devel

Ubuntu

$ sudo apt-get build-dep rrdtool

(2) GrowthForecastのインストール

cpanmコマンドを利用して依存モジュールも一緒にインストールします。

OSに最初から入っているperlではなくperlbrew等で構築したperlを使う事をお勧めします

$ cpanm -n GrowthForecast

バージョンはCPANにて確認してください。インストールは依存モジュールの数が多いので時間がかかります

(3) GrowthForecastの起動

ここまでの手順でインストールは完了です。GrowthForecast の起動は「growthforecast.pl」を実行します

data-dir オプションにグラフデータを保存するディレクトリを指定して起動すると、port 5125 でWebサーバが起動するので、ブラウザで確認できます

起動コマンド

$ growthforecast.pl --data-dir /home/user/growthforecast

その他の起動オプション

オプション名 説明
portバインドするTCPポート。デフォルトは5125
hostバインドするIPアドレス。デフォルトは0.0.0.0
front-proxyリバースプロキシーを利用している場合、リバースプロキシーのIPアドレスもしくはCIDRで指定する。複数指定可
allow-fromアクセス元IPアドレスの指定。指定しないと全てのリモートホストからアクセス可能
disable-1min-metrics1分毎にグラフを更新する機能の停止
with-mysqlグラフ情報を保存するDBに標準のSQLiteではなくMySQLを使う。dbi:mysql:[dbname];hostname=[hostname] の形式で指定
time-zoneGrowthFocastのタイムゾーンを指定します。デフォルトはシステムのタイムゾーンです
h または helpヘルプの出力
v または versionバージョンの出力

MySQLを使う場合

--with-mysql オプションを指定しMySQLを使う場合次の権限が必要となります。

  • CREATE
  • ALTER
  • DELETE
  • INSERT
  • UPDATE
  • SELECT

GRANT文の例

mysql> GRANT  CREATE, ALTER, DELETE, INSERT, UPDATE, SELECT \\
         ON growthforecast.* TO 'www'\@'localhost' IDENTIFIED BY foobar;

ユーザ名とパスワードは環境変数で指定します

$ MYSQL_USER=www MYSQL_PASSWORD=foobar growthforecast.pl \\
      --data-dir /home/user/growthforecast \\
      --with-mysql dbi:mysql:growthforecast;hostname=localhost 

グラフの登録方法

グラフの作成・データ更新を行うには以下のURLに対してPOSTメソッドにてリクエストを行います

http://example.com/api/:service_name/:section_name/:graph_name

POSTする際のURL中の各名前は右にまとめました

各項目名にはUTF-8であればマルチバイト文字列が使えます

例中の名前 役割 具体例を , 区切りで
:service_name グラフを取りたいサービスの名前 blog, photo, place, socialgame
:section_name そのサービスの中での、グラフを取る対象が属してる機能やシステム名 entry, user, spot, items
:graph_name 具体的に何のグラフか total_entry, kakin_user, muryo_user

もしソーシャルゲームの登録ユーザ数をグラフにするのであれば

http://example.com/api/socialgame/member/register

に対して POST します。

また、 POST する時には以下のパラメータをつけます。

パラメータ 説明 必須/オプション
number グラフに与える数値 必須
mode 数値のアップデート方法。count or modified or gauge。
count: 登録済みの数値を number の値で加算
modified: 前回と異なる数値の時だけ上書き更新
gauge: number の数値で常に上書き
デフォルトは gauge
オプション
color グラフの色。#FFFFFF 形式で指定 オプション/新規グラフで指定なしの場合自動生成
timestamp プロット時間。315360010 より大きいエポック秒(整数)で指定。
例えばログに書き込まれている時間フィールドを元に明示的に時間を指定してプロットしたい場合に役立つ
制限1: 最新の更新時間よりも新しい timestamp のみ有効 (rrdtool の制限)
制限2: rrdupdate は GrowthForecast worker によって一定インターバル毎(short worker の場合1分、long worker の場合5分)に実行される。そのため、インターバル内の最新のデータのみが使われる。
オプション/現在時間が使用される
datetime 以下の文字フォーマットでプロット時間を指定する
"Wed, 09 Feb 1994 22:23:32 GMT"       -- HTTP format
"Thu Feb  3 17:03:55 GMT 1994"        -- ctime(3) format
"Thu Feb  3 00:00:00 1994",           -- ANSI C asctime() format
"Tuesday, 08-Feb-94 14:15:29 GMT"     -- old rfc850 HTTP format
"Tuesday, 08-Feb-1994 14:15:29 GMT"   -- broken rfc850 HTTP format
"03/Feb/1994:17:03:55 -0700"   -- common logfile format
"09 Feb 1994 22:23:32 GMT"     -- HTTP format (no weekday)
"08-Feb-94 14:15:29 GMT"       -- rfc850 format (no weekday)
"08-Feb-1994 14:15:29 GMT"     -- broken rfc850 format (no weekday)
"1994-02-03 14:15:29 -0100"    -- ISO 8601 format
"1994-02-03 14:15:29"          -- zone is optional
"1994-02-03"                   -- only date
"1994-02-03T14:15:29"          -- Use T as separator
"19940203T141529Z"             -- ISO 8601 compact format
"19940203"                     -- only date
オプション/デフォルトでは現在時間を、timestamp パラメータも同時に指定された場合は timestamp パラメータが使用される

グラフ登録サンプル

PerlのLWPモジュールを利用したグラフの登録・更新サンプル

my $ua = LWP::UserAgent->new;
$ua->post('http://example.com/api/socialgame/member/register',{
    number      => 10,
    color       => '#333399'
});

curlを使った場合

$ curl -F number=10 http://example.com/api/socialgame/member/register

GrowthForeacstの仕組み

GrowthForecastはRound Robbin Databaseおよびグラフ描画のツールとしてRRDtoolを利用しています。

APIのエンドポイントに送信されたデータはRDMBSに一旦保存されます。Workerが定期的に動作し、RDBMSからデータを読み出し、RRDファイルを更新しています。その際、GrowthForecastのworkerは、現在の値に加えて、一つ前との差分をsubtractデータとして格納しています。

subtractデータをグラフのソースとして利用することで、データの変化量を可視化することができます

垂直線の追加 (GrowthForecast 0.82以上)

グラフに垂直線を描く事ができます

エンドポイント

垂直線の追加 http://example.com/vrule/api[/:service_name[/:section_name[/:graph_name]]]
垂直線データの取得 http://example.com/vrule/summary[/:service_name[/:section_name[/:graph_name]]]

垂直線追加時のパラメータ

パラメータ 説明 必須/オプション
time 垂直線を描画する日付時間。「2011/12/08 12:10:00」の形式で指定。デフォルトは現在時間 オプション
color 垂直線の色。#FFFFFF 形式で指定。デフォルトは「#FF0000」 オプション
description 垂直線の説明 オプション

垂直線登録サンプル

curlを使った場合

$ curl -F description=deploy -F color=#FF0000 http://example.com/vrule/api/socialgame/member

垂直線データ取得時のパラメータ

パラメータ 説明
t 取得する範囲。all(全期間)、c(任意・toおよびfromを使用)、h(直近1時間)、n(半日)、w(一週間)、m(一ヶ月) y(1年) 3d(3日間) 8h(8時間) 4h(4時間)
from 「t」が「c」の場合、取得する開始日付。「2011/12/08 12:10:00」の形式で指定
to 「t」が「c」の場合、取得する終了日付。「2011/12/08 12:10:00」の形式で指定

グラフの表示のカスタマイズ

グラフのURIに対していくつかパラメータを与えるとグラフの描画をカスタマイズすることができます

エンドポイント

グラフのURI     http://example.com/graph/:service_name/:section_name/:graph_name
複合グラフのURI http://example.com/graph/:pattern

サポートしているパラメータ一覧

パラメータを変更する事で↓こんなグラフも作れます

http://example.com/graph/service/section/graph?t=d&gmode=gauge&border=0&legend=0&width=200&background_color=333333&canvas_color=333333&font_color=CCCCCC&axis_color=666666
パラメータ 説明
t グラフの範囲。y(年間)、m(月間)、w(週間)、3d(3日間)、s3d(3日間・1分更新)、d(一日)、sd(一日・1分更新)、8h(8時間)、s8h(8時間・1分更新)、4h(4時間)、s4h(4時間・1分更新)、h(1時間)、sh(1時間・1分更新)、n(半日)、sn(半日・1分更新)、c(任意)、sc(任意・1分更新)
from 「t」が「c」または「sc」の場合、描画する開始日付。「2011/12/08 12:10:00」の形式で指定
to 「t」が「c」または「sc」の場合、描画する終了日付。「2011/12/08 12:10:00」の形式で指定
gmode 値そのままの普通グラフ「gauge」か差分グラフ「subtract」の選択。デフォルトは「gauge」
width 横幅。実際には凡例などを含むので指定したサイズより大きくなる
height 縦幅。実際には凡例などを含むので指定したサイズより大きくなる
graphonly グラフ部分しか描画しないモード。デフォルト「0」
logarithmic 対数グラフ。デフォルト「0」
xgrid X軸の設定。フォーマットはrrdtoolのドキュメント参照のこと
ygrid Y軸の設定。フォーマットはrrdtoolのドキュメント参照のこと
background_color 背景色。FFFFFF または FFFFFF00 で指定。最後の2文字はアルファチャンネル
canvas_color グラフ部分背景色。FFFFFF または FFFFFF00 で指定
font_color 文字色。FFFFFF または FFFFFF00 で指定
frame_color 凡例の色を囲っている部分。FFFFFF または FFFFFF00 で指定
axis_color グラフ部分の枠線。FFFFFF または FFFFFF00 で指定
shadea_color 左上、上の枠線。FFFFFF または FFFFFF00 で指定
shadeb_color 右下、下の枠線。FFFFFF または FFFFFF00 で指定
border 枠線の太さ。「0」も可能。デフォルト「3」
legend 凡例の有無。デフォルト「1」
sumup 凡例に合計値を含むかどうか。デフォルト「0」
vrule_legend 垂直線の説明を凡例に出すかどうか。デフォルト「1」

グラフデータのサマリー

グラフデータの凡例部分をJSON形式でエクスポートできます

エンドポイント

グラフのサマリーURI     http://example.com/summary/:service_name/:section_name/:graph_name
複合グラフのサマリーURI  http://example.com/summary/:pattern

グラフデータのエクスポート

グラフデータをJSON形式でエクスポートできます

エンドポイント

グラフのURI http://example.com/xport/:service_name/:section_name/:graph_name
複合グラフのURI  http://example.com/xport/:pattern

パラメータ一覧

パラメータ 説明
t グラフの範囲。y(年間)、m(月間)、w(週間)、3d(3日間)、s3d(3日間・1分更新)、d(一日)、sd(一日・1分更新)、8h(8時間)、s8h(8時間・1分更新)、4h(4時間)、s4h(4時間・1分更新)、h(1時間)、sh(1時間・1分更新)、n(半日)、sn(半日・1分更新)、c(任意)、sc(任意・1分更新)
from 「t」が「c」または「sc」の場合、描画する開始日付。「2011/12/08 12:10:00」の形式で指定
to 「t」が「c」または「sc」の場合、描画する終了日付。「2011/12/08 12:10:00」の形式で指定
gmode 値をそのまま描画する普通グラフか差分グラフの選択、「gauge」または「subtract」。デフォルトは「gauge」 値そのままの普通グラフ「gauge」か差分グラフ「subtract」の選択。デフォルトは「gauge」
width rowの最大個数

fluent-plugin-growthforecast

https://github.com/tagomoris/fluent-plugin-growthforecast
Fluentd plugin to output numbers(metrics) to 'GrowthForecast', metrics drawing tool over HTTP.

rb-growthforecast (ruby)

https://github.com/tagomoris/rb-growthforecast
Client library and command to operate GrowthForecast

growthforecast-client (ruby)

https://github.com/sonots/growthforecast-client
growthforecast-client is a ruby client library for GrowthForecast API where GrowthForecast is a visualization graph tool.

Net::GrowthForecast (perl)

https://metacpan.org/pod/Net::GrowthForecast
A client library for awesome visualization tool GrowthForecast