vague memory

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

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 の利用になり、基本機能が使えれば問題ないと思いますが、混乱します(しました)。

Datadog (dogコマンド) tag編

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

f:id:htnosm:20170318051327p:plain


目次


tag Modes

ユーザタグの操作が行えます。 Datadog Agent や インテグレーションで付与されるタグの更新はできません。
ホスト指定は host:タグ の値です。

サブコマンド 説明
add ホストへユーザタグ追加(既存ユーザタグを保持)
replace ホストのユーザタグ置換(既存ユーザタグは削除)
show ユーザタグを出力
detach ホストのユーザタグを全削除

add

usage: dog tag add [-h] host tag [tag ...]

positional arguments:

引数 説明
host 対象ホスト
tag 追加するタグ(スペース区切り)

実行例

追加したユーザタグと既に付与済みのユーザタグがレスポンスです。 (完全な初回実行時にはレスポンスはありませんでした。一度追加した後は、空の状態からでもレスポンスがありました。)
既に付与済みのユーザタグを指定してもエラーはありません。

単一タグ指定

$ dog tag add i-XXXXXXXXXXXXXXXXX TestTag
testtag

f:id:htnosm:20170318051328p:plain

複数タグ指定

$ dog tag add i-XXXXXXXXXXXXXXXXX TestStage:dev OS:linux alias:tag-test-instance
teststage:dev
os:linux
testtag
alias:tag-test-instance

f:id:htnosm:20170318051329p:plain

replace

ユーザタグを置き換えます。 個別のタグ指定はできず、指定したタグリストと完全に置き換わります。

usage: dog tag replace [-h] host tag [tag ...]

positional arguments:

引数 説明
host 対象ホスト
tag 置換するタグ(スペース区切り)

実行例

  • 実行前に付与されているユーザタグ
teststage:dev           #→ stage:stg を指定
os:linux                #→ 同一値を指定
testtag                 #→ updatetesttag を指定
alias:tag-test-instance #→指定しない
$ dog tag replace i-XXXXXXXXXXXXXXXXX stage:stg os:linux updatetesttag
updatetesttag
os:linux
stage:stg

f:id:htnosm:20170318051330p:plain

show

タグを出力します。ユーザタグに加え、Datadog Agent や インテグレーションで付与されるタグも併せて出力します。

usage: dog tag show [-h] host

positional arguments:

引数 説明
host 対象ホストの全ユーザタグ表示
all 全てのホストの全ユーザタグ表示

host

$ dog tag show i-XXXXXXXXXXXXXXXXX

f:id:htnosm:20170318051331p:plain

  • raw オプションでの出力結果

f:id:htnosm:20170318051332p:plain

  • pretty オプションでの出力結果
    • 出力オプション未指定と同じです。

all

“タグ ホスト” 形式で出力されます。ユーザタグか否かの区別はつきません。

$ dog tag show all

f:id:htnosm:20170318051333p:plain

  • raw オプションでの出力結果
    • tag を key とした形式

f:id:htnosm:20170318051334p:plain

  • pretty オプションでの出力結果
    • インデントが付いた形式
    • 区切りに"()“行が出力

f:id:htnosm:20170318051335p:plain

detach

ホストからユーザタグを削除します。個別のタグ指定はできません。(全ユーザタグが削除されます)

usage: dog tag detach [-h] host

positional arguments:

引数 説明
host 対象ホスト

実行例

f:id:htnosm:20170322093632p:plain

Datadog (dogコマンド) metric編

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

f:id:htnosm:20170317233257p:plain


目次


metric Modes

ヘルプに Post metrics. とある通り、現在時刻でのメトリクス投稿が行えます。 現時点では参照系は未対応です。

サブコマンド 説明
post メトリクス投稿

post

usage: dog metric post [-h] [--host HOST] [--no_host] [--device DEVICE]
                       [--tags TAGS] [--localhostname] [--type TYPE]
                       name value

positional arguments:

引数 説明
name メトリクス名
value メトリクス値

optional arguments:

ロングオプション 説明
–host 関連ホスト名(デフォルトはローカルホスト名)
–no_host 関連ホスト無し(–hostオプションは無視される)
–device 関連デバイス
–tags タグのリスト(カンマ区切り)
–localhostname 非推奨オプション(–hostオプションがない場合のデフォルトの挙動)
–type メトリクスのタイプ指定。gauge(32bit float) or counter(64bit integer)

実行例

単純実行

name,value のみで投稿します。 成功時のレスポンスは特にありません。

$ dog metric post TestMetrics 1
$

f:id:htnosm:20170317233258p:plain

hostオプションを使用していないため、実行 hostname に紐付けられます。

f:id:htnosm:20170317233302p:plain

1分以下の間隔で投稿

グラフ上最短の丸め間隔である 20秒 を基準に挙動を確認してみます。

20秒間隔

投稿毎の値が表示できます。

f:id:htnosm:20170317233259p:plain

5秒間隔

丸められます。

f:id:htnosm:20170317233300p:plain

登録データ確認(pointlist)

登録されているデータ自体も20秒間隔となるようです。

f:id:htnosm:20170317233301p:plain

小数点(decimal)

まず必要になることはなさそうですが、precision(有効桁) = 9 でしょうか。

以下のような値を連続で投稿してみます。

0.1
0.12
0.123
0.1234
0.12345
0.123456
0.1234567
0.12345678
0.123456789
0.12345678910
0.1234567891011
0.123456789101112
0.12345678910111213
0.1234567891011121314
0.123456789101112131415
0.12345678910111213141516
0.1234567891011121314151617
0.123456789101112131415161718
0.12345678910111213141516171819
0.1234567891011121314151617181920

f:id:htnosm:20170317233303p:plain f:id:htnosm:20170317233304p:plain

hostオプション

dog metric post --host hogehost TestMetrics 5

指定した hostname で投稿できます。

f:id:htnosm:20170317233305p:plain

no_hostオプション
# host有
dog metric post --host hogehost --no_host TestMetrics 10
# host無
dog metric post --no_host TestMetrics 3

host:N/A となります。

f:id:htnosm:20170317233306p:plain

deviceオプション

DatadogAgent を導入するとディスク関連のメトリクスが device タグとして登録されます。 その device タグに関連させるオプションと思われます。
存在しない device タグでも投稿はできるので、 device タグを付与するオプション と言い換えて良さそうです。

  • 存在する device タグ

f:id:htnosm:20170317233307p:plain

# 存在しないdeviceタグ
$ dog metric post --device sda1 TestMetrics 5
# 存在するdeviceタグ
$ dog metric post --device tmpfs TestMetrics 4

f:id:htnosm:20170317234608p:plain

tagオプション

任意のタグ名とタグに関連付けが行えます。

$ dog metric post --tags tag1,tag2:2,hoge:fuga TestMetrics 15
$ dog metric post --tags tag1,tag2:3,hoge:hoge TestMetrics 7

f:id:htnosm:20170317233309p:plain

localhostnameオプション

helpから削除してもらいたいオプションです。 非推奨なので、 WARNING が出力されます。

$ dog metric post --localhostname TestMetrics 1
WARNING: `--localhostname` command line flag is deprecated, made default when no `--host` is specified. See the `--host` option for more information.

動作としては、 –host オプションを使用しない(デフォルト)で実行した結果と同様、実行 hostname に紐付けられます。

f:id:htnosm:20170317233310p:plain

typeオプション

違いがわかりませんでした。
type が任意の値でも登録されること、APIでサポートしているのは guage のみという記載があることから、実際は guage で登録されているのかもしれません。

HTTP API Submission

For the API all metrics are submitted the same way, with the type specified as a parameter.

Gauge Stored in Web App as GAUGE type

# gauge 整数
$ dog metric post --type gauge TestMetrics 1
# gauge 少数
$ dog metric post --type gauge TestMetrics 2.123
# counter 整数
$ dog metric post --type counter TestMetrics 3
# counter 少数
$ dog metric post --type counter TestMetrics 4.456
# type オプション無し
$ dog metric post TestMetrics 5
$ dog metric post TestMetrics 6.789
# type に適当な値指定
$ dog metric post --type xxxxx TestMetrics 7

f:id:htnosm:20170317233311p:plain

  • gauge と counter を同時に投稿した結果

f:id:htnosm:20170317233312p:plain

実行時エラー

value に数値以外を指定するとエラーが返ります。

$ dog metric post TestMetrics XXXXX
usage: dog metric post [-h] [--host HOST] [--no_host] [--device DEVICE]
                       [--tags TAGS] [--localhostname] [--type TYPE]
                       name value
dog metric post: error: argument value: invalid float value: 'XXXXX'

metric編まとめ

カスタムメトリクスを投稿する際、APIを使用するより簡単に扱えると思います。
今回 value 不正以外のエラーを発生させることが出来ませんでしたが、タグやタイプを間違えていても基本的には受け付けてしまうようです。

Datadog (dogコマンド) search編

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

f:id:htnosm:20170316053400p:plain

search Modes

ヘルプには Search datadog. としかないので、何を検索できるのか謎でしたが、APIリファレンスに記載がありました。

過去24時間のエンティティを検索します。 検索可能なエンティティは hostmetrics です。

サブコマンド 説明
query faset検索

ここで言う hostmetrics は faset と呼ぶそうです。 query 部分は facet:query_string の形式になります。

結果を先に書いてしまうと、これと言った用途が見つけられませんでした。 新規導入した host や metrics が Datadog 側に正常に登録されたことを確認する等でしょうか。

APIを見ると api.Infrastructure.search と記載があるので、恐らく WebUI 上の Infrastructure での検索なのかと思います。 f:id:htnosm:20170320151251p:plain

query

usage: dog search query [-h] query

全検索

query の後ろに空文字(クォート囲み)を入れると、metrics、hostsのリストが返ってきます。 空文字を入れないとエラーとなります。

# 空文字で実行
$ dog search query ""
metrics system.uptime
metrics system.swap.used
metrics system.swap.total
・・・
metrics aws.dynamodb.online_index_percentage_progress
metrics gcp.logging.dropped_log_entry_count
hosts   hoge.ap-northeast-1.elb.amazonaws.com
hosts   i-XXXXXXXX
# 引数無しで実行
$ dog search query
usage: dog search query [-h] query
dog search query: error: too few arguments

facetのみ指定

全検索とほぼ同じですが、指定したfacetのみ出力されます。

$ dog search query "hosts:"
hosts   hoge.ap-northeast-1.elb.amazonaws.com
・・・
hosts   i-XXXXXXXX
$ dog search query "metrics:"
metrics system.uptime
・・・
metrics gcp.logging.dropped_log_entry_count

facet:query_string 指定

絞り込めます。が、facet指定無しでも同じ結果が返ってきました。

$ dog search query "metrics:aws.ec2.cpucredit_usage"
metrics aws.ec2.cpucredit_usage
$ dog search query "aws.ec2.cpucredit_usage"
metrics aws.ec2.cpucredit_usage

query_stringのみ指定

中間一致でfacetを跨いでの結果が返ってきました。

$ dog search query "load"
metrics system.load.1
hosts   load-test.xxxxxxxxxxxx.ap-northeast-1.rds.amazonaws.com

使い所がわからないので良いユースケースがあれば教えてほしいです。

Datadog (dogコマンド) comment編

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

f:id:htnosm:20170314212522p:plain


目次


comment Modes

Events に表示されるコメント(メッセージ)の操作が行えます。 f:id:htnosm:20170314205807p:plain

サブコマンド 説明
post コメント送信
update コメント更新
reply コメントへの返信
show コメント情報取得
delete コメント削除

コメントの一覧を取得するAPIは用意されていません。 更新系の操作はコメントIDを引数として与える必要がありますが、Web UIでIDを確認する、postしたコメントで戻り値を取得しておく等、IDを取得する術を用意しなくてはならず使い勝手はよくないです。(利用頻度は低そうです)

  • コメントID取得例

f:id:htnosm:20170314205806p:plain

post

usage: dog comment post [-h] [--handle HANDLE] [comment]

実行例

$ dog comment post "PostTest"
id      9999999999999999999
url     /event/event?id=9999999999999999999
resource    /api/v1/comments/9999999999999999999
handle      hoge@example.com
message     u'PostTest'

f:id:htnosm:20170314205803p:plain

HANDLE にはDatadogのユーザを指定するようです。存在しないユーザの場合はエラーとなります。

$ dog comment post --handle "hoge" "PostTest hoge"
ERROR: The value provided for parameter 'handle' is invalid
$ dog comment post --handle "user@example.com" "PostTest user"
id      9999999999999999999
url     /event/event?id=9999999999999999999
resource    /api/v1/comments/9999999999999999999
handle      user@example.com
message     u'PostTest user'

update

対象の comment_id が必要です。 対象コメントが直接書き換わります。(履歴は残りません)

usage: dog comment update [-h] [--handle HANDLE] comment_id [comment]

実行例

$ dog comment update 9999999999999999999 "CommentUpdate"
id      9999999999999999999
url     /event/event?id=9999999999999999999
resource    /api/v1/comments/9999999999999999999
handle      hoge@example.com
message     u'CommentUpdate'

f:id:htnosm:20170314205804p:plain

replay

対象の comment_id が必要です。 対象コメントへ返信の付与になります。

usage: dog comment reply [-h] [--handle HANDLE] comment_id [comment]

実行例

$ dog comment reply 9999999999999999999 "ReplyTest"
id      9999999999999999990
url     /event/event?id=9999999999999999990
resource    /api/v1/comments/9999999999999999990
handle      hoge@example.com
message     u'ReplyTest'

f:id:htnosm:20170314205805p:plain

show

対象の comment_id が必要です。一覧取得はできません。

usage: dog comment show [-h] comment_id

実行例

返信(reply)のコメントID指定は取得できません(エラーになります)

# コメントを指定
$ dog comment show 9999999999999999999
id      9999999999999999999
url     /event/event?id=9999999999999999999
resource    /api/v1/events/9999999999999999999
message     u'CommentUpdate'
# コメントのreplyを指定
$ dog comment show 9999999999999999990
ERROR: No event matches that comment_id.

delete

対象の comment_id が必要です。 対象コメント・返信を削除します。(responseも無く、履歴は残りません) コメントを削除するとそのコメントに対する返信もまとめて消えます。 存在しない id 指定は 500 エラーが返ります。

usage: dog comment delete [-h] comment_id

実行例

# コメントのreplyを指定
$ dog comment delete 9999999999999999990
# コメントを指定
$ dog comment delete 9999999999999999999
# 削除済みコメントを指定
$ dog comment delete 9999999999999999999
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/comment.py", line 166, in _delete
    res = api.Comment.delete(id)
  File "/usr/lib/python2.7/site-packages/datadog/api/resources.py", line 110, in delete
    return APIClient.submit('DELETE', cls._class_url + "/" + str(id), **params)
  File "/usr/lib/python2.7/site-packages/datadog/api/api_client.py", line 129, in submit
    proxies=_proxies, verify=_cacert
  File "/usr/lib/python2.7/site-packages/datadog/api/http_client.py", line 84, in request
    raise HTTPError(e.response.status_code, result.reason)
datadog.api.exceptions.HTTPError: Datadog returned a bad HTTP response code: 500 - Internal Server Error. Please try again later. If the problem persists, please contact support@datadoghq.com

サポートへのメッセージポストで利用できるかなと思いました。(他に用途が浮かびませんでした)

Messages in the event stream containing @support-datadog will reach our Support Team.