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

related_event_id オプション

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

vague memory

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

Datadog (dogコマンド) event編

event Modes

post

positional arguments:

optional arguments:

実行例

オプション無しで実行

文字数制限

マルチバイト

date_happened オプション

handle オプション

priority オプション

related_event_id オプション

tags オプション

host オプション

device オプション

aggregation_key オプション

type オプション

alert_type オプション

show

positional arguments:

実行例

stream

positional arguments:

optional arguments:

実行例

start

end

priority オプション

sources オプション

tags オプション

event編まとめ