New Relic APM エージェントを使ったカスタムイベントの追加

New Relic のエージェント API を使って、カスタムイベントを送信できます。つまり、アプリのコードから送信したイベントに対して問い合わせが行えるということです。エージェントがカスタムイベントの存在を認識すると、60秒ごとに New Relic Insights へカスタムイベントを送信します。

エージェントAPIを経由して送信されたカスタムイベントは、ハイセキュリティモードと互換性がありません。

イベントの追加

New Relic エージェントを使って、カスタムイベントを追加する方法は、エージェントごとに異なります。お使いの環境に合わせて以下をご覧ください。

Go
Insights のカスタムイベントを Go アプリに追加するには、RecordCustomEvent を使います。

RecordCustomEvent のフォーマットは以下の通りです。

RecordCustomEvent(eventType string, params map[string]interface{}) error

eventType は、英数字、アンダースコア、およびコロンのみが使えます。255バイト未満でなければなりません。

params マップの各値は、数値、文字列、真偽値でなければなりません。キーは255 バイト未満であること。params マップには、64以上の属性を含まないこと。イベントタイプ名の制限については、制限と文字制約予約語を確認ください。

Insights のカスタムイベントの作成方法
以下は Go アプリで Insights のカスタムイベントを生成する例です。

func customEvent(w http.ResponseWriter, r *http.Request) {
    io.WriteString(w, "recording a custom event")

    app.RecordCustomEvent("my_event_type", map[string]interface{}{
        "myString": "hello",
        "myFloat":  0.603,
        "myInt":    123,
        "myBool":   true,
    })
}
Java
Java におけるカスタムイベントの収集は、バージョン 3.13.0 以降のエージェントではデフォルトで有効になっています。カスタムイベントは、以下のように関連する API を呼び出して送信します。

Map<String, Object> eventAttributes = new HashMap<String, Object>();
NewRelic.getAgent().getInsights().recordCustomEvent('MyCustomEvent', eventAttributes);

第1引数は、イベントタイプの名前を定義しています。第2引数は、カスタムイベントの属性を格納したマップです。イベントタイプ名の数には制限があります。よって、動的にイベントタイプ名を生成しないでください。イベントタイプ名の制約については、制限と文字制約予約語を参照してください。

newrelic.yml の設定パラメータによって、Java エージェントが記録するイベントの最大数を変更できます。

  1. custom_insights_events.max_samples_stored: を設定ファイルに追加します。
  2. 1分あたりに記録するイベントの最大数を、整数で指定します。10,000 イベント(デフォルト)よりも少ない数を送信したい場合は以下のようになります。
    custom_insights_events.max_samples_stored: 5000
大量のイベントを送信すると、エージェントのメモリオーバーヘッドを増やすことになります。また、1MBより大きい Post リクエストは、イベントの最大数に関係なく記録されません。

カスタムイベントを完全に無効にするには、newrelic.ymlcustom_insights_events.enabled: falseを追加してください。

.NET
.NET におけるカスタムイベントの収集は、バージョン 4.6.29.0 以降のエージェントではデフォルトで有効になっています。カスタムイベントは、以下のように関連する API を呼び出して送信します。

var eventAttributes = new Dictionary<String, Object>();
NewRelic.Api.Agent.NewRelic.RecordCustomEvent('MyCustomEvent', eventAttributes);

第1引数は、イベントタイプの名前を指定します。第2引数は、カスタムイベントの属性を格納した IEnumerable です。イベントタイプ名の数には制限があります。よって、動的にイベントタイプ名を生成しないでください。イベントタイプ名の制約については、制限と文字制約予約語を参照してください。

カスタムイベント無効にするには、newrelic.config にある customEvents.enabledfalse にセットします。

大量のイベントを送信すると、エージェントのメモリオーバーヘッドを増やすことになります。また、1MBより大きい Post リクエストは、イベントの最大数に関係なく記録されません。
Node.js
Node.js におけるカスタムイベントの収集は、バージョン 1.15.0 以降のエージェントではデフォルトで有効になっています。カスタムイベントは、以下のように関連する API を呼び出して送信します。

recordCustomEvent(eventType, attributes)

通常、特定の処理時間に関連したイベントベースのメ​​トリックを記録するには、recordCustomEvent を使用します。eventType は、255 文字未満の英数字の文字列とします。属性は、キーと値のペアのオブジェクトでなければなりません。キーは、255 文字以下、値は、文字列、数値、真偽値としてください。イベントタイプ名の制約については、制限と制限付き文字予約語を御覧ください。

カスタムイベントを無効にするには、newrelic.jscustom_insights_events.enabled: false を追加します。

PHP
PHP におけるカスタムイベントの収集は、バージョン 4.18 以降のエージェントではデフォルトで有効になっています。カスタムイベントを送信するには、以下のように関連する API を呼び出します。

newrelic_record_custom_event("WidgetSale", array("color"=>"red", "weight"=>12.5));

第1引数は、イベントタイプの名前を指定します。第2引数は、カスタムイベントの属性を格納した配列です。イベントタイプ名の数には制限があります。よって、動的にイベントタイプ名を生成しないでください。イベントタイプ名の制約については、制限と文字制約予約語を参照してください。

デフォルトでは、分ごとに記録するカスタムイベントの最大数は 10,000 です。この設定は変更することができません。

カスタムイベントを完全に無効にするには、newrelic.custom_insights_events.enabled = falsenewrelic.ini に追加し、エージェントを再起動します。

Python
Python におけるカスタムイベントの収集は、バージョン 2.60.0.46 以降のエージェントではデフォルトで有効になっています。カスタムイベントを送信するには、以下のように関連する API を呼び出します。

newrelic.agent.record_custom_event(event_type, params, application=None)

event_type は、カスタムイベントの名前(またはタイプ)を表します。カスタムイベントの属性は、params キーワード引数にディクショナリとして渡します。イベントタイプ名の数には制限があります。よって、動的にイベントタイプ名を生成しないでください。イベントタイプ名の制約については、制限と文字制約予約語を参照してください。

監視対象の Web リクエストやバックグラウンドタスクのコンテキスト外で呼び出された場合、application キーワード引数が指定されており、例外が記録されるべきアプリに対応するアプリケーションオブジェクトがない場合、その呼び出しは無視されます。適切なアプリケーションオブジェクトは、 newrelic.agent.application() 関数を呼び出して取得できます。

カスタムイベントを完全に無効にするには、newrelic.ini 設定ファイル内の custom_insights_events.enabled の値に False をセットします。

Ruby
Ruby におけるカスタムイベントの収集は、バージョン 3.9.8.273 以降のエージェントではデフォルトで有効になっています。カスタムイベントを送信するには、以下のように関連する API を呼び出します。

::NewRelic::Agent.record_custom_event('WidgetSale', color: 'red', weight: 12.5)

第1引数は、イベントタイプの名前を指定します。第2引数は、カスタムイベントの属性を格納した hash です。イベントタイプ名の数には制限があります。よって、動的にイベントタイプ名を生成しないでください。イベントタイプ名の制約については、制限と文字制約予約語を参照してください。

newrelic.yml の設定パラメータによって、Ruby エージェントが記録するイベントの最大数を変更できます。

  1. custom_insights_events.max_samples_stored: を設定ファイルに追加します。
  2. 1分あたりの記録するイベントの最大数を整数で指定します。1分あたり 5000 イベントを送信の上限にしたい場合は以下のようになります。
    custom_insights_events.max_samples_stored: 5000
大量のイベントを送信すると、エージェントのメモリオーバーヘッドを増やすことになります。また、1MB より大きい Post リクエストは、イベントの最大数に関係なく記録されません。

カスタムイベントを完全に無効にするには、newrelic.ymlcustom_insights_events.enabled: false を追加します。

タイムスタンプ

エージェント経由で収集および記録されたイベントのタイムスタンプを指定することはできません。API を通してイベントが記録された時間に基づいて、イベントにタイムスタンプを割り当てます。

制限と文字制約

New Relic Insights では、カスタムイベントのサイズを制限しています。

  • 属性数: 1イベントあたり最大 64個
  • 文字属性: 最長 4kb
  • 1回の合計サイズ: 1コールあたり最大 1Mb

カスタムイベントを追加するときは、以下の文字のみを使用できます。

  • eventType: 英数字、_ [アンダースコア]、: [コロン]
  • appId: 整数のみ
  • accountId: 整数のみ

予約語

カスタム属性を追加する前に、New Relic のNRQL と Insights
の予約語
を確認してください。この予約語をカスタム属性として使うと、予期せぬ結果を招く可能性があります。