Simple Log Service:イベント処理関数

関数

# 以下の 4 つの変換ルールは同等です。
e_if_else(e_search("f1==v1"), KEEP, DROP)
e_if_else(e_search("not f1==v1"), DROP) 
e_keep(e_search("f1==v1"))
e_drop(e_search("not f1==v1"))

# 以下の変換ルールは無意味です。
以下の変換ルールは効果がなく、何の目的もありません：
e_keep()

__labels__:host#$#myhost
__name__:rt
__time_nano__:1614739608000000000
__value__:123.0

e_drop

条件に基づいてログを破棄します。

• 構文

  e_drop(condition=True)

  e_drop() と同等の固定識別子 DROP もサポートされています。

• パラメーター

  パラメーター名	タイプ	必須	説明
  condition	ブール値	いいえ	デフォルト：True。通常、条件関数の結果がこのパラメーターに渡されます。

• レスポンス

  条件が満たされた場合、ログを破棄し、None を返します。それ以外の場合は、元のログを返します。

• 例

  • 例 1：__programe__ フィールドの値が access の場合、ログを破棄します。それ以外の場合は、ログを保持します。

    • 生ログ

      __programe__: access
      age:  18
      content:  123
      name:  maki
      __programe__: error
      age:  18
      content:  123
      name:  maki

    • 変換ルール

      e_if(e_search("__programe__==access"), DROP)

    • 結果

      __programe__ フィールドが access に設定されているログは破棄されます。__programe__ フィールドが error に設定されているログは保持されます。

      __programe__: error
      age:  18
      content:  123
      name:  maki

  • 例 2：条件が True と評価されます。ログは破棄されます。

    • 生ログ

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール

      e_drop(e_search("k1==v1"))

    • 結果

      条件 k1==v1 が True であるため、ログは破棄されます。

  • 例 3：条件が False と評価されます。ログは保持されます。

    • 生ログ

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール

      e_drop(e_search("not k1==v1"))

    • 結果

      k1: v1
      k2: v2
      k3: k1

  • 例 4：条件が設定されていません。デフォルト値の True が使用され、ログは破棄されます。

    • 生ログ

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール

      e_drop()

    • 結果

      ログは破棄されます。

• 参照

  他の関数と組み合わせて使用できます。詳細については、「データの複製と配信」をご参照ください。

e_keep

条件に基づいてログを保持します。

• 構文

  e_keep(condition=True)

  e_keep() と同等の固定識別子 KEEP もサポートされています。

• パラメーター

  パラメーター名	タイプ	必須	説明
  condition	ブール値	いいえ	デフォルト：True。通常、条件関数の結果がこのパラメーターに渡されます。

• レスポンス

  条件が満たされた場合、元のログを返します。条件が満たされない場合、ログを破棄します。

• 例

  • 例 1：__programe__ フィールドの値が access の場合、ログを保持します。それ以外の場合は、ログを破棄します。

    • 生ログ

      __programe__: access
      age:  18
      content:  123
      name:  maki
      __programe__: error
      age:  18
      content:  123
      name:  maki

    • 変換ルール

      e_keep(e_search("__programe__==access"))
      # 以下と同等
      e_if(e_search("not __programe__==access"), DROP)
      # 以下と同等
      e_if_else(e_search("__programe__==access"), KEEP, DROP)  

    • 結果

      __programe__ フィールドが access に設定されているログは保持されます。

      __programe__: access
      age:  18
      content:  123
      name:  maki

  • 例 2：条件が True と評価されます。ログは保持されます。

    • 生ログ

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール

      e_keep(e_search("k1==v1"))

    • 結果

      k1: v1
      k2: v2
      k3: k1

  • 例 3：条件が False と評価されます。ログは破棄されます。

    • 生ログ

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール

      e_keep(e_search("not k1==v1"))

    • 結果

      ログは破棄されます。

  • 例 4：条件が False です。ログは破棄されます。

    • 生ログ

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール

      e_keep(False)

    • 結果

      ログは破棄されます。

• 参考資料

  他の関数と組み合わせて使用できます。詳細については、「複雑な JSON データの変換」をご参照ください。

e_split

フィールド値に基づいてログを複数のログに分割します。また、分割前に JMESPath を使用してフィールドを抽出することもサポートしています。

• 構文

  e_split(field_name, sep=',', quote='"', lstrip=True, jmes=None, output=None)

  分割ルール：

  1. jmes パラメーターを指定した場合、ログフィールド値は JSON リストに変換され、JMES を使用して次のステップのために値が抽出されます。jmes パラメーターを指定しない場合、フィールド値は次のステップで直接使用されます。

  2. 前のステップの値がリストまたは JSON リスト形式の文字列である場合、ログはこのリストに基づいて分割されます。それ以外の場合、値は sep、quote、および lstrip パラメーターを使用して CSV ファイルとして解析されます。その後、ログは解析された値に基づいて分割されます。

• パラメーター

  パラメーター名	タイプ	必須	説明
  field_name	文字列	はい	分割するフィールドの名前。特殊なフィールド名の設定方法については、「イベントタイプ」をご参照ください。
  sep	文字列	いいえ	複数の値を分割するために使用される区切り文字。
  quote	文字列	いいえ	値を囲むために使用される引用符。
  lstrip	文字列	いいえ	各値から先頭のスペースを削除するかどうか。デフォルト：True。
  jmes	文字列	いいえ	フィールド値を JSON オブジェクトに変換し、JMES 式を使用して値を抽出し、その結果を分割します。
  output	文字列	いいえ	分割結果のフィールド名。デフォルトでは、元のフィールド名が上書きされます。

• レスポンス

  フィールド値がソースリストの分割された値に置き換えられたログのリストを返します。

• 例

  • 生ログ

    __topic__:
    age:  18
    content:  123
    name:  maki
    __topic__:
    age:  18
    content:  123
    name:  maki

  • 変換ルール

    e_set("__topic__", "V_SENT,V_RECV,A_SENT,A_RECV")
    e_split("__topic__")

  • 結果

    __topic__:  A_SENT
    age:  18
    content:  123
    name:  maki
    __topic__:  V_RECV
    age:  18
    content:  123
    name:  maki
    ...

• 参考資料

  他の関数と組み合わせて使用できます。詳細については、「複雑な JSON データの変換」をご参照ください。

出力 Logstore

指定された Logstore にログを出力します。出力ログのトピック、ソース、およびタグを設定できます。

• 構文

  e_output(name=None, project=None, logstore=None, topic=None, source=None, tags=None, hash_key_field=None, hash_key=None)
  e_coutput(name=None, project=None, logstore=None, topic=None, source=None, tags=None, hash_key_field=None, hash_key=None)

  プレビューモードでは、ログは送信先 Logstore に送信されません。代わりに、データ変換ジョブを初めてプレビューするときに現在のプロジェクトに自動的に作成される専用の Logstore である internal-etl-log Logstore に送信されます。この Logstore の構成を変更したり、他のデータを書き込んだりすることはできません。この Logstore は無料です。

• パラメーター

  説明

  e_output または e_coutput 関数で name、プロジェクト、および Logstore パラメーターを設定し、[データ変換ジョブの作成] パネルでも送信先プロジェクトと送信先 Logstore を設定した場合、関数のパラメーターが優先されます。詳細は次のとおりです。

  • e_output または e_coutput 関数で name パラメーターのみを設定した場合、変換結果は指定された名前に対応する送信先 Logstore に分散されて保存されます。

  • e_output 関数で project と Logstore パラメーターのみを設定した場合、変換結果は e_output 関数で指定した送信先 Logstore に分散されて保存されます。

    権限付与に AccessKey ペアを使用する場合、変換プロセス中に現在のログインアカウントの AccessKey ペアが使用されます。

  • e_output 関数で name、project、および Logstore パラメーターを設定した場合、変換結果は e_output 関数で指定した送信先 Logstore に分散されて保存されます。

    権限付与に AccessKey ペアを使用する場合、送信先名に指定された AccessKey ペアが変換プロセス中に使用されます。

  パラメーター名	タイプ	必須	説明
  name	文字列	いいえ	ストレージ送信先名。デフォルト：None。
  project	文字列	いいえ	送信先プロジェクト。すでに存在している必要があります。
  Logstore	文字列	いいえ	送信先 Logstore。すでに存在している必要があります。
  topic	文字列	いいえ	ログに新しいトピックを設定します。
  source	文字列	いいえ	ログに新しいソースを設定します。
  tags	Dict	いいえ	ログに新しいタグを設定します。タグは辞書形式で渡します。 説明 __tag__: プレフィックスをキーワードに追加する必要はありません。
  hash_key_field	文字列	いいえ	ログ内のフィールド名。変換ジョブは、このフィールドのハッシュ値に基づいて、ログを特定のシャードにルーティングします。 説明 指定されたフィールドがログに存在しない場合、システムは負荷分散モードにフォールバックし、ランダムにログをシャードに書き込みます。
  hash_key	文字列	いいえ	ハッシュ値。変換ジョブは、この値に基づいてログを特定のシャードにルーティングします。 説明 hash_key_field パラメーターは、このパラメーターよりも優先度が高いです。hash_key_field パラメーターが変換構文ですでに設定されている場合、このパラメーターは効果がありません。

  • デフォルトの保存先の設定

    e_output または e_coutput 関数を使用する場合、[データ変換ジョブの作成] パネルでデフォルトのストレージ送信先を設定する必要があります。Simple Log Service は、1 のラベルが付いたストレージ送信先をデフォルトとして使用します。たとえば、データ変換ジョブは、e_output 関数の基準を満たすデータを、target_01、target_02、および target_03 のそれぞれの送信先 Logstore に送信します。ジョブは、変換中に破棄されなかった他のすべてのデータを、デフォルトのストレージ送信先 (target0) の送信先 Logstore に送信します。[ストレージ送信先] エリアで、2 つのストレージ送信先を設定します。ストレージ送信先 1: ターゲット名を target0 に、ターゲットリージョンを 中国 (杭州) に、ターゲットプロジェクトを Project0 に、送信先 Logstore を Logstore0 に、認証メソッドを デフォルトロールに設定します。ストレージ送信先 2: ターゲット名を target1 に、ターゲットリージョンを 中国 (杭州) に、ターゲットプロジェクトを Project1 に、送信先 Logstore を Logstore1 に、認証メソッドを デフォルトロールに設定します。

  • 高度なパラメーター設定

    `e_output` または `e_coutput` 関数を使用し、送信先のプロジェクトまたは Logstore が存在しない場合は、[データ変換ジョブの作成] パネルに移動します。[高度なパラメーター設定] セクションで、キーを config.sls_output.failure_strategy に、値を {"drop_when_not_exists":"true"} に設定して、ログをスキップします。スキップされたログは破棄され、警告レベルのログとして報告されます。[高度なパラメーター設定] を設定しない場合、データ変換ジョブは、実行前に送信先のプロジェクトと Logstore が作成されるのを待機します。

    警告

    [高度なパラメーター設定] を使用すると、送信先のプロジェクトまたは Logstore が存在しない場合、ログは破棄されます。この機能は注意して使用してください。

  • 結果

    • e_output：指定された Logstore にログを出力します。後続の変換ルールはこのログに対して実行されません。

    • e_coutput：指定された Logstore にログを出力します。後続の変換ルールはこのログに対して引き続き実行されます。

• 例

  • 例 1：k2 フィールドの値が正規表現に一致する場合、ログを target2 に出力し、topic を topic1 に設定します。

    • 生ログ

      __topic__:
      k1: v1
      k2: v2
      x1: v3
      x5: v4

    • 変換ルール

      ここでは e_drop() 関数を使用して、e_if() 関数によってフィルターされたデータを破棄します。この関数を追加しない場合、フィルターされたデータはデフォルトのストレージ送信先に配信されます。

      e_if(e_match("k2", r"\w+"), e_output(name="target2", source="source1", topic="topic1"))
      e_drop()

    • 結果

      __topic__:  topic1
      k1: v1
      k2: v2
      x1: v3
      x5: v4

  • 例 2：ログの db_version フィールドの値に基づいてハッシュを計算します。このハッシュ値に基づいて、ログをストレージ送信先の特定のシャードに出力します。

    • 生ログ

      __topic__:
      db_name: db-01
      db_version:5.6
      __topic__:
      db_name: db-02
      db_version:5.7

    • 変換ルール

      e_output(name="target1", hash_key_field="db_version")

    • 結果

      # ストレージ送信先 target1 に 2 つのシャードがあると仮定します。
      # シャード 0 の範囲は [00000000000000000000000000000000,80000000000000000000000000000000) です。
      # シャード 1 の範囲は [80000000000000000000000000000000,ffffffffffffffffffffffffffffffff) です。
      # db_version の値 5.6 と 5.7 のハッシュ値は、それぞれ 0ebe1a34e990772a2bad83ce076e0766 と f1867131d82f2256b4521fe34aec2405 です。
      # シャード 0：
      __topic__:
      db_name: db-01
      db_version:5.6
      # シャード 1：
      __topic__:
      db_name: db-02
      db_version:5.7

  • 例 3：ハッシュ値を直接指定して、ログをストレージ送信先の特定のシャードに出力します。

    • 生ログ

      __topic__:
      db_name: db-01
      db_version:5.6
      __topic__:
      db_name: db-02
      db_version:5.7

    • 変換ルール

      e_output(name="target1", hash_key="00000000000000000000000000000000")

    • 結果

      # ストレージ送信先に 2 つのシャードがあると仮定します。
      # シャード 0 の範囲は [00000000000000000000000000000000,80000000000000000000000000000000) です。
      # シャード 1 の範囲は [80000000000000000000000000000000,ffffffffffffffffffffffffffffffff) です。
      # シャード 0：
      __topic__:
      db_name: db-01
      db_version:5.6
      __topic__:
      db_name: db-02
      db_version:5.7
      # シャード 1：
      None

• 参照

  他の関数と組み合わせて使用できます。詳細については、「異なる Logstore のログデータを 1 つの Logstore に集約する」をご参照ください。

e_to_metric

ログを時系列 (Metricstore) フォーマットに変換します。

• 構文

  e_to_metric(names=None, labels=None, time_field='__time__', time_precision='s', ignore_none_names=True, ignore_none_labels=True)

• パラメーター

  パラメーター名	タイプ	必須	説明
  names	文字列、文字列リスト、またはタプルリスト	はい	時系列データのメトリック名。単一の文字列、文字列のリスト、またはタプルのリストにすることができます。その値は対応するログフィールド名です。 文字列：ログフィールドを時系列データのメトリック名に変換します。rt のような単一の文字列が含まれます。__name__:rt を含む時系列データレコードが返されます。 文字列リスト：ログフィールドを時系列データのメトリック名に変換します。["rt", "qps"] のような複数の文字列が含まれます。__name__:rt と __name__:qps をそれぞれ含む 2 つの時系列データレコードが返されます。 タプルリスト：複数のログフィールドを時系列データのメトリック名に変換し、名前を変更します。[("rt","max_rt"),("qps", "total_qps")] のような複数のタプルが含まれます。タプルの最初の要素は元のログフィールドで、2 番目の要素は変換された時系列データのメトリック名フィールドです。__name__:max_rt と __name__:total_qps をそれぞれ含む 2 つの時系列データレコードが返されます。
  labels	文字列、文字列リスト、またはタプルリスト	いいえ	時系列データのラベルフィールド。単一の文字列、文字列のリスト、またはタプルのリストにすることができます。その値は対応するログフィールド名です。 説明 以下の説明では、host と app はログフィールド名であり、hostvalue と appvalue はログフィールド値です。 文字列：ログフィールドを時系列データのラベルに変換します。host のような単一の文字列が含まれます。__label__:host#$#hostvalue を含む時系列データレコードが返されます。 文字列リスト：ログフィールドを時系列データのラベルに変換します。["host", "app"] のような複数の文字列が含まれます。__label__:host#$#hostvalue と __label__:app#$#appvalue をそれぞれ含む 2 つの時系列データレコードが返されます。 タプルリスト：複数のログフィールドを時系列データのラベルに変換し、名前を変更します。[("host","hostname"),("app", "appname")] のような複数のタプルが含まれます。タプルの最初の要素は元のログフィールドで、2 番目の要素は変換された時系列データのラベルフィールドです。__label__:hostname#$#hostvalue と __label__:appname#$#appvalue をそれぞれ含む 2 つの時系列データレコードが返されます。
  time_field	文字列	いいえ	時系列データの時間フィールド。デフォルトでは、ログの __time__ フィールドが使用されます。
  time_precision	Int	いいえ	生ログのタイムスタンプフィールドの時間単位。有効な値：秒、ミリ秒、マイクロ秒、ナノ秒。デフォルト：秒。たとえば、time_field="ms" は時間単位としてミリ秒を指定します。
  ignore_none_names	ブール値	いいえ	指定されたログフィールドが存在しない場合に変換をスキップするかどうか。 True (デフォルト)：変換をスキップします。データは時系列データに変換されません。 False：フィールドが存在しない場合、エラーを報告します。
  ignore_none_labels	ブール値	いいえ	指定されたログフィールドが存在しない場合にラベル変換をスキップするかどうか。 True (デフォルト)：変換をスキップします。データは時系列データに変換されません。 False：フィールドが存在しない場合、エラーを報告します。

• レスポンス

  時系列データを返します。

• 例

  • 例 1：rt フィールドを含むログを時系列データ形式に変換します。

    • 生ログ

      __time__: 1614739608
      rt: 123

    • 変換ルール

      e_to_metric(names="rt")

    • 結果

      __labels__:
      __name__:rt
      __time_nano__:1614739608000000000
      __value__:123.0

  • 例 2：rt フィールドを含むログを時系列データ形式に変換し、host フィールドを新しいラベルとして使用します。

    • 生ログ

      __time__: 1614739608
      rt: 123
      host: myhost

    • 変換ルール

      e_to_metric(names="rt", labels="host")

    • 結果

      __labels__:host#$#myhost
      __name__:rt
      __time_nano__:1614739608000000000
      __value__:123.0

  • 例 3：rt と qps フィールドを含むログを時系列データ形式に変換し、host フィールドを新しいラベルとして使用します。

    • 生ログ

      __time__: 1614739608
      rt: 123
      qps: 10
      host: myhost

    • 変換ルール

      e_to_metric(names=["rt","qps"], labels="host")

    • 結果

      __labels__:host#$#myhost
      __name__:rt
      __time_nano__:1614739608000000000
      __value__:123.0
      __labels__:host#$#myhost
      __name__:qps
      __time_nano__:1614739608000000000
      __value__:10.0

  • 例 4：rt と qps フィールドを含むログを時系列データ形式に変換し、フィールド名を max_rt と total_qps に置き換え、host フィールドを新しいラベルとして使用します。

    • 生ログ

      __time__: 1614739608
      rt: 123
      qps: 10
      host: myhost

    • 変換ルール

      e_to_metric(names=[("rt","max_rt"),("qps","total_qps")], labels="host")

    • 結果

      __labels__:host#$#myhost
      __name__:max_rt
      __time_nano__:1614739608000000000
      __value__:123.0
      __labels__:host#$#myhost
      __name__:total_qps
      __time_nano__:1614739608000000000
      __value__:10.0

  • 例 5：rt と qps フィールドを含むログを時系列データ形式に変換し、フィールド名を max_rt と total_qps に置き換え、host フィールドを hostname に名前を変更して新しいラベルとして使用します。

    • 生ログ

      __time__: 1614739608
      rt: 123
      qps: 10
      host: myhost

    • 変換ルール

      e_to_metric(names=[("rt","max_rt"),("qps","total_qps")], labels=[("host","hostname")])

    • 結果

      __labels__:hostname#$#myhost
      __name__:max_rt
      __time_nano__:1614739608000000000
      __value__:123.0
      __labels__:hostname#$#myhost
      __name__:total_qps
      __time_nano__:1614739608000000000
      __value__:10.0

  • 例 6：remote_user1 と request_length フィールドを含むログを時系列データ形式に変換し、フィールド名を remote_user2 と request_length1 に置き換え、status1 フィールドを新しいラベルとして使用します。

    • 生ログ

      __time__:1652943594
      remote_user:89
      request_length:4264
      request_method:GET
      status:200

    • 変換ルール

      # remote_user1 と status1 フィールドは存在しないため、無視されて変換されません。
      e_to_metric(
          names=[("remote_user1", "remote_user2"), ("request_length", "request_length1")],
          labels="status1",
          ignore_none_names=True,
          ignore_none_labels=True,
      )

    • 結果

      __labels__:
      __name__:request_length1
      __time_nano__:1652943594000000000
      __value__:4264.0

  • 例 7：remote_user フィールドを含むログを時系列データ形式に変換し、status フィールドを新しいラベルとして使用し、ソースログデータの時間単位をミリ秒として指定します。

    • 生ログ

      __time__:1652943594
      remote_user:89
      request_length:4264
      request_method:GET
      status:200

    • 変換ルール

      e_to_metric(
          names="remote_user",
          labels="status",
          time_precision="ms",
          ignore_none_names=True,
          ignore_none_labels=True,
      )

    • 結果

      __labels__:status#$#200
      __name__:remote_user
      __time_nano__:1652943594000000
      __value__:89.0

  • 例 8：remote_user フィールドを含むログを時系列データ形式に変換し、status フィールドを新しいラベルとして使用し、time フィールドを時系列データの時間フィールドとして使用し、ソースログデータの時間単位をナノ秒として指定します。

    • 生ログ

      time:1652943594
      remote_user:89
      request_length:4264
      request_method:GET
      status:200

    • 変換ルール

      e_to_metric(
          names="remote_user",
          labels="status",
          time_field="time",
          time_precision="ns",
          ignore_none_names=True,
          ignore_none_labels=True,
      )

    • 結果

      __labels__:status#$#200
      __name__:remote_user
      __time_nano__:1652943594
      __value__:89.0

• 参考資料

  他の関数と組み合わせて使用できます。詳細については、「Logstore のログフィールドを Metricstore のメトリックメジャーに変換する」をご参照ください。