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

関数

# The following four transformation rules are equivalent:
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"))

# The following transformation rules are invalid:
e_if(e_search("..."), KEEP)   
e_keep()

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

e_drop

e_drop関数は、指定された条件が満たされるとログを破棄します。

• e_drop(condition=True)

  識別子DROPがサポートされています。 識別子DROPは、e_drop() 関数に相当する。

• パラメーター	データ型	必須	説明
  condition	Bool	課金されません	デフォルト値は True です。 ほとんどの場合、1つの条件が関数に渡されます。

• 指定された条件が満たされると、ログは破棄され、Noneが返されます。 指定された条件が満たされない場合、ログが返されます。

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

    • Raw log:

      __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に評価された場合、ログを破棄します。

    • Raw log:

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール：

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

    • 結果：

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

  • 例3: 指定された条件がFalseに評価された場合、ログを保持します。

    • Raw log:

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール：

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

    • 結果：

      k1: v1
      k2: v2
      k3: k1

  • 例4: 条件を指定しない場合は、Trueを使用します。これは、ログが破棄されることを示します。

    • Raw log:

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール：

      e_drop()

    • 結果：

      ログは破棄されます。

• 関連ドキュメント

  この関数は、他の関数と一緒に使用できます。 詳細については、「データの複製と配布」をご参照ください。

e_keep

e_keep関数は、指定された条件が満たされるとログを保持します。

• e_keep(condition=True)

  識別子KEEPがサポートされています。 識別子KEEPは、e_keep() 関数に相当する。

• パラメーター	データ型	必須	説明
  condition	Bool	課金されません	デフォルト値は True です。 ほとんどの場合、1つの条件が関数に渡されます。

• 指定された条件が満たされると、ログが返されます。 指定された条件が満たされない場合、ログは破棄されます。

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

    • Raw log:

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

    • 変換ルール：

      e_keep(e_search("__programe__==access"))
      # Equivalent to:
      e_if(e_search("not __programe__==access"), DROP) 
      # Equivalent to:
      e_if_else(e_search("__programe__==access"), KEEP, DROP)  

    • 結果：

      __programe__ フィールドの値がaccessであるログは保持されます。

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

  • 例2: 指定された条件がTrueに評価された場合、ログを保持します。

    • Raw log:

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール：

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

    • 結果：

      k1: v1
      k2: v2
      k3: k1 

  • 例3: 指定された条件がFalseに評価された場合、ログを破棄します。

    • Raw log:

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール：

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

    • 結果：

      ログは破棄されます。

  • 例4: e_keep関数に値Falseを渡します。

    • Raw log:

      k1: v1
      k2: v2
      k3: k1

    • 変換ルール：

      e_keep(False)

    • 結果：

      ログは破棄されます。

• 関連ドキュメント

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

e_split

e_splitは、指定されたフィールドの値に基づいてログを複数のログに分割します。 JMESPath式を使用してフィールドの値を抽出し、ログを分割することもできます。

• e_split(Field name, sep=',', quote='"', lstrip=True, jmes=None, output=None)

  分割ルール:

  1. jmesパラメーターを設定すると、Simple Log Serviceはログフィールドの値をJSONリストに変換し、JMESPath式を使用してJSONリストから値を抽出し、次の操作でこれらの値を使用します。 jmesパラメーターを設定しない場合、Simple Log Serviceは次の操作でログフィールドの値を使用します。

  2. 前の操作で取得した値がリストまたはJSONリストを表す文字列である場合、Simple Log Serviceはリストに基づいてログを分割します。 それ以外の場合、Simple Log Serviceは、sep、quote、またはlstripパラメーターに基づいて値をCSV値に解析します。 次に、Simple Log Serviceは、解析された値に基づいてログを分割します。

• パラメーター	データ型	必須	説明
  フィールド名	String	課金されます	ログの分割に使用するフィールドの名前。 特別なフィールド名を指定する方法の詳細については、「イベントタイプ」をご参照ください。
  sep	String	課金されません	値を区切るために使用する区切り文字。
  quote	String	課金されません	値を囲むために使用する引用符。
  lstrip	String	課金されません	値の左側のスペースを削除するかどうかを指定します。 デフォルト値は True です。
  jmes	String	課金されません	フィールドの値をJSONオブジェクトに変換し、JSONオブジェクトから値を抽出するために使用するJMESPath文字列。 Simple Log Serviceは、JSONオブジェクトに基づいてログを分割します。
  アウトプット	String	課金されません	フィールドの新しい名前。デフォルトで既存の名前を上書きします。

• ログのリストが返されます。 返されるログのフィールドの値は、生ログのフィールドの値と同じです。

• • Raw log:

    __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データの変換」をご参照ください。

e_outputおよびe_coutput

e_output関数とe_coutput関数は、指定された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に書き込まれます。 データ変換結果を初めてプレビューすると、Simple Log Serviceは、現在のプロジェクトにinternal-etl-logという名前の専用ログストアを自動的に作成します。 このLogstoreの設定を変更したり、他のデータをLogstoreに書き込むことはできません。 このLogstoreは課金されません。

• 説明

  e_outputまたはe_coutput関数でname、project、logstoreパラメーターを設定し、[データ変換ルールの作成] パネルでプロジェクトと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ペアを使用してデータ変換を許可する場合、保存先で指定されたAccessKeyペアがデータ変換に使用されます。

  パラメーター	データ型	必須	説明
  name	String	課金されません	保存先の名前。 デフォルト値 : なし。
  project	String	課金されません	ログが書き込まれる既存のプロジェクト。
  logstore	String	課金されません	ログが書き込まれる既存のLogstore。
  topic	String	課金されません	ログの新しいトピック。
  source	String	課金されません	ログの新しいソース。
  tags	ディクト	課金されません	ログの新しいタグ。 タグは辞書形式です。 説明 キーワードのプレフィックスに __tag __: を付ける必要はありません。
  hash_key_field	String	課金されません	ハッシュに使用されるフィールドの名前。 ログは、フィールドのハッシュ値に基づいて指定した格納先のシャードに書き込まれます。 説明 ログに指定したフィールドが含まれていない場合、ログはロードバランシングモードで指定したストレージ先のシャードにランダムに書き込まれます。
  hash_key	String	課金されません	ハッシュ値。 ログは、ハッシュ値に基づいて指定した格納先のシャードに書き込まれます。 説明 hash_key_fieldパラメーターは、hash_keyパラメーターよりも優先度が高くなります。 hash_key_fieldパラメーターが変換ルールで設定されている場合、hash_keyパラメーターは有効になりません。

  • デフォルトの保存先

    e_outputまたはe_coutput関数を使用するには、[データ変換ルールの作成] パネルでデフォルトの保存先を設定する必要があります。 デフォルトでは、Simple Log Serviceは1というラベルの付いた格納先をデフォルトの格納先として使用します。 次の図では、変換結果はtarget_01、target_02、およびtarget_03に対応するLogstoreに送信されます。 変換中に破棄されなかったデータは、target_00という名前のデフォルトの保存先に対応するLogstoreに保存されます。

  • 高度なパラメータ設定

    e_output関数またはe_coutput関数で指定したプロジェクトまたはLogstoreが存在しない場合は、[データ変換ルールの作成] パネルの [詳細パラメーター設定] セクションでキーと値のペアを指定できます。 ログをスキップするには、keyをconfig.sls_output.failure_strategyに設定し、keyの値を {"drop_when_not_exists":"true"} に設定します。 スキップされたログは破棄され、警告ログとして報告されます。 [詳細パラメーター設定] セクションでキーと値のペアを指定しない場合、指定したプロジェクトまたはLogstoreが作成されるまで、データ変換ジョブは中断されます。

    警告

    指定されたプロジェクトまたはログストアが存在せず、[詳細パラメーター設定] セクションでキーと値のペアを指定してログをスキップすると、スキップされたログは破棄されます。 作業は慎重に行ってください。

    

  • 結果：

    • e_output: 指定されたLogstoreにログを書き込みます。 後続の変換ルールはログに対して実行されません。

    • e_coutput: 指定されたLogstoreにログを書き込みます。 後続の変換ルールは、ログに対して実行される。

• • 例1: ログのk2フィールドの値を正規表現に対して評価します。 値が正規表現を満たしている場合は、target2で指定されたLogstoreにログを書き込み、topicをtopic1に設定します。

    • Raw log:

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

    • 変換ルール：

      e_drop() 関数は、e_if() 関数の条件を満たさないデータを削除します。 変換ルールに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フィールドの値に基づいてログのハッシュ値を計算し、ハッシュ値に基づいて指定したストレージ先のシャードにログを書き込みます。

    • Raw log:

      __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")

    • 結果：

      # For example, the storage destination named target1 has two shards. 
      # The MD5 hash range of Shard 0 is [00000000000000000000000000000000,80000000000000000000000000000000). 
      # The MD5 hash range of Shard 1 is [80000000000000000000000000000000,ffffffffffffffffffffffffffffffff). 
      # The hash values for logs whose values of the db_version field are 5.6 and 5.7 are 0ebe1a34e990772a2bad83ce076e0766 and f1867131d82f2256b4521fe34aec2405. 
      
      # Shard 0:
      __topic__:
      db_name: db-01
      db_version:5.6
      
      # Shard 1:
      __topic__:
      db_name: db-02
      db_version:5.7

  • 例3: ログのハッシュ値を指定し、ハッシュ値に基づいて指定したストレージ先のシャードにログを書き込みます。

    • Raw log:

      __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")

    • 結果：

      # For example, the storage destination has two shards. 
      # The MD5 hash range of Shard 0 is [00000000000000000000000000000000,80000000000000000000000000000000). 
      # The MD5 hash range of Shard 1 is [80000000000000000000000000000000,ffffffffffffffffffffffffffffffff). 
      
      # Shard 0:
      __topic__:
      db_name: db-01
      db_version:5.6
      
      __topic__:
      db_name: db-02
      db_version:5.7
      
      # Shard 1:
      None

• 関連ドキュメント

  この関数は、他の関数と一緒に使用できます。 詳細については、「複数のソースLogstoreからのデータの集約」をご参照ください。

e_to_metric

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	文字列、文字列リスト、またはタプルリスト	課金されます	メトリックの名前。 namesパラメーターの値は、単一の文字列、文字列リスト、またはタプルリストにすることができます。 値は、変換するログ内のフィールドの名前です。 String: ログフィールドの名前は、メトリックの名前として使用されます。 値は文字列です。 例: rt. __name __: rtを含むメトリックレコードが返されます。 文字列リスト: ログフィールドの名前は、メトリックの名前として使用されます。 値は複数の文字列で構成されます。 例: ["rt", "qps"] 。 この例では、2つのメトリックレコードが返されます。 一方のレコードには __name __: rtが含まれ、もう一方のレコードには __name __: qpsが含まれます。 タプルリスト: 複数のログフィールドの名前がメトリックの名前として使用され、メトリックの名前が変更されます。 値は複数のタプルで構成されます。 例: [("rt", "max_rt"),("qps", "total_qps")] 。 この例では、タプルの最初の要素は生ログフィールドの名前です。 タプルの2番目の要素は、変換後に生成されるメトリックの名前です。 2つのメトリックレコードが返されます。 一方のレコードには __name __: max_rtが含まれ、もう一方のレコードには __name __: total_qpsが含まれます。
  labels	文字列、文字列リスト、またはタプルリスト	課金されません	メトリックのラベル。 labelsパラメーターの値は、単一の文字列、文字列リスト、またはタプルリストにすることができます。 値は、変換するログ内のフィールドの名前です。 説明 次のリストでは、hostとappはログフィールドの名前であり、hostvalueとappvalueはログフィールドの値です。 String: ログフィールドの名前は、メトリックのラベルとして使用されます。 値は文字列です。 例: host。 __label __: host #$# hostvalueを含むメトリックレコードが返されます。 文字列リスト: ログフィールドの名前は、メトリックのラベルとして使用されます。 値は複数の文字列で構成されます。 例: ["host", "app"] 。 この例では、2つのメトリックレコードが返されます。 一方のレコードには __label __: host #$# hostvalueが含まれ、もう一方のレコードには __label __: app #$# appvalueが含まれます。 タプルリスト: 複数のログフィールドの名前がメトリックのラベルとして使用され、ラベルの名前が変更されます。 値は複数のタプルで構成されます。 例: [("host", "hostname"),("app", "appname")] 。 この例では、タプルの最初の要素は生ログフィールドの名前です。 タプルの2番目の要素は、変換後に生成されるメトリックのラベルです。 2つのメトリックレコードが返されます。 一方のレコードには __label __: hostname #$# hostvalueが含まれ、もう一方のレコードには __label __: appname #$# appvalueが含まれます。
  time_field	String	課金されません	メトリックの時間フィールド。 デフォルトでは、ログの __time__ フィールドがメトリックの時間フィールドとして使用されます。
  time_precision	Int	課金されません	生ログの時間フィールドの単位。 サポートされる単位は、秒、ミリ秒、マイクロ秒、およびナノ秒です。 デフォルトでは、ログは秒単位で保存されます。 たとえば、time_field="ms" は、生ログの時間フィールドの単位がミリ秒であることを示します。
  ignore_none_names	ブール値	課金されません	ログフィールドが存在しない場合、ログからメトリックへの変換をスキップするかどうかを指定します。 有効な値： True: ログからメトリックへの変換をスキップします。 デフォルト値です。 False: 変換をスキップせず、エラーを報告します。
  ignore_none_labels	ブール値	課金されません	ログフィールドが存在しない場合、ログからメトリックへの変換をスキップするかどうかを指定します。 有効な値： True: ログからメトリックへの変換をスキップします。 デフォルト値です。 False: 変換をスキップせず、エラーを報告します。

• メトリックが返されます。

• • 例1: rtフィールドを含むログをメトリックに変換します。

    • Raw log:

      __time__: 1614739608
      rt: 123

    • 変換ルール：

      e_to_metric(names="rt")

    • 結果：

      __labels__:
      __name__:rt
      __time_nano__:1614739608000000000
      __value__:123.0

  • 例2: rtフィールドを含むログをメトリックに変換し、ラベルをhostに設定します。

    • Raw log:

      __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に設定します。

    • Raw log:

      __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フィールドを含むログをメトリックに変換し、rtおよびqpsフィールドの名前をmax_rtおよびtotal_qpsに変更し、ラベルをhostに設定します。

    • Raw log:

      __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フィールドを含むログをメトリックに変換し、rtおよびqpsフィールドの名前をmax_rtおよびtotal_qpsに変更し、ラベルをhostに設定し、hostの名前をhostnameに変更します。

    • Raw log:

      __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_user1およびrequest_lengthフィールドの名前をremote_user2およびrequest_length1に変更し、ラベルをstatus1に設定します。

    • Raw log:

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

    • 変換ルール：

      # The remote_user1 and status1 fields do not exist in the log and the conversion is skipped. 
      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に設定し、ログの時間フィールドの単位としてミリ秒を指定します。

    • Raw log:

      __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フィールドとして指定し、ナノ秒をログのtimeフィールドの単位として指定します。

    • Raw log:

      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

• 関連ドキュメント

  この関数は、他の関数と一緒に使用できます。 詳細については、「ログをメトリクスに変換する」をご参照ください。