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_if(e_search("..."), KEEP)   
e_keep()

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

e_drop

条件に応じてログを破棄します。

• 構文

  e_drop(condition=True)

  固定識別子 DROP を使用でき、これは e_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)

  固定識別子 KEEP を使用でき、これは e_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

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

• 構文

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

  分割ルール：

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

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

• パラメーター

  パラメーター名	型	必須	説明
  field_name	文字列	はい	分割対象のフィールド名です。特殊なフィールド名の設定方法については、「イベントタイプ」をご参照ください。
  sep	文字列	いいえ	複数の値を分割する際に使用する区切り文字です。
  quote	文字列	いいえ	値を囲む引用符として使用する文字です。
  lstrip	文字列	いいえ	値の左側の空白を削除するかどうかを指定します。デフォルト値は True です。
  jmes	文字列	いいえ	フィールド値を JSON オブジェクトに変換し、JMESPath を使用して特定の値を抽出した後、分割操作を実行します。
  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 には送信されず、代わりに internal-etl-log Logstore へ送信されます。internal-etl-log Logstore は、データ変換ジョブのプレビューを初めて実行したときに、現在のプロジェクト内に自動的に作成される専用 Logstore です。この Logstore の構成を変更したり、他のデータを書き込んだりすることはできません。この Logstore は無料です。

• パラメーター

  説明

  e_output または e_coutput 関数内で name、project、Logstore パラメーターを指定し、かつ「データ変換ジョブの作成」パネルで送信先プロジェクトおよびデータベースを設定した場合、e_output または e_coutput 関数内の設定が優先されます。詳細は以下の通りです：

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

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

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

  • e_output 関数内で name、project、Logstore パラメーターをすべて設定した場合、変換結果は e_output 関数内で指定した送信先 Logstore に分散・格納されます。

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

  パラメーター名	型	必須	説明
  name	文字列	いいえ	保存先の名前です。デフォルト値は None です。
  project	文字列	いいえ	既存のプロジェクトへログを出力します。
  Logstore	文字列	いいえ	既存の Logstore へログを出力します。
  topic	文字列	いいえ	ログの新しいトピックを設定します。
  source	文字列	いいえ	ログの新しいソースを設定します。
  tags	辞書	いいえ	ログの新しいタグを設定します。タグは辞書形式で渡します。 説明 キーワードに __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 へ配信されます。変換中に破棄されなかったその他のデータは、デフォルトの保存先 Logstore（target_00）へ格納されます。

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

    `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：
      なし

• 参考資料

  この関数は他の関数と併用可能です。詳細については、「複数の Logstore から集約したログデータを 1 つの Logstore に格納する」をご参照ください。

e_to_metric

ログを時系列ストレージ形式に変換します。

• 構文

  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")]）を含みます。タプルの第 1 要素は元のログフィールド、第 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")]）を含みます。タプルの第 1 要素は元のログフィールド、第 2 要素は変換後の時系列データのラベルフィールドです。結果として、__label__:hostname#$#hostvalue および __label__:appname#$#appvalue をそれぞれ含む 2 件の時系列データレコードが返されます。
  time_field	文字列	いいえ	時系列データの時間フィールドです。デフォルトでは、ログ内の __time__ フィールドが時系列データの時間フィールドとして使用されます。
  time_precision	整数	いいえ	生ログのデータタイムスタンプフィールドの時間単位は、秒、ミリ秒、マイクロ秒、ナノ秒のいずれかです。デフォルトは秒です。たとえば、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 内のメトリック測定値に変換する」をご参照ください。