vague memory

うろ覚えを無くしていこうともがき苦しむ人の備忘録

Datadog (dogコマンド) service_check編

Datadog公式のツール dog 使用方法まとめ service_check 編です。

f:id:htnosm:20170325135420p:plain

service_check Modes

カスタムステータスチェックの送信を行います。 APIcheck_run が該当します。

check

usage: dog service_check check [-h] [--timestamp TIMESTAMP]
                               [--message MESSAGE] [--tags TAGS]
                               check host_name status

positional arguments:

引数 説明
check 送信メッセージ
host_name 関連ホスト名
status ステータス値。整数。(‘0’:OK, ‘1’:WARNING, ‘2’:CRITICAL, ‘3’:UNKNOWN)

optional arguments:

ロングオプション 説明
–timestamp イベント発生日時。POSIX。(デフォルト現在日時)
–message ステータス値の説明
–tags タグを付与

実行例

timestamp、message オプションは必須のようです。
message 未指定だとエラーとなり、 timestamp 未指定だと Datadog(WebUI)側で表示されませんでした。

# message 未指定
$ dog service_check check "customService" "$(uname -n)" 0
ERROR: "message" parameter should be a string
# message 指定
$ dog service_check check --timestamp $(date +'%s') --message "CustomServiceMessage" "customService" "$(uname -n)" 0
{"status": "ok"}

正常に登録できた場合、[Check Summary]に表示されます。

f:id:htnosm:20170325135421p:plain

host_name に指定した値の host: タグが付与されます。

f:id:htnosm:20170325135423p:plain

Monitor(Custom Check) 作成時の指定も可能になります。

f:id:htnosm:20170325135422p:plain

tag オプション

任意のタグを付与します。
複数タグはできないようです。 (タブ区切り、スペース区切りを試しましたが、 _ に置換され結合されてしまいました。)

$ dog service_check check --timestamp $(date +'%s') --message "CustomServiceMessage" "customService" --tags "stage:dev" "$(uname -n)" 0
{"status": "ok"}

f:id:htnosm:20170325135424p:plain

status 値

status に不正な値を入れるとエラーが返ります。

Traceback (most recent call last):
  File "/usr/bin/dog", line 9, in <module>
    load_entry_point('datadog==0.15.0', 'console_scripts', 'dog')()
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/__init__.py", line 69, in main
    args.func(args)
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/service_check.py", line 34, in _check
    timestamp=args.timestamp, message=args.message, tags=args.tags)
  File "/usr/lib/python2.7/site-packages/datadog/api/service_checks.py", line 37, in check
    % ', '.join(str(v) for v in CheckStatus.ALL))
datadog.api.exceptions.ApiError: Invalid status, expected one of: 0, 1, 2, 3

message 値

Monitor に {{check_message}} を設定することで、 –message で指定した内容を通知に含むことができます。

f:id:htnosm:20170325135426p:plain

  • Slackへの通知例

f:id:htnosm:20170325135425p:plain


0からカスタムチェックを作成するよりは、手軽に実装できると思います。

Datadog (dogコマンド) downtime編

Datadog公式のツール dog 使用方法まとめ downtime 編です。

f:id:htnosm:20170325135413p:plain


目次


downtime Modes

downtime 設定を行います。

f:id:htnosm:20170325135414p:plain

サブコマンド 説明
show ダウンタイム情報出力
show_all 全ダウンタイム情報出力
post ダウンタイムスケジュール作成
update ダウンタイムスケジュール更新
delete ダウンタイムスケジュール削除

show

ダウンタイム情報を出力します。

usage: dog downtime show [-h] downtime_id

実行例

JSON 形式で出力されます。

$ downtime_id=XXXXXXXX2
$ dog downtime show ${downtime_id} | jq '.'
{
  "recurrence": null,
  "end": null,
  "parent_id": null,
  "monitor_id": null,
  "start": NNNNNNNNN4,
  "disabled": false,
  "canceled": null,
  "creator_id": XXXXX8,
  "scope": [
    "host:i-XXXXXXXX"
  ],
  "active": true,
  "timezone": "UTC",
  "message": null,
  "id": XXXXXXXX2,
  "updater_id": null
}

show_all

全ダウンタイム情報を出力します。

usage: dog downtime show_all [-h] [--current_only CURRENT_ONLY]

optional arguments:

ロングオプション 説明
–current_only CURRENT_ONLY を指定。active=true のみ出力

実行例

オプション無し

JSON 形式で出力されます。 active = false (Web画面上表示されない) 設定も含めて返却されます。

$ dog downtime show_all | jq '.'
[
  {
    "recurrence": null,
    "end": null,
    "parent_id": null,
    "monitor_id": null,
    "start": NNNNNNNNN1,
    "disabled": true,
    "canceled": NNNNNNNNN6,
    "creator_id": XXXXX8,
    "scope": [
      "host:i-XXXXXXXX"
    ],
    "active": false,
    "timezone": "UTC",
    "message": null,
    "id": XXXXXXXX3,
    "updater_id": XXXXX8
  },
・・・略
  {
    "recurrence": null,
    "end": null,
    "parent_id": null,
    "monitor_id": XXXXXXXX8,
    "start": NNNNNNNNN4,
    "disabled": false,
    "canceled": null,
    "creator_id": XXXXX8,
    "scope": [
      "*"
    ],
    "active": true,
    "timezone": "UTC",
    "message": "Monitor muted from web",
    "id": XXXXXXXX9,
    "updater_id": null
  },
・・・略
  }
]

current_only オプション

active = true (Web画面上表示される) 設定のみ返却されます。 ロングオプション指定のみではなく、--current_only CURRENT_ONLY の記述が必要です。

$ dog downtime show_all --current_only CURRENT_ONLY | jq '.'
[
  {
    "recurrence": null,
    "end": null,
    "parent_id": null,
    "monitor_id": null,
    "start": NNNNNNNNN4,
    "disabled": false,
    "canceled": null,
    "creator_id": XXXXX8,
    "scope": [
      "host:i-XXXXXXXX"
    ],
    "active": true,
    "timezone": "UTC",
    "message": null,
    "id": XXXXXXXX2,
    "updater_id": null
  },
  {
    "recurrence": null,
    "end": null,
    "parent_id": null,
    "monitor_id": null,
    "start": NNNNNNNNN7,
    "disabled": false,
    "canceled": null,
    "creator_id": null,
    "scope": [
      "host:i-XXXXXXXXXXXXXXXXX"
    ],
    "active": true,
    "timezone": "UTC",
    "message": "This manually stopped or terminated AWS instance has been automatically silenced by Datadog.\n\nAWS reported host i-XXXXXXXXXXXXXXXXX as 'stopping' with the reason: 'Client.UserInitiatedShutdown: User initiated (yyyy-mm-dd hh:mm:ss GMT)'",
    "id": XXXXXXXX1,
    "updater_id": null
  },
  {
    "recurrence": null,
    "end": null,
    "parent_id": null,
    "monitor_id": XXXXXXXX8,
    "start": NNNNNNNNN4,
    "disabled": false,
    "canceled": null,
    "creator_id": XXXXX8,
    "scope": [
      "*"
    ],
    "active": true,
    "timezone": "UTC",
    "message": "Monitor muted from web",
    "id": XXXXXXXX9,
    "updater_id": null
  }
]

自動で作成される automatically muted hosts のダウンタイムも含みます。

f:id:htnosm:20170325135415p:plain

post

ダウンタイムスケジュールを作成します。

usage: dog downtime post [-h] [--end END] [--message MESSAGE] scope start

Monitor 指定、繰り返しスケジュールは未サポートです。 APIとしては存在します。(monitor_id指定はドキュメント記載が無いです。)

f:id:htnosm:20170325135418p:plain

positional arguments:

引数 説明
scope 適用対象タグ
start 開始日時を指定。POSIX timestamp

optional arguments:

ロングオプション 説明
–end 終了日時を指定。POSIX timestamp。指定無しの場合は forever(無限)
–message 関連付けるメッセージ本文

実行例

オプション無し

スコープ、開始日時を指定する必要があります。(現在日時の自動設定はありません)

$ dog downtime post "*" "$(date +'%s')" | jq '.'
{
  "recurrence": null,
  "end": null,
  "parent_id": null,
  "monitor_id": null,
  "start": NNNNNNNNN9,
  "disabled": false,
  "canceled": null,
  "creator_id": XXXXX8,
  "scope": [
    "*"
  ],
  "active": true,
  "timezone": "UTC",
  "message": null,
  "id": XXXXXXXX4,
  "updater_id": null
}

message オプション

downtime にメッセージを関連付けます。各種通知を行うことも可能です。

$ dog downtime post --end "$(date -d '1 hour' +'%s')" --message "1時間止めます @slack-xxxxxx" "*" "$(date +'%s')" | jq '.'
{
  "recurrence": null,
  "end": NNNNNNNNN3,
  "parent_id": null,
  "monitor_id": null,
  "start": NNNNNNNNN3,
  "disabled": false,
  "canceled": null,
  "creator_id": XXXXX8,
  "scope": [
    "*"
  ],
  "active": true,
  "timezone": "UTC",
  "message": "1時間止めます @slack-xxxxxx",
  "id": XXXXXXXX8,
  "updater_id": null
}

f:id:htnosm:20170325135416p:plain

  • Slackへの通知例

f:id:htnosm:20170325135417p:plain

update

ダウンタイムスケジュールを更新します。post とほぼ同じ構文で、対象の downtime_id を指定します。
scope,start は必須オプションではなくなっています。(部分更新可能)

usage: dog downtime update [-h] [--scope SCOPE] [--start START] [--end END]
                           [--message MESSAGE]
                           downtime_id

実行例

$ dog downtime update --start "$(date -d '1 hour' +'%s')" --end "$(date -d '2 hour' +'%s')" --message "開始を1時間遅らせます" ${downtime_id} | jq '.'
{
  "recurrence": null,
  "end": NNNNNNNNN1,
  "parent_id": null,
  "monitor_id": null,
  "start": NNNNNNNNN1,
  "disabled": false,
  "canceled": null,
  "creator_id": XXXXX8,
  "scope": [
    "*"
  ],
  "active": false,
  "timezone": "UTC",
  "message": "開始を1時間遅らせます",
  "id": XXXXXXXX8,
  "updater_id": XXXXX8
}

f:id:htnosm:20170325135419p:plain

start > end を指定した場合はエラーとなります。

$ dog downtime update --start "$(date -d '2 hour' +'%s')" --end "$(date -d '1 hour' +'%s')" --message "start > end で指定" ${downtime_id} | jq '.'
ERROR: Downtime cannot end before it begins

delete

ダウンタイムスケジュールを削除します。

usage: dog downtime delete [-h] downtime_id

実行例

レスポンスはありません。 disabled = true が設定されます。(WebUI上は表示されなくなります。)

$ dog downtime delete ${downtime_id}
$
$ dog downtime show ${downtime_id} | jq '.'
{
  "recurrence": null,
  "end": NNNNNNNNN1,
  "parent_id": null,
  "monitor_id": null,
  "start": NNNNNNNNN1,
  "disabled": true,
  "canceled": XXXXXXXX8,
  "creator_id": XXXXX8,
  "scope": [
    "*"
  ],
  "active": false,
  "timezone": "UTC",
  "message": "開始を1時間遅らせます",
  "id": XXXXXXXX8,
  "updater_id": XXXXX8
}

Datadog (dogコマンド) host編

Datadog公式のツール dog 使用方法まとめ host 編です。

f:id:htnosm:20170325010528p:plain


目次


host Modes

host とありますが、操作できるのは mute|unmute のみです。

サブコマンド 説明
mute ホストのmute(通知無効化)
unmute ホストのunmute(通知無効化解除)

mute

usage: dog host mute [-h] [--end END] [--message MESSAGE] [--override]
                     host_name

optional arguments:

ロングオプション 説明
–end 終了日時を指定。POSIX timestamp。指定無しの場合は forever(無限)
–message 関連付けるメッセージ本文
–override 既に mute 状態の場合でも終了期間を上書きする

実行例

$ host_name="i-XXXXXXXX"
$ dog host mute ${host_name}
{"action": "Muted", "downtime_id": XXXXXXX33, "hostname": "i-XXXXXXXX"}

[Infrastracture List]、または、[Manage Downtime] で確認できます。

f:id:htnosm:20170325010529p:plain

デフォルトで設定されるスケジュールは登録日時から Forever です。

f:id:htnosm:20170325010530p:plain

既に mute 済みの場合は override オプションを使用するようメッセージが出力されます。

$ dog host mute ${host_name}
ERROR: host:i-XXXXXXXX is already muted. To mute this host with a different end timestamp,                             add ?override=true to your request.

message オプション

downtime にメッセージを関連付けます。各種通知を行うことも可能です。

$ dog host mute --end $(date -d '1 hour' +'%s') --message "1時間無効化します @slack-xxxxxx" ${host_name}
{"action": "Muted", "downtime_id": XXXXXXX73, "hostname": "i-XXXXXXXX", "end": NNNNNNNNN9, "message": "1\u6642\u9593\u7121\u52b9\u5316\u3057\u307e\u3059 @slack-xxxxxx"}

f:id:htnosm:20170325010532p:plain

指定したスケジュール(登録日時から1時間)、通知設定が入ります。

f:id:htnosm:20170325010533p:plain

  • Slackへの通知例

f:id:htnosm:20170325010534p:plain

既に mute 済みの場合は、end、message 共に更新不可です。オプション無し時と同様に override オプションを使用するようメッセージが出力されます。

$ dog host mute --end $(date -d '2 hour' +'%s') --message "2時間無効化に伸ばします" ${host_name}
ERROR: host:i-XXXXXXXX is already muted. To mute this host with a different end timestamp,                             add ?override=true to your request.

override オプション

unmuteの状態に加え、既にmute済みでも更新できるようになります。

$ dog host mute --end $(date -d '2 hour' +'%s') --message "2時間無効化に伸ばします" --override ${host_name}
{"action": "Muted", "downtime_id": XXXXXXX75, "hostname": "i-XXXXXXXX", "end": NNNNNNNNN0, "message": "2\u6642\u9593\u7121\u52b9\u5316\u306b\u4f38\u3070\u3057\u307e\u3059"}

f:id:htnosm:20170325010535p:plain

unmute

オプションはありません。

usage: dog host unmute [-h] host_name

実行例

$ host_name="i-XXXXXXXX"
$ dog host unmute ${host_name}
{"action": "Unmuted", "downtime_id": XXXXXXX33, "hostname": "i-XXXXXXXX"}

f:id:htnosm:20170325010531p:plain

unmute 済みの場合はメッセージ出力のみです。

$ dog host unmute ${host_name}
ERROR: host:i-XXXXXXXX is not muted.

monitor {mute|unmute} コマンドはモニターを軸にタグ(スコープ)による指定を行うのに対し、 指定 host 単体の全モニターが対象になります。 対象ホストをメンテナンス(mute)状態にしたい場合に利用できると思います。

Datadog (dogコマンド) screenboard編

Datadog公式のツール dog 使用方法まとめ screenboard 編です。

f:id:htnosm:20170323212159p:plain


目次


screenboard Modes

ダッシュボード(screenboard) 操作を行います。

f:id:htnosm:20170323212200p:plain

サブコマンド 説明
show スクリーンボード情報出力
post スクリーンボード新規作成
update スクリーンボード更新
pull スクリーンボード定義取得
push スクリーンボード更新
new_file スクリーンボードの新規作成と定義取得 (post後にpull)
delete スクリーンボードの削除
share Public URL の払い出し
revoke Public URL の削除

timeboard と異なる点としては、show_all、pull_all、web_view が無い事と、 public URL を操作する shore,revoke がある事です。

JSON形式で定義することになりますが、 1からJSONを作るのは中々難しいため、 参照用のスクリーンボードを用意して確認します。

  • サンプルスクリーンボード

f:id:htnosm:20170323212201p:plain

show

スクリーンボード定義を出力します。JSON形式で出力されます。

usage: dog screenboard show [-h] screenboard_id

前述の通り、全ダッシュボードを対象としたリスト出力(show_all)は未サポートです。 (APIとしては存在します)

実行結果

$ board_id=XXXXX3
$ dog screenboard show ${board_id} | jq '.'
{
  "board_title": "SampleScreenBoard",
  "read_only": false,
  "isIntegration": false,
  "board_bgtype": "board_graph",
  "created": "yyyy-mm-ddThh:mm:ss.454510+00:00",
  "original_title": "SampleScreenBoard",
  "modified": "yyyy-mm-ddThh:mm:ss.634253+00:00",
  "disableEditing": false,
  "height": 80,
  "width": "100%",
  "template_variables": [
    {
      "default": "*",
      "prefix": null,
      "name": "scope"
    },
・・・略
    }
  ],
  "templated": true,
  "widgets": [
    {
      "metric": "aws.ec2.host_ok",
・・・略
      },
      "res_calc_func": "raw",
      "aggr": "sum",
      "y": 13,
      "calc_func": "raw"
    },
・・・略
    }
  ],
  "disableCog": false,
  "id": XXXXX3,
  "title_edited": false,
  "isShared": false
}
# 存在しないID指定の場合
$ dog screenboard show ${board_id}X | jq '.'
ERROR: The value provided for parameter 'board_id' is invalid

post

スクリーンボードを作成します。

usage: dog screenboard post [-h] [--template_variables TEMPLATE_VARIABLES]
                            [--width WIDTH] [--height HEIGHT]
                            title description [graphs]

意図した動作となりません
新規スクリーンボードの作成は行えましたが、APIに問題があるようで、指定値が反映されません。

positional arguments:

引数 説明
title スクリーンボード名
description スクリーンボードの説明
graphs グラフ定義JSON。標準入力から読み込ませる事も可能。

optional arguments:

ロングオプション 説明
–template_variables テンプレート変数定義JSON
–width スクリーンボードの横幅を指定。pixel
–height スクリーンボードの縦幅を指定。pixel

実行例(エラー)

未修正、show コマンド結果JSONの使用

graphs の扱いに問題が有り、読み込みが行われません。 引数として渡した場合、中断(Ctrl+C)するまで返ってこず、標準入力から渡した場合、エラー Exception: bad json parameter となります。

# 引数として渡す
$ dog screenboard post "sb1" "ScreenBoard Test 1" "$(cat SampleScreenBoard.post.single.json)"
^CTraceback (most recent call last):
  File "/usr/bin/dog", line 9, in <module>
    load_entry_point('datadog==0.15.0', 'console_scripts', 'dog')()
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/__init__.py", line 69, in main
    args.func(args)
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/screenboard.py", line 169, in _post
    graphs = sys.stdin.read()
KeyboardInterrupt
# 標準入力から渡す
$ cat SampleScreenBoard.post.single.json | dog screenboard post "sb1" "ScreenBoard Test 1"
Traceback (most recent call last):
  File "/usr/bin/dog", line 9, in <module>
    load_entry_point('datadog==0.15.0', 'console_scripts', 'dog')()
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/__init__.py", line 69, in main
    args.func(args)
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/screenboard.py", line 178, in _post
    raise Exception('bad json parameter')
Exception: bad json parameter

一部修正、show コマンド結果JSONの使用(widgets配下)

post 時の不要な読み込みを削除し、showコマンド結果JSONwidgets 配下の状態で実行するとコマンド実行は成功しました。

  • screenboard.py
@@ -166,7 +166,7 @@

     @classmethod
     def _post(cls, args):
-        graphs = sys.stdin.read()
+#        graphs = sys.stdin.read()
         api._timeout = args.timeout
         format = args.format
         graphs = args.graphs
$ dog screenboard post "sb1" "ScreenBoard Test 1" "$(cat SampleScreenBoard.post.single.json)" | jq '.'
{
  "read_only": false,
  "description": "ScreenBoard Test 1",
  "title": "sb1",
  "created": "yyyy-mm-ddThh:mm:ss.739591+00:00",
  "modified": "yyyy-mm-ddThh:mm:ss.739608+00:00",
  "height": null,
  "graphs": [
    {
      "board_id": XXXX6,
      "title_size": 13,
      "title": true,
      "title_align": "left",
      "title_text": "CPU utilization by name (top 10)",
      "height": 21,
      "tile_def": {
        "viz": "timeseries",
        "requests": [
          {
            "q": "top(avg:aws.ec2.cpuutilization{$scope,$region,$availability-zone} by {name},10,'mean','desc')",
            "aggregator": "avg",
            "style": {
              "palette": "warm"
            },
            "type": "line",
            "conditional_formats": []
          }
        ]
      },
      "width": 42,
      "timeframe": "4h",
      "y": 0,
      "x": 82,
      "legend_size": "0",
      "type": "timeseries",
      "legend": false
    }
  ],
  "template_variables": [],
  "id": XXXXX1,
  "width": null
}

作成されたダッシュボードを見ると、空の状態で作成されてしまっています。

f:id:htnosm:20170323212202p:plain

show コマンドで返却される値は正しいように見えます。

$ dog screenboard show XXXXX1 | jq '.'
{
  "read_only": false,
  "description": "ScreenBoard Test 1",
  "title": "sb1",
  "created": "yyyy-mm-ddThh:mm:ss.739591+00:00",
  "modified": "yyyy-mm-ddThh:mm:ss.739608+00:00",
  "height": null,
  "graphs": [
    {
      "board_id": XXXX6,
      "title_size": 13,
      "title": true,
      "title_align": "left",
      "title_text": "CPU utilization by name (top 10)",
      "height": 21,
      "tile_def": {
        "viz": "timeseries",
        "requests": [
          {
            "q": "top(avg:aws.ec2.cpuutilization{$scope,$region,$availability-zone} by {name},10,'mean','desc')",
            "aggregator": "avg",
            "style": {
              "palette": "warm"
            },
            "type": "line",
            "conditional_formats": []
          }
        ]
      },
      "width": 42,
      "timeframe": "4h",
      "y": 0,
      "x": 82,
      "legend_size": "0",
      "type": "timeseries",
      "legend": false
    }
  ],
  "template_variables": [],
  "id": XXXXX1,
  "width": null
}

APIの直実行

同じJSON定義でAPIを直接実行してみましたが、同様の結果となりました。 API側の問題になりそうです。

$ curl -X POST -H "Content-type: application/json" \
> -d '@SampleScreenBoard.post.single.json' \
> "https://app.datadoghq.com/api/v1/screen?api_key=${api_key}&application_key=${app_key}"
{"board_id":XXXX6,"read_only":false,"title_size":13,"title":true,"id": XXXXX7,"title_align":"left","modified":"yyyy-mm-ddThh:mm:ss.495185+00:00","title_text":"CPU utilization by name (top 10)","height":21,"tile_def":{"viz":"timeseries","requests":[{"q":"top(avg:aws.ec2.cpuutilization{$scope,$region,$availability-zone} by {name},10,'mean','desc')","aggregator":"avg","style":{"palette":"warm"},"type":"line","conditional_formats":[]}]},"width":42,"created":"yyyy-mm-ddThh:mm:ss.495175+00:00","timeframe":"4h","y":0,"x":82,"legend_size":"0","type":"timeseries","legend":false}$

API Reference 上のサンプルをそのまま実行してみます。また違う結果になりましたが、やはり正常に動作していないように見えます。

> "https://app.datadoghq.com/api/v1/screen?api_key=${api_key}&application_key=${app_key}"
{"board_title":"dogapi test","read_only":false,"created":"yyyy-mm-ddThh:mm:ss.329178+00:00","modified":"yyyy-mm-ddThh:mm:ss.329191+00:00","height":768,"width":1024,"widgets":[{"url":"https://path/to/image.jpg","height":20,"width":32,"y":7,"x":32,"type":"image"}],"id": XXXXX9}$

f:id:htnosm:20170323212203p:plain

一部修正、template_variables、width、height オプション

オプション付与で実行してみた所、オプションは有効なようです。

$ dog screenboard post --template_variables "$(cat TEMPLATE_VARIABLES.json)" --width 1024 --height 768 "sb1" "ScreenBoard Test 1" "$(cat SampleScreenBoard.post.single.json)" | jq '.'
{
  "read_only": false,
  "description": "ScreenBoard Test 1",
  "title": "sb1",
  "created": "yyyy-mm-ddThh:mm:ss.222671+00:00",
  "modified": "yyyy-mm-ddThh:mm:ss.222682+00:00",
  "height": 768,
  "graphs": [
    {
      "board_id": XXXX6,
      "title_size": 13,
      "title": true,
      "title_align": "left",
      "title_text": "CPU utilization by name (top 10)",
      "height": 21,
      "tile_def": {
        "viz": "timeseries",
        "requests": [
          {
            "q": "top(avg:aws.ec2.cpuutilization{$scope,$region,$availability-zone} by {name},10,'mean','desc')",
            "aggregator": "avg",
            "style": {
              "palette": "warm"
            },
            "type": "line",
            "conditional_formats": []
          }
        ]
      },
      "width": 42,
      "timeframe": "4h",
      "y": 0,
      "x": 82,
      "legend_size": "0",
      "type": "timeseries",
      "legend": false
    }
  ],
  "template_variables": [
    {
      "default": "*",
      "prefix": "host",
      "name": "host"
    },
    {
      "default": "region:ap-northeast-1",
      "prefix": "region",
      "name": "region"
    }
  ],
  "id": XXXXX1,
  "width": 1024
}

f:id:htnosm:20170323212204p:plain

update

スクリーンボードを更新します。 post とほぼ同じ構文で、対象の screenboard_id を指定します。

usage: dog screenboard update [-h] [--template_variables TEMPLATE_VARIABLES]
                              [--width WIDTH] [--height HEIGHT]
                              screenboard_id title description [graphs]

意図した動作となりません
処理は正常終了しているように見えますが、指定値が反映されません。

pull

usage: dog screenboard pull [-h] screenboard_id filename

positional arguments:

引数 説明
screenboard_id スクリーンボードID
filename 出力ファイル名

実行例

JSON形式で出力されます。

$ board_id=169723
$ dog screenboard pull ${board_id} pull_${board_id}.json
XXXXX3 pull_XXXXX3.json
# 出力結果
$ cat pull_XXXXX3.json
{
  "board_title": "SampleScreenBoard",
  "read_only": false,
  "isIntegration": false,
  "board_bgtype": "board_graph",
  "created": "2017-03-23T16:57:56.454510+00:00",
  "original_title": "SampleScreenBoard",
  "modified": "2017-03-23T16:59:49.634253+00:00",
  "disableEditing": false,
  "height": 80,
  "width": "100%",
  "template_variables": [
    {
      "default": "*",
      "prefix": null,
      "name": "scope"
    },
・・・略
    }
  ],
  "templated": true,
  "widgets": [
    {
      "metric": "aws.ec2.host_ok",
      "text_align": "center",
      "query": "sum:aws.ec2.host_ok{$zone,$region,$account}",
      "text_size": "auto",
      "autoscale": true,
      "title": true,
      "aggregator": "max",
      "title_align": "left",
      "custom_unit": null,
      "width": 18,
      "timeframe": "1h",
      "wrapped": true,
      "legend_size": "0",
      "type": "query_value",
      "tags": [
        "$zone",
        "$region",
        "$account"
      ],
      "precision": 2,
      "title_text": "Active EC2 instances (max)",
      "padding": 8,
      "x": 20,
      "metric_type": "standard",
      "title_size": 13,
      "height": 8,
      "legend": false,
      "conditional_formats": [],
      "is_valid_query": true,
      "tile_def": {
        "text_align": "center",
        "autoscale": true,
        "custom_unit": null,
        "precision": 2,
        "viz": "query_value",
        "requests": [
          {
            "q": "sum:aws.ec2.host_ok{$scope,$region,$availability-zone}",
            "aggregator": "max",
            "conditional_formats": []
          }
        ]
      },
      "res_calc_func": "raw",
      "aggr": "sum",
      "y": 13,
      "calc_func": "raw"
    },
・・・略
    }
  ],
  "disableCog": false,
  "id": XXXXX3,
  "title_edited": false,
  "isShared": false
}$

push

JSON (pull した結果) を基に更新します。

positional arguments:

引数 説明
file 入力ファイル名。JSON

optional arguments:

ロングオプション 説明
–append_auto_text 対象タイムボードの description に日時とファイル名を追記します

append_auto_text はヘルプ上に記載はありますが、利用できません。 スクリーンボードはWebUI上 description が参照できないため、不要なオプションなのだと思います。

実行例

$ ls *${board_id}*
pull_XXXXX3.json  pull_XXXXX3.json.org
$ diff -w pull_XXXXX3.json.org pull_XXXXX3.json
22,26d21
<     },
<     {
<       "default": "*",
<       "prefix": "availability-zone",
<       "name": "availability-zone"
69c64
<             "q": "sum:aws.ec2.host_ok{$scope,$region,$availability-zone}",
---
>             "q": "sum:aws.ec2.host_ok{$scope,$region}",
104c99
<       "bgcolor": "gray",
---
>       "bgcolor": "blue",
134,135c129
<           "$region",
<           "$availability-zone"
---
>           "$region"
139c133
<             "q": "avg:aws.ec2.cpuutilization{$scope,$region,$availability-zone} by {host}",
---
>             "q": "avg:aws.ec2.cpuutilization{$scope,$region} by {host}",
166c160
<             "q": "top(avg:aws.ec2.cpuutilization{$scope,$region,$availability-zone} by {name},10,'mean','desc')",
---
>             "q": "top(avg:aws.ec2.cpuutilization{$scope,$region} by {name},10,'mean','desc')",
$ dog screenboard push pull_${board_id}.json | jq '.'
{
  "board_title": "SampleScreenBoard",
・・・略
  "id": XXXXX3,
  "title_edited": false,
  "isShared": false
}

f:id:htnosm:20170323212205p:plain

append_auto_text オプション

pull 結果に description が含まれていないため失敗します。

$ dog screenboard push --append_auto_text pull_${board_id}.json | jq '.'
Traceback (most recent call last):
  File "/usr/bin/dog", line 9, in <module>
    load_entry_point('datadog==0.15.0', 'console_scripts', 'dog')()
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/__init__.py", line 69, in main
    args.func(args)
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/screenboard.py", line 119, in _push
    screen_obj["description"] += auto_text
KeyError: 'description'
$ grep -c 'description'  pull_${board_id}.json
0

description を追記すれば動作します。また、 description を追加した状態で pull すると結果ファイルに description が含まれます。
ですが、WebUI上で作成した物には付与されないので使用しない方が良いかと思います。

$ diff pull_${board_id}.json pull_${board_id}_add_description.json
1a2
>   "description": "test",
$ dog screenboard push --append_auto_text pull_${board_id}_add_description.json | jq '.'
{
  "board_title": "SampleScreenBoard",
  "read_only": false,
  "isIntegration": false,
  "description": "test<br/>\nUpdated at mm/dd/yy hh:mm:dd from pull_XXXXX3_add_description.json (XXXXX3) on XXXXX.local",
・・・略
  "isShared": false
}
# 更新後にpull
$ dog screenboard pull ${board_id} pull_${board_id}_after.json
XXXXX3 pull_XXXXX3_after.json
$ grep -c description pull_XXXXX3.json pull_XXXXX3_after.json
pull_XXXXX3.json:0
pull_XXXXX3_after.json:1

new_file

新規でダッシュボードおよびpush用のファイルを作成します。

usage: dog screenboard new_file [-h] filename [graphs]

positional arguments:

引数 説明
filename 出力ファイル名。タイムボード名も兼ねる(説明にも記載される)。JSON
graphs グラフ定義JSON。標準入力から読み込ませる事も可能。

実行例

post して pull する動作となり、post と同じ問題が出てくるため省きます。

delete

スクリーンボードを削除します。

usage: dog screenboard delete [-h] screenboard_id

実行例

成功時のレスポンスはありません。

$ board_id=XXXXX1
$ dog screenboard delete ${board_id}
# 存在しない(削除済み) ID を指定
$ dog screenboard show ${board_id}
ERROR: Unable to find Screenboard for id XXXXX1

share | revoke

Public URL の払い出しと削除を行います。

# share
usage: dog screenboard share [-h] screenboard_id
# revoke
usage: dog screenboard revoke [-h] screenboard_id

実行例

share

PublicURL が払い出されます。再実行しても PublicURL の更新はされません。

$ board_id=XXXXX9
$ dog screenboard share ${board_id}
{"board_id": XXXXX9, "public_url": "https://p.datadoghq.com/sb/XXXXXXXXX-YYYYY5b001"}
$ dog screenboard share ${board_id}
{"board_id": XXXXX9, "public_url": "https://p.datadoghq.com/sb/XXXXXXXXX-YYYYY5b001"}

f:id:htnosm:20170323212206p:plain

ダッシュボードリスト(Dashboards) 上は share が表示されます。

f:id:htnosm:20170323212207p:plain

revoke

払い出し済みの PublicURL を削除します。
削除後に再度払い出し(share)を行うと別URLが払い出されます。

$ dog screenboard revoke ${board_id}
null
$ dog screenboard revoke ${board_id}
{"errors": ["Unable to find shared Screenboard for id XXXXX9"]}
# 再払い出し
$ dog screenboard share ${board_id}
{"board_id": XXXXX9, "public_url": "https://p.datadoghq.com/sb/XXXXXXXXX-YYYYY5c178"}
$

screenboard編まとめ

指定しているグラフの定義が悪いのか、想定した動作を確認できませんでした。
pull -> push の流れは利用できるので、現状はWebUIで作成したスクリーンボードを用意した後、定義のコード管理を行うことになりそうです。

Datadog (dogコマンド) timeboard編

Datadog公式のツール dog 使用方法まとめ timeboard 編です。

f:id:htnosm:20170323212147p:plain


目次


timeboard Modes

ダッシュボード(TimeBoard) 操作を行います。

f:id:htnosm:20170323212148p:plain

サブコマンド 説明
show タイムボード情報出力
show_all タイムボードリスト出力
post タイムボード新規作成
update タイムボード更新
pull タイムボード定義取得
pull_all 全タイムボードの定義取得
push タイムボード更新
new_file タイムボードの新規作成と定義取得 (post後にpull)
web_view タイムボードを規定ブラウザで開く
delete タイムボードの削除

JSON形式で定義することになりますが、 1からJSONを作るのは中々難しいため、 参照用のタイムボードを用意して確認します。

  • サンプルタイムボード

f:id:htnosm:20170323212149p:plain

show

タイムボード定義を出力します。JSON形式で出力されます。

usage: dog timeboard show [-h] timeboard_id

実行結果

$ dash_id=XXXXXX
$ dog timeboard show ${dash_id} | jq '.'
{
  "dash": {
    "read_only": false,
    "description": "sample timeboard",
    "title": "SampleTimeBoard",
    "created": "yyyy-mm-ddThh:mm:ss.549586+00:00",
    "modified": "yyyy-mm-ddThh:mm:ss.731078+00:00",
    "graphs": [
      {
        "definition": {
          "viz": "timeseries",
          "requests": [
            {
              "q": "max:system.cpu.user{*} by {host}",
              "conditional_formats": [],
              "type": "line"
            }
          ],
          "autoscale": true
        },
        "title": "system.cpu.user"
      },
・・・略
      }
    ],
    "id": XXXXXX
  },
  "url": "/dash/XXXXXX/sampletimeboard",
  "resource": "/api/v1/dash/XXXXXX"
}

show_all

タイムボードリストを出力します。全タイムボードが対象となり、絞り込みのオプションはありません。

usage: dog timeboard show_all [-h]

実行結果

JSON形式で出力したい場合は raw オプションを使用します。

$ dog timeboard show_all
XXXXX8  /api/v1/dash/XXXXX8 Hoge's TimeBoard    created by user@example.com
XXXXX9  /api/v1/dash/XXXXX9 SampleTimeBoard sample timeboard
# rawオプション
$ dog --raw timeboard show_all | jq '.'
{
  "dashes": [
    {
      "read_only": false,
      "resource": "/api/v1/dash/XXXXX8",
      "description": "created by user@example.com",
      "created": "yyyy-mm-ddThh:mm:ss.111559+00:00",
      "title": "Hoge's TimeBoard",
      "modified": "yyyy-mm-ddThh:mm:ss.062052+00:00",
      "id": "XXXXX8"
    },
・・・略
    }
  ]
}

post

タイムボードを作成します。

usage: dog timeboard post [-h] [--template_variables TEMPLATE_VARIABLES]
                          title description [graphs]

(恐らく)複数グラフ未対応です
オブジェクトをそのまま連ねた場合、 JSON 読み込み時点でエラー、 配列化して JSON としては正しい状態にした場合、api呼び出し時点でエラーとなるようです。

positional arguments:

引数 説明
title タイムボード名
description タイムボードの説明
graphs グラフ定義JSON。標準入力から読み込ませる事も可能。

optional arguments:

ロングオプション 説明
–template_variables テンプレート変数定義JSON

実行例(エラー)

show コマンド結果JSONの使用

show コマンドで出力した結果をそのまま使用してもエラーとなります。graphs 以外の不要な key が含まれているためだと思います。

$ dog --raw timeboard post "tb1" "TimeBoard Test 1" "$(cat SampleTimeBoard.json)"
ERROR: The 'title' parameter is required for all graphs

show コマンド結果JSONの使用(graphs配下)

graphs 配下を抜き出した物を使用してみた所、JSONのパースエラーとなりました。

$ dash_id=XXXXXX 
$ dog timeboard show ${dash_id} > SampleTimeBoard.json
$ dog timeboard post "tb1" "TimeBoard Test 1" "$(cat SampleTimeBoard.post.json)"
Traceback (most recent call last):
  File "/usr/bin/dog", line 9, in <module>
    load_entry_point('datadog==0.15.0', 'console_scripts', 'dog')()
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/__init__.py", line 69, in main
    args.func(args)
  File "/usr/lib/python2.7/site-packages/datadog/dogshell/timeboard.py", line 236, in _post
    raise Exception('bad json parameter')
Exception: bad json parameter
  • 使用したファイル抜粋
      {
        "definition": {
          "viz": "timeseries",
          "requests": [
            {
              "q": "max:system.cpu.user{*} by {host}",
              "conditional_formats": [],
              "type": "line"
            }
          ],
          "autoscale": true
        },
        "title": "system.cpu.user"
      },
      {
        "definition": {
・・・略
      },

show コマンド結果JSONの使用 + 配列

オブジェクトが並ぶ形式で JSON として不正なため、配列としてみた所、 ‘title’ パラメータが無い旨のエラーメッセージとなりました。

$ dog timeboard post "tb1" "TimeBoard Test 1" "$(cat SampleTimeBoard.post.array.json)"
ERROR: The 'title' parameter is required for all graphs
  • 使用したファイル抜粋
      [{
        "definition": {
          "viz": "timeseries",
          "requests": [
            {
              "q": "max:system.cpu.user{*} by {host}",
              "conditional_formats": [],
              "type": "line"
            }
          ],
          "autoscale": true
        },
        "title": "system.cpu.user"
      },
      {
        "definition": {
・・・略
      }]

実行例

複数グラフを指定すると上手く動作しないようなので、グラフを1つにして実行した所、成功しました。
レスポンスは JSON 形式です。

$ dog timeboard post "tb1" "TimeBoard Test 1" "$(cat SampleTimeBoard.post.single.json)"
{"dash": {"read_only": false, "description": "TimeBoard Test 1", "title": "tb1", "created": "yyyy-mm-ddThh:mm:ss.260935+00:00", "modified": "yyyy-mm-ddThh:mm:ss.321740+00:00", "graphs": [{"definition": {"viz": "timeseries", "requests": [{"q": "max:system.cpu.user{*} by {host}", "conditional_formats": [], "type": "line"}], "autoscale": true}, "title": "system.cpu.user"}], "id": XXXXX6}, "url": "/dash/XXXXX6/tb1", "resource": "/api/v1/dash/XXXXX6"}
  • 使用したファイル
      {
        "definition": {
          "viz": "timeseries",
          "requests": [
            {
              "q": "max:system.cpu.user{*} by {host}",
              "conditional_formats": [],
              "type": "line"
            }
          ],
          "autoscale": true
        },
        "title": "system.cpu.user"
      }

f:id:htnosm:20170323212150p:plain

template_variables

テンプレート定義変数を付与できます。JSONのファイルを使用した実行例です。

$ cat TEMPLATE_VARIABLES.json
[{
  "name": "host",
  "prefix": "host",
  "default": "*"
},
{
  "name": "region",
  "prefix": "region",
  "default": "region:ap-northeast-1"
}]
$ dog timeboard post --template_variables "$(cat TEMPLATE_VARIABLES.json)" "tb2" "TimeBoard Test 2" "$(cat SampleTimeBoard.post.single.json)" | jq '.'
{
  "dash": {
    "read_only": false,
    "description": "TimeBoard Test 2",
    "title": "tb2",
    "created": "yyyy-mm-ddThh:mm:ss.444179+00:00",
    "modified": "yyyy-mm-ddThh:mm:ss.497676+00:00",
    "graphs": [
      {
        "definition": {
          "viz": "timeseries",
          "requests": [
            {
              "q": "max:system.cpu.user{*} by {host}",
              "conditional_formats": [],
              "type": "line"
            }
          ],
          "autoscale": true
        },
        "title": "system.cpu.user"
      }
    ],
    "template_variables": [
      {
        "default": "*",
        "prefix": "host",
        "name": "host"
      },
      {
        "default": "region:ap-northeast-1",
        "prefix": "region",
        "name": "region"
      }
    ],
    "id": XXXXX9
  },
  "url": "/dash/XXXXX9/tb2",
  "resource": "/api/v1/dash/XXXXX9"
}

f:id:htnosm:20170323212151p:plain

update

タイムボードを更新します。 post とほぼ同じ構文で、対象の timeboard_id を指定します。

usage: dog timeboard update [-h] [--template_variables TEMPLATE_VARIABLES]
                            timeboard_id title description [graphs]

変更がない場合でも title, description の指定は必須です。(idのみにして欲しい所ではあります)
graphs は post ではエラーとなりましたが、 update は複数指定が成功します。(後述)

実行例(エラー)

post コマンドで利用したJSON

show コマンドで出力した結果をそのまま使用してもエラーとなりました。

$ dog timeboard update --template_variables "$(cat TEMPLATE_VARIABLES.json)" ${dash_id} "tb1" "TimeBoard Test 1 Add graph" "$(cat SampleTimeBoard.post.single.json)" | jq '.'
ERROR: The 'graphs' parameter is required to be a list

実行例

post コマンドで利用したJSON + 配列[]

JSONを配列化した所、成功しました。 post と update で何故か受け付ける形式が異なります。

$ dash_id=XXXXX6
$ dog timeboard update --template_variables "$(cat TEMPLATE_VARIABLES.json)" ${dash_id} "tb1" "TimeBoard Test 1 Add graph" "$(cat SampleTimeBoard.update.json)" | jq '.'
{
  "dash": {
    "read_only": false,
    "description": "TimeBoard Test 1 Add graph",
    "title": "tb1",
    "created": "yyyy-mm-ddThh:mm:ss.260935+00:00",
    "modified": "yyyy-mm-ddThh:mm:ss.797204+00:00",
    "graphs": [
      {
        "definition": {
          "viz": "query_value",
          "requests": [
            {
              "q": "avg:system.load.5{*}",
              "aggregator": "max",
              "conditional_formats": [
                {
                  "palette": "white_on_yellow",
                  "value": "5",
                  "comparator": ">"
                },
                {
                  "palette": "white_on_red",
                  "value": "10",
                  "comparator": ">"
                }
              ]
            }
          ],
          "autoscale": true,
          "text_align": "right",
          "precision": "1"
        },
        "title": "system.load.5"
      }
    ],
    "template_variables": [
      {
        "default": "*",
        "prefix": "host",
        "name": "host"
      },
      {
        "default": "region:ap-northeast-1",
        "prefix": "region",
        "name": "region"
      }
    ],
    "id": XXXXX6
  },
  "url": "/dash/XXXXX6/tb1",
  "resource": "/api/v1/dash/XXXXX6"
}
  • 使用したファイル
$ cat SampleTimeBoard.update.json
      [{
        "definition": {
          "viz": "query_value",
          "requests": [
            {
              "q": "avg:system.load.5{*}",
              "aggregator": "max",
              "conditional_formats": [
                {
                  "palette": "white_on_yellow",
                  "value": "5",
                  "comparator": ">"
                },
                {
                  "palette": "white_on_red",
                  "value": "10",
                  "comparator": ">"
                }
              ]
            }
          ],
          "autoscale": true,
          "text_align": "right",
          "precision": "1"
        },
        "title": "system.load.5"
      }]

f:id:htnosm:20170323212152p:plain

show コマンド結果JSONの使用 + 配列[]

配列形式が受け付けられたので複数グラフも試した所、成功しました。

$ dog timeboard update ${dash_id} "tb1" "TimeBoard Test 1 Add graph array" "$(cat SampleTimeBoard.post.array.json)" | jq '.'
{
  "dash": {
    "read_only": false,
    "description": "TimeBoard Test 1 Add graph array",
    "title": "tb1",
    "created": "yyyy-mm-ddThh:mm:ss.260935+00:00",
    "modified": "yyyy-mm-ddThh:mm:ss.343722+00:00",
    "graphs": [
      {
        "definition": {
          "viz": "timeseries",
          "requests": [
            {
              "q": "max:system.cpu.user{*} by {host}",
              "conditional_formats": [],
              "type": "line"
            }
          ],
          "autoscale": true
        },
        "title": "system.cpu.user"
      },
・・・略
      }
    ],
    "template_variables": [],
    "id": XXXXX6
  },
  "url": "/dash/XXXXX6/tb1",
  "resource": "/api/v1/dash/XXXXX6"
}

f:id:htnosm:20170323212153p:plain

pull

usage: dog timeboard pull [-h] timeboard_id filename

positional arguments:

引数 説明
timeboard_id タイムボードID
filename 出力ファイル名

実行例

JSON形式で出力されます。

$ dash_id=XXXXX9
$ dog timeboard pull ${dash_id} pull_${dash_id}.json
XXXXX9 pull_XXXXX9.txt
  • 出力結果
$ cat pull_${dash_id}.txt
{
  "read_only": false,
  "description": "TimeBoard Test 2",
  "title": "tb2",
  "created": "yyyy-mm-ddThh:mm:ss.444179+00:00",
  "modified": "yyyy-mm-ddThh:mm:ss.497676+00:00",
  "graphs": [
    {
      "definition": {
        "viz": "timeseries",
        "requests": [
          {
            "q": "max:system.cpu.user{*} by {host}",
            "conditional_formats": [],
            "type": "line"
          }
        ],
        "autoscale": true
      },
      "title": "system.cpu.user"
    }
  ],
  "template_variables": [
    {
      "default": "*",
      "prefix": "host",
      "name": "host"
    },
    {
      "default": "region:ap-northeast-1",
      "prefix": "region",
      "name": "region"
    }
  ],
  "id": XXXXX9
}

pull_all

usage: dog timeboard pull_all [-h] pull_dir

positional arguments:

引数 説明
pull_dir 出力ディレクトリ名

実行例

指定ディレクトリへ各タイムボードの JSON を出力します。
ディレクトリは存在しない場合作成、存在する場合は上書きされます。

$ dog timeboard pull_all out_dir
XXXXX8 out_dir/hoge.json
XXXXX9 out_dir/sampletimeboard.json
XXXXX6 out_dir/tb1.json
XXXXX9 out_dir/tb2.json

push

JSON (pull した結果) を基に更新します。

usage: dog timeboard push [-h] [--append_auto_text] file [file ...]

positional arguments:

引数 説明
file 入力ファイル名。JSON

optional arguments:

ロングオプション 説明
–append_auto_text 対象タイムボードの description に日時とファイル名を追記します

実行例

pull 結果ファイルを push

pull で出力した JSON を編集して、そのまま push できます。

$ dog timeboard push pull_XXXXX9.json | jq '.'
{
  "dash": {
    "read_only": false,
    "description": "TimeBoard Test 2 push",
    "title": "tb2",
    "created": "yyyy-mm-ddThh:mm:ss.444179+00:00",
    "modified": "yyyy-mm-ddThh:mm:ss.050260+00:00",
    "graphs": [
      {
        "definition": {
          "viz": "timeseries",
          "requests": [
            {
              "q": "max:system.cpu.user{*} by {host}",
              "conditional_formats": [],
              "type": "line"
            }
          ],
          "autoscale": true
        },
        "title": "system.cpu.user"
      }
    ],
    "template_variables": [
      {
        "default": "*",
        "prefix": "host",
        "name": "host"
      },
      {
        "default": "region:ap-northeast-1",
        "prefix": "region",
        "name": "region"
      }
    ],
    "id": XXXXX9
  },
  "url": "/dash/XXXXX9/tb2",
  "resource": "/api/v1/dash/XXXXX9"
}

f:id:htnosm:20170323212154p:plain

append_auto_text オプション

description に更新日時とファイル名、実行ホストが追記されます。 改行の <br> は改行として認識されていないようです。

$ dog timeboard push --append_auto_text pull_XXXXX9.json | jq '.'

f:id:htnosm:20170323212155p:plain

new_file

新規でダッシュボードおよびpush用のファイルを作成します。

usage: dog timeboard new_file [-h] filename [graphs]

positional arguments:

引数 説明
filename 出力ファイル名。タイムボード名も兼ねる(説明にも記載される)。JSON
graphs グラフ定義JSON。標準入力から読み込ませる事も可能。

実行例

post して pull する動作です。
タイムボード作成処理は post と同様の処理となっているため、グラフを1つにしたJSONで実行します。 filename で指定した JSON ファイルが生成されます。

$ dog timeboard new_file NewFile.json "$(cat SampleTimeBoard.post.single.json)"
XXXXX3 NewFile.json
{"dash": {"read_only": false, "description": "Description for NewFile.json", "title": "NewFile.json", "created": "yyyy-mm-ddThh:mm:ss.957193+00:00", "modified": "yyyy-mm-ddThh:mm:ss.028761+00:00", "graphs": [{"definition": {"viz": "timeseries", "requests": [{"q": "max:system.cpu.user{*} by {host}", "conditional_formats": [], "type": "line"}], "autoscale": true}, "title": "system.cpu.user"}], "id": XXXXX3}, "url": "/dash/XXXXX3/newfilejson", "resource": "/api/v1/dash/XXXXX3"}
$ cat NewFile.json
{
  "read_only": false,
  "description": "Description for NewFile.json",
  "title": "NewFile.json",
  "created": "yyyy-mm-ddThh:mm:ss.957193+00:00",
  "modified": "yyyy-mm-ddThh:mm:ss.028761+00:00",
  "graphs": [
    {
      "definition": {
        "viz": "timeseries",
        "requests": [
          {
            "q": "max:system.cpu.user{*} by {host}",
            "conditional_formats": [],
            "type": "line"
          }
        ],
        "autoscale": true
      },
      "title": "system.cpu.user"
    }
  ],
  "id": XXXXX3
}

タイムボード件名と説明には filename が使用されます。

f:id:htnosm:20170323212156p:plain

web_view

ブラウザでダッシュボードを開きます。

usage: dog timeboard web_view [-h] file

positional arguments:

引数 説明
file 入力ファイル名。JSON

json.load(file)['id']timeboard_id が取得できれば良いので、下のような形式のJSONがあれば実行可能です。

'{ "id": XXXXX3 }'

実行例

レスポンスはありません。規定のブラウザでタイムボードのURLを開きます。

$ dog --raw timeboard web_view NewFile.json
$
# 存在しない id 指定
% diff NewFile.json NewFile_noid.json
23c23
<   "id": XXXXX3
---
>   "id": 200003
$ dog --raw timeboard web_view NewFile_noid.json
$
  • 存在するID

f:id:htnosm:20170323212157p:plain

  • 存在しないID

f:id:htnosm:20170323212158p:plain

delete

タイムボードを削除します。

usage: dog timeboard delete [-h] timeboard_id

実行例

成功時のレスポンスはありません。

$ dash_id=265413
$ dog --raw timeboard delete ${dash_id}
# 存在しない(削除済み) ID を指定
$ dog timeboard delete ${dash_id}
ERROR: No dashboard matches that dash_id.

timeboard編まとめ

pull -> push の流れを利用すると定義のコード管理が行いやすいと思います。
似たような名前のサブコマンドが多く困惑しました。 dog コマンドとしては show[all],pull[all],push,delete だけに絞っても、必要十分なのではと思います。

Datadog (dogコマンド) monitor編

Datadog公式のツール dog 使用方法まとめ monitor 編です。

f:id:htnosm:20170320185036p:plain


目次


monitor Modes

Monitor 操作を行います。

サブコマンド 説明
post モニター作成
update モニター更新
show モニター情報出力
show_all モニター一覧出力
delete モニター削除
mute_all 全モニターの mute
unmute_all 全モニターの unmute
mute モニターの mute
unmute モニターの unmute

post

モニターを作成します。

usage: dog monitor post [-h] [--name NAME] [--message MESSAGE]
                        [--options OPTIONS]
                        type query

positional arguments:

引数 説明
type モニター種類。"metric alert"、"service check"、"event alert" のいずれかを指定。
query クエリ文字列。 type により指定項目が異なる。

query に関しては、dog のヘルプには詳細記載が無いため、API Reference などで確認します。 記載方法は多岐に渡るため今回詳細は割愛します。

恐らくダッシュボード上でグラフを生成して、Edit から JSON 参照するのが最も簡単に作成する方法だと思います。 メトリクスのグラフはジェネレータのような Metric Explorer が用意されていますが、一旦グラフを生成しないと JSON の参照ができません。

optional arguments:

ロングオプション 説明
–name モニター件名
–message 通知時のメッセージ
–options モニターオプション。 共通オプションと type 固有オプションが存在。 JSON文字列で指定。

options に関しても、dog のヘルプには詳細記載が無いため、API Reference などで確認します。 設定項目が多いため今回詳細は割愛します。

実行例

オプション無し

JSONで返却されます。 件名にはクエリ文字列が入ります。

metric alert
$ dog monitor post "metric alert" 'avg(last_5m):max:system.cpu.user{*} by {host} >= 50' | jq '.'
{
  "multi": true,
  "name": "**system.cpu.user** over ***** was **>= 50.0** on average during the **last 5m**.",
  "tags": [],
  "deleted": null,
  "type": "metric alert",
  "created_at": NNNNNNNNNN000,
  "created": "yyyy-MM-ddThh:mm:dd.050779+00:00",
  "org_id": XXXX3,
  "modified": "yyyy-MM-ddThh:mm:dd.050779+00:00",
  "options": {
    "notify_audit": false,
    "locked": false,
    "silenced": {},
    "require_full_window": true,
    "new_host_delay": 300,
    "notify_no_data": false
  },
  "overall_state_modified": null,
  "overall_state": "No Data",
  "query": "avg(last_5m):max:system.cpu.user{*} by {host} >= 50",
  "message": "",
  "creator": {
    "email": "user@example.com",
    "handle": "user@example.com",
    "id": XXXXX8,
    "name": "User Name"
  },
  "id": XXXXXX1
}

f:id:htnosm:20170320185037p:plain

service check
dog monitor post "service check" '"datadog.agent.up".over("*").by("host").last(5).count_by_status()'

f:id:htnosm:20170320185038p:plain

event alert
$ dog monitor post "event alert" 'events("sources:users priority:all").rollup("count").last("5m") > 0'

f:id:htnosm:20170320185039p:plain

name オプション

モニター名を指定します。

dog monitor post --name "MonitorTest1" "metric alert" 'avg(last_5m):max:system.cpu.user{*} by {host} >= 50'

f:id:htnosm:20170320185040p:plain

message オプション

モニター通知文を指定します。

$ dog monitor post --message "alert message to @hoge@example.com" "metric alert" 'avg(last_5m):max:system.cpu.user{*} by {host} >= 50' | jq '.'

f:id:htnosm:20170320185041p:plain

options オプション

mute 状態(Forever)で登録する場合の例です。共通オプションの silenced を指定します。

$ dog monitor post --name "MonitorTest4" --message "Test4: alert message to @hoge@example.com" --options '{"silenced": "{\"*\": null}"}' "metric alert" 'avg(last_5m):max:system.cpu.user{*} by {host} >= 50'

f:id:htnosm:20170320185042p:plain

ファイル形式

ファイル形式での読込は未対応のため、実行時には展開する必要があります。

$ cat param.json
{"no_data_timeframe": 300}
$ dog monitor post --name "MonitorTest4" --message "Test4: alert message to @hoge@example.com" --options "$(cat param.json)" "metric alert" 'avg(last_5m):max:system.cpu.user{*} by {host} >= 50'

update

モニターを更新します。post とほぼ同じ構文で、対象の MonitorId を指定します。

usage: dog monitor update [-h] [--name NAME] [--message MESSAGE]
                          [--options OPTIONS]
                          monitor_id type query

変更がない場合でも type,query の指定は必須です。(idのみにして欲しい所ではあります)

実行例

モニター件名を更新する例です。

$ monitor_id=XXXXXXX
$ dog monitor update --name "UpdateMonitorTest" ${monitor_id} "metric alert" 'avg(last_5m):max:system.cpu.user{*} by {host} >= 50'
  • 実行前後比較
$ diff monitor.json.before monitor.json.after
3c3
<   "name": "**system.cpu.user** over ***** was **>= 50.0** on average during the **last 5m**.",
---
>   "name": "UpdateMonitorTest",
10c10
<   "modified": "yyyy-MM-ddThh:mm:dd.286774+00:00",
---
>   "modified": "yyyy-MM-ddThh:mm:dd.597438+00:00",

show

指定 monitor_id の情報を出力します。

usage: dog monitor show [-h] monitor_id

実行例

JSON 形式で出力されます。

$ monitor_id=XXXXXXX
$ dog monitor show ${monitor_id} | jq '.'
{
  "multi": true,
  "name": "UpdateMonitorTest",
  "tags": [],
  "deleted": null,
  "type": "metric alert",
  "created_at": NNNNNNNNNN000,
  "created": "yyyy-MM-ddThh:mm:dd.050779+00:00",
  "org_id": XXXX3,
  "modified": "yyyy-MM-ddThh:mm:dd.597438+00:00",
  "options": {
    "notify_no_data": false,
    "notify_audit": false,
    "locked": false,
    "new_host_delay": 300,
    "silenced": {}
  },
  "overall_state_modified": "yyyy-MM-ddThh:mm:dd.971827+00:00",
  "overall_state": "OK",
  "query": "avg(last_5m):max:system.cpu.user{*} by {host} >= 50",
  "message": "",
  "creator": {
    "email": "user@example.com",
    "handle": "user@example.com",
    "id": XXXXX8,
    "name": "User Name"
  },
  "id": XXXXXX5
}

show_all

全モニター情報を出力します。タグ等による絞り込みは未サポートです。(APIではタグによる絞り込みが可能なようです)

usage: dog monitor show_all [-h]

実行例

整形された状態で出力されます。tsv形式に似ていますが、区切りタブの数が異なったりと完全なtsvにはなっていません。
raw オプションを使用して JSON で出力した方が扱いやすいと思います。

$ dog monitor show_all
XXXXXX7     MonitorTest1    {u'notify_audit': False, u'locked': False, u'silenced': {}, u'require_full_window': True, u'new_host_delay': 300, u'notify_no_data': False} XXXX3   avg(last_5m):max:system.cpu.user{*} by {host} >= 50  metric alert
XXXXXX4 alert message to @hoge@example.com  **system.cpu.user** over ***** was **>= 50.0** on average during the **last 5m**.    {u'notify_audit': False, u'locked': False, u'silenced': {}, u'require_full_window': True, u'new_host_delay': 300, u'notify_no_data': False} XXXX3   avg(last_5m):max:system.cpu.user{*} by {host} >= 50  metric alert
・・・略
# raw オプション
#dog --raw monitor show_all

delete

指定 monitor_id を削除します。

usage: dog monitor delete [-h] monitor_id

実行例

レスポンスはありません。(raw オプションを付けても同様です)

$ monitor_id=XXXXXX5
$ dog monitor delete ${monitor_id}
$ dog monitor show ${monitor_id}
ERROR: Monitor not found
$ monitor_id=XXXXXX7
$ dog --raw monitor delete ${monitor_id}
$ dog --raw monitor show ${monitor_id}
ERROR: Monitor not found

mute_all | unmute_all

全モニターを mute | unmute (無効化 | 無効化解除)します。 影響が大きいコマンドなので基本利用しない方が良いかと思います。
Monitor 画面右上の Mute All" ボタン押下時と同様の動作です。

# mute_all
usage: dog monitor mute_all [-h]
# unmute_all
usage: dog monitor unmute_all [-h]

実行例

mute_all

$ dog monitor mute_all | jq '.'
{
  "recurrence": null,
  "end": null,
  "parent_id": null,
  "monitor_id": null,
  "start": NNNNNNNNN3,
  "disabled": false,
  "canceled": null,
  "creator_id": XXXXX8,
  "scope": [
    "*"
  ],
  "active": true,
  "timezone": "UTC",
  "message": null,
  "monitor_name": null,
  "id": XXXXXXXX4,
  "updater_id": null
}

f:id:htnosm:20170320185043p:plain

unmute_all

レスポンスはありません。(raw オプションを付けても同様です)

$ dog monitor unmute_all | jq '.'
$

f:id:htnosm:20170320185044p:plain

通知

実行者と全員(@all)に通知されます。

f:id:htnosm:20170320185045p:plain

mute | unmute

moniter_id 指定で mute | unmute (無効化 | 無効化解除)します。

# mute
usage: dog monitor mute [-h] [--scope SCOPE] [--end END] monitor_id
# unmute
usage: dog monitor unmute [-h] [--scope SCOPE] [--all_scopes] monitor_id

optional arguments:

ロングオプション 説明
–scope 適用対象タグ
–end muteのみ。終了日時を指定。POSIX timestamp
–all_scopes unmuteのみ。全スコープを対象とする

実行例

mute|unmute

いずれも JSON 形式でのレスポンスです。

$ monitor_id=XXXXXX5
$ dog monitor mute ${monitor_id} | jq '.'
{
  "multi": true,
  "name": "MonitorTest4",
  "tags": [],
  "deleted": null,
  "created_at": NNNNNNNNNN000,
  "created": "yyyy-MM-ddThh:mm:dd.596409+00:00",
  "org_id": XXXX3,
  "modified": "yyyy-MM-ddThh:mm:dd.596409+00:00",
  "options": {
    "notify_audit": false,
    "locked": false,
    "silenced": {
      "*": null
    },
    "no_data_timeframe": 300,
    "require_full_window": true,
    "new_host_delay": 300,
    "notify_no_data": false
  },
  "overall_state_modified": "yyyy-MM-ddThh:mm:dd.037144+00:00",
  "overall_state": "OK",
  "query": "avg(last_5m):max:system.cpu.user{*} by {host} >= 50",
  "message": "Test4: alert message to @hoge@example.com",
  "type": "metric alert",
  "id": XXXXXX5
}

scope オプション

$ monitor_id=XXXXXX1
$ dog monitor mute --scope "host:i-XXXXXX" ${monitor_id} | jq '.'

mute 設定状況は [Monitors] → [Manage Downtime] で確認できます。

f:id:htnosm:20170320185046p:plain

mute→unmuteでscopeを変える事は不可

全体を mute 後、 特定の scope のみを unmute することはできませんでした。

$ monitor_id=XXXXXX1
$ dog monitor unmute --scope "host:i-XXXXXX" ${monitor_id} | jq '.'
ERROR: metric alert "CPU Credit Balance on {{host.name}}" is already unmuted on host:i-XXXXXX

end オプション(mute)

mute終了時刻を指定します。

monitor_id= XXXXXX1
dog monitor mute --end $(date -v 1h +'%s') ${monitor_id} | jq '.'

f:id:htnosm:20170320190610p:plain

all_scopes オプション(unmute)

個別の scope が設定されている mute 状態 monitor 全てを unmute します。

  • 実行前の状態

f:id:htnosm:20170320190609p:plain

オプション無しだとエラーが返りますが、 all_scopes を付与することによりまとめて unmute (無効化解除) が行えます。

$ monitor_id=XXXXXX1
$ dog monitor unmute ${monitor_id} | jq '.'
ERROR: metric alert "CPU Credit Balance on {{host.name}}" is already unmuted
$ dog monitor unmute --all_scopes ${monitor_id} | jq '.'

実行時エラー

  • mute(unmute) 済みを mute(unmute)
ERROR: metric alert "MonitorTest4" is already muted
ERROR: metric alert "MonitorTest4" is already unmuted
  • 存在しない monitor_id 指定
ERROR: Monitor not found

Query と Option については別の機会に整理したいと思います。

Datadog (dogコマンド) event編

Datadog公式のツール dog 使用方法まとめ event 編です。

f:id:htnosm:20170320141611p:plain


目次


event Modes

Event操作を行います。 表示箇所は同じですが、commentは文面のみの編集に対し、 event は文面に加え優先度やタイプ等の設定が行なえます。

f:id:htnosm:20170320141612p:plain

サブコマンド 説明
post イベント送信
show イベント詳細情報取得
stream イベント一覧取得

post

イベント送信(投稿) を行います。

usage: dog event post [-h] [--date_happened DATE_HAPPENED] [--handle HANDLE]
                      [--priority PRIORITY]
                      [--related_event_id RELATED_EVENT_ID] [--tags TAGS]
                      [--host HOST] [--no_host] [--device DEVICE]
                      [--aggregation_key AGGREGATION_KEY] [--type TYPE]
                      [--alert_type ALERT_TYPE]
                      title [message]

positional arguments:

引数 説明
title 件名。文字数制限=100
message 本文。文字数制限=4,000 MarkDownサポート。標準入力から読み込ませる事も可能。

optional arguments:

ロングオプション 説明
–date_happened イベント発生日時。POSIX。(デフォルト現在日時)
–handle ユーザ名。未指定の場合汎用APIユーザ。
–priority 優先度。"normal" or “low” (デフォルト normal)
–date_happened イベント発生日時。POSIX。(デフォルト現在日時)
–related_event_id 親イベントID。未指定の場合は親イベントとして投稿。
–tags タグのリスト(カンマ区切り)
–host 関連ホスト名(デフォルトはローカルホスト名)
–no_host 関連ホスト無し(–hostオプションは無視される)
–device 関連デバイス名 (e.g. eth0, /dev/sda1)
–aggregation_key 集計用キー。文字数制限=100
–type イベントタイプ (e.g. nagios, jenkins, etc.)
–alert_type アラートタイプ。"error" or “warning” or “info” or “success” (デフォルト info)

実行例

オプション無しで実行

# message指定
$ dog event post "EventTest1" "With arguments."
EventTest1 With arguments.  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXXX
# message未指定(標準入力から)
$ echo "With stdin." | dog event post "EventTest2"
EventTest2 With stdin.
  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=YYYYYYYYYYYYYYYYYY

f:id:htnosm:20170320141613p:plain

文字数制限

title に “A” x100 と最後に “b"、 message に "C” x4,000 と最後に “d” の文字列を投げた結果、 制限超過した物は切り捨てられました。 実行時エラーは特に無く、コマンド自体は正常終了です。

f:id:htnosm:20170320141616p:plain

マルチバイト

同様に日本語でも実行してみます。 title に “う” x100 と最後に “え"、 message に "お” x4,000 と最後に “か” の文字列を投げた結果、 文字数制限数より少ない部分で切り捨てられました。

  • 登録できたマルチバイト文字列数
    • title = 33 文字
    • message = 1333 文字

f:id:htnosm:20170320141617p:plain

date_happened オプション

効きません。 過去日時、未来日時、いずれも受け付けず、現在日時となります。

$ _DATE=$(date +'%s') ; echo ${_DATE} ; dog --raw event post "EventTest3 now" "With now"
1489859130
{"status": "ok", "event": {"date_happened": 1489859131, "handle": null, "title": "EventTest3 now", "url": "https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX8", "text": "With now", "tags": null, "priority": null, "related_event_id": null, "id": XXXXXXXXXXXXXXXXX8}}
# 過去日時指定
$ _DATE=$(date -v -1H '+%s') ; echo ${_DATE} ; dog --raw event post --date_happened ${_DATE} "EventTest3" "With date_happened (past)"
1489855533
{"status": "ok", "event": {"date_happened": 1489859134, "handle": null, "title": "EventTest3", "url": "https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX5", "text": "With date_happened (past)", "tags": null, "priority": null, "related_event_id": null, "id": XXXXXXXXXXXXXXXXX5}}
# 未来日時指定
$ _DATE=$(date -v +1H '+%s') ; echo ${_DATE} ; dog --raw event post --date_happened ${_DATE} "EventTest3" "With date_happened (future)"
1489862735
{"status": "ok", "event": {"date_happened": 1489859136, "handle": null, "title": "EventTest3", "url": "https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX6", "text": "With date_happened (future)", "tags": null, "priority": null, "related_event_id": null, "id": XXXXXXXXXXXXXXXXX6}}

f:id:htnosm:20170320141614p:plain

  • TODO?

f:id:htnosm:20170320141615p:plain

handle オプション

(多分)効きません。
指定無し、アカウント登録済みユーザ、未登録ユーザで試しましたが、いずれも同じ結果でした。 dog コマンドのレスポンス上は返ってきていますが、 API Reference 見た所 handle オプション自体存在しませんでした。

$ dog event post "EventTest4" "Default Handle."
EventTest4 Default Handle.  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX4
$ dog event post --handle "user@expample.com" "EventTest4" "Add Handle."
EventTest4 Add Handle.  (user@expample.com)
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX3
$ dog event post --handle "hoge@example.com" "EventTest4" "Add Handle. (NoAccount)"

EventTest4 Add Handle. (NoAccount)  (hoge@example.com)
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX8

f:id:htnosm:20170320141618p:plain

priority オプション

Priority を指定します。 Normal,Low 以外でも特にエラーにはならず、投稿できました。(Normalになります)
そのため、現状 Low を指定したい場合のみに使用することになります。

# Normal
$ dog event post --priority normal "EventTest5" "priority normal"
EventTest5 priority normal  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX3
# Low
$ dog event post --priority low "EventTest5" "priority low"
EventTest5 priority low  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX5
# Normal,Low 以外
$ dog event post --priority high "EventTest5" "priority high"
EventTest5 priority high  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX0

f:id:htnosm:20170320141619p:plain

(多分)使えません。
親イベントIDを指定すれば良いのかと思いましたが、JSON不正のエラーになりました。
API Reference 見た所 related_event_id オプションが存在しないようでした。(例では見かけましたが)
comment のリプライ機能、もしくは、後述 aggregation_key オプションの誤りでしょうか。

$ dog event post "EventTest5" "Parent"
EventTest5 Parent  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX2
$ EVENT_ID=XXXXXXXXXXXXXXXXX2
$ dog event post --related_event_id ${EVENT_ID} "EventTest5-1" "child"
ERROR: Invalid JSON structure
$ dog event post --related_event_id '{"related_event_id":XXXXXXXXXXXXXXXXX2}' "EventTest5-1" "child"
ERROR: Invalid JSON structure

tags オプション

タグをカンマ区切りで指定します。

$ dog event post --tags "stage:dev,TestTag,alias:tag-test-instance,availability-zone:ap-northeast-1a" "EventTest7" "Tags"
EventTest7 Tags  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX7

f:id:htnosm:20170320141620p:plain

host オプション

hostタグを指定します。 no_host で hostタグ無しです。

$ dog event post --host "hoge" "EventTest8" "HostName=hoge"
EventTest8 HostName=hoge  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX8
$ dog event post --no_host "EventTest8" "No Host"
EventTest8 No Host  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX9
$ dog event post --host "hoge" --no_host "EventTest8" "HostName=hoge and No Host"
EventTest8 HostName=hoge and No Host  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX6

f:id:htnosm:20170320141621p:plain

存在する host を指定すると関連付けが行なえます。

f:id:htnosm:20170320141620p:plain

device オプション

(多分)効きません。 存在する device タグを指定しても、無視されたような動きとなりました。
Infrastructure に載るような、 host と同レベルの device があれば紐付くのかもしれません。手許環境には無かったので未確認です。

$ dog event post --device "devtmpfs" "EventTest9" "Device=devtmpfs"
EventTest9 Device=devtmpfs  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX5

f:id:htnosm:20170320141623p:plain

aggregation_key オプション

イベントをまとめます。

$ dog event post --aggregation_key "AggKey1" "EventTest10" "AggregationKey [1]-1"
EventTest10 AggregationKey [1]-1  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX0
$ dog event post --aggregation_key "AggKey1" "EventTest10" "AggregationKey [1]-2"
EventTest10 AggregationKey [1]-2  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX4
$ dog event post --aggregation_key "AggKey1" "EventTest10" "AggregationKey [1]-3"
EventTest10 AggregationKey [1]-3  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX5

f:id:htnosm:20170320141624p:plain

type オプション

イベントタイプを指定します。アイコンが変更され、存在するIntegrationの場合は左ペインでの絞り込みが行えます。

$ dog event post --type "nagios" "EventTest11" "Type=nagios"
EventTest11 Type=nagios  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX1
$ dog event post --type "Slack" "EventTest11" "Type=Slack"
EventTest11 Type=Slack  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX8

f:id:htnosm:20170320141625p:plain

alert_type オプション

アラートレベルを指定します。対応した色付けが行われます。STATUSでの絞り込みも行えます。

$ dog event post --no_host --alert_type "error" "EventTest12" "AlertType=error"
EventTest12 AlertType=error  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX3
$ dog event post --no_host --alert_type "warning" "EventTest12" "AlertType=warning"
EventTest12 AlertType=warning  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX9
$ dog event post --no_host --alert_type "info" "EventTest12" "AlertType=info"
EventTest12 AlertType=info  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX3
$ dog event post --no_host --alert_type "success" "EventTest12" "AlertType=success"
EventTest12 AlertType=success  ()
yyyy-mm-dd hh:mm:ss | https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX2

f:id:htnosm:20170320141626p:plain

存在しないアラートレベル(alert_type)を指定した場合、コマンドでのエラーは無く、一見投稿できたように見えますが、参照が行なえません。
返却された EventId のURLは 404 となりました。

# hoge での登録
$ dog --raw event post --no_host --alert_type "hoge" "EventTest12" "AlertType=hoge"
{"status": "ok", "event": {"date_happened": NNNNNNNNNN, "handle": null, "title": "EventTest12", "url": "https://app.datadoghq.com/event/event?id=XXXXXXXXXXXXXXXXX7", "text": "AlertType=hoge", "tags": null, "priority": null, "related_event_id": null, "id": XXXXXXXXXXXXXXXXX7}}
# show で参照できない
$ dog --raw event show XXXXXXXXXXXXXXXXX7
ERROR: No event matches that comment_id.

f:id:htnosm:20170320141627p:plain

show

イベント情報を出力します。

usage: dog event show [-h] event_id

positional arguments:

引数 説明
event_id イベントID

実行例

$ dog event show XXXXXXXXXXXXXXXXX5
EventTest10 AggregationKey [1]-3  ()
yyyy-mm-dd hh:mm:ss | /event/event?id=XXXXXXXXXXXXXXXXX5
  • raw オプションでの出力結果
    • JSON で返却され、全情報が載ってくるのでデフォルトより利用しやすいと思います
    • “id” は EventId とは別のIDが返却されます
$ dog --raw event show XXXXXXXXXXXXXXXXX5 | jq '.'
{
  "event": {
    "date_happened": NNNNNNNNNN,
    "alert_type": "info",
    "resource": "/api/v1/events/XXXXXXXXXXXXXXXXX5",
    "title": "EventTest10",
    "url": "/event/event?id=XXXXXXXXXXXXXXXXX5",
    "text": "AggregationKey [1]-3",
    "tags": [],
    "device_name": null,
    "priority": "normal",
    "host": "xxxxxxxxxxxx.local",
    "id": XXXXXXXXXXXXXXXXX0
  }
}
  • pretty オプションでの出力結果
    • 出力オプション未指定と同じです。

stream

usage: dog event stream [-h] [--priority PRIORITY] [--sources SOURCES]
                        [--tags TAGS]
                        start [end]

positional arguments:

引数 説明
start 対象の開始(FROM)日時を指定
end 対象の終了(TO)日時を指定

形式は POSIX です。形式は POSIX です。'30d' のような形式でも指定可能です。

Stream start and end times can be specified as either a POSIX timestamp (e.g.
the output of `date +%s`) or as a period of time in the past (e.g. '5m', '6h',
'3d').

optional arguments:

ロングオプション 説明
–priority 優先度。"normal" or “low” (デフォルト normal)
–sources フィルタする source のリスト(カンマ区切り)
–tags フィルタするタグのリスト(カンマ区切り)

実行例

start

指定値〜現在時刻まで降順で出力されます。

$ dog event stream $(date -v -1H +'%s')
EventTest12 AlertType=success  ()
yyyy-mm-dd hh:mm:46 | /event/event?id=XXXXXXXXXXXXXXXXX2
()
EventTest12 AlertType=info  ()
yyyy-mm-dd hh:mm:43 | /event/event?id=XXXXXXXXXXXXXXXXX3
()
・・・略

timeframe は 2,764,800 秒未満です。 32日以上を指定するとエラーとなります。

$ dog event stream $(date -v -32d +'%s')
ERROR: Trying to query too large a timeframe (max: 2764800)
  • raw オプションでの出力結果
$ dog --raw event stream $(date -v -9H +'%s') | jq '.'
{
  "events": [
    {
      "date_happened": NNNNNNNN46,
      "alert_type": "success",
      "is_aggregate": false,
      "title": "EventTest12",
      "url": "/event/event?id=XXXXXXXXXXXXXXXXX2",
      "text": "AlertType=success",
      "tags": [],
      "comments": [],
      "device_name": null,
      "priority": "normal",
      "source": "My Apps",
      "host": null,
      "resource": "/api/v1/events/XXXXXXXXXXXXXXXXX2",
      "id": XXXXXXXXXXXXXXXXX0
    },
    {
      "date_happened": NNNNNNNN43,
      "alert_type": "info",
      "is_aggregate": false,
      "title": "EventTest12",
      "url": "/event/event?id=XXXXXXXXXXXXXXXXX3",
      "text": "AlertType=info",
      "tags": [],
      "comments": [],
      "device_name": null,
      "priority": "normal",
      "source": "My Apps",
      "host": null,
      "resource": "/api/v1/events/XXXXXXXXXXXXXXXXX3",
      "id": XXXXXXXXXXXXXXXXX0
    },
・・・略
  • pretty オプションでの出力結果
    • 出力オプション未指定と同じです。

end

指定開始〜終了時間まで降順で出力されます。

$ dog event stream $(date -v -10H +'%s') $(date -v -9H +'%s')
EventTest9 Device=sda1  ()
yyyy-mm-dd hh:mm:29 | /event/event?id=XXXXXXXXXXXXXXXXX5
()
EventTest8 HostName=hoge and No Host  ()
yyyy-mm-dd hh:mm:40 | /event/event?id=XXXXXXXXXXXXXXXXX6
()
・・・略

priority オプション

優先度での絞り込みです。low,normal 以外の指定はデフォルト(all)と見做されます。

$ dog event stream $(date -v -30d +'%s') --priority low
EventTest5 priority low  ()
yyyy-mm-dd hh:mm:00 | /event/event?id=XXXXXXXXXXXXXXXXX6
()
・・・略

sources オプション

イベントタイプでの絞り込みです。
カンマ区切りで複数指定可能とヘルプにありましたが、効きませんでした。 後に指定した物のみ有効となりました。

$ dog event stream --sources "nagios" $(date -v -30d +'%s')
EventTest11 Type=nagios  ()
yyyy-mm-dd hh:mm:26 | /event/event?id=XXXXXXXXXXXXXXXXX1
()

tags オプション

タグでの絞り込みです。複数指定で and 検索になります。

$ dog --raw event stream --tags "testtag,availability-zone:ap-northeast-1a" $(date -v -30d +'%s') | jq '.'
{
  "events": [
    {
      "date_happened": NNNNNNNN89,
      "alert_type": "info",
      "is_aggregate": false,
      "title": "EventTest7",
      "url": "/event/event?id=XXXXXXXXXXXXXXXXX7",
      "text": "Tags",
      "tags": [
        "alias:tag-test-instance",
        "availability-zone:ap-northeast-1a",
        "stage:dev",
        "testtag"
      ],
      "comments": [],
      "device_name": null,
      "priority": "normal",
      "source": "My Apps",
      "host": "XXXXX.local",
      "resource": "/api/v1/events/XXXXXXXXXXXXXXXXX7",
      "id": XXXXXXXXXXXXXXXXX0
    }
  ]
}

host タグは特殊なようで上手く絞込できませんでした。 WebUI上で host:XXXXX の形式で絞り込みすると hosts に置き換わるので、何かしら変換掛かるのかもしれません。

f:id:htnosm:20170320141628p:plain


event編まとめ

ヘルプではオプションとして出て来るが、利用できないものが多い印象でした。
event は主に post の利用になり、基本機能が使えれば問題ないと思いますが、混乱します(しました)。