本文介紹事件操作函數的語法規則，包括參數解釋、函數示例等。

函數列表

類型函數說明
事件操作e_drop根據條件判斷是否丟棄日志。

支持和其他函數組合使用。相關示例，請參見復制和分發數據。

e_keep根據條件判斷是否保留日志。
e_keep函數和e_drop函數都會丟棄日志。e_keep函數在不滿足條件時丟棄，而e_drop函數則是在滿足條件時丟棄。 
# 以下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()

支持和其他函數組合使用。相關示例，請參見復雜JSON數據加工。

事件分裂e_split基于日志字段的值分裂出多條日志，并且支持通過JMES提取字段后再進行分裂。

支持和其他函數組合使用。相關示例，請參見復雜JSON數據加工。

輸出事件e_output、e_coutput輸出日志到指定的Logstore中，并可配置輸出時的topic、source、tag和shard hash信息。
  • e_output：執行到e_output函數時，輸出日志到指定的Logstore中，且對應的日志不再執行后面的加工規則。
  • e_coutput：執行到e_coutput函數時，輸出日志到指定的Logstore中，且對應的日志繼續執行后面的加工規則。

支持和其他函數組合使用。相關示例，請參見多源Logstore數據匯總。

事件轉換成時序數據e_to_metric將日志格式轉化為時序存儲（MetricStore）的格式。
說明 加工為時序數據格式后，保存加工結果時請選擇目標庫為時序庫。
典型的時序數據如下所示：
__labels__:host#$#myhost
__name__:rt
__time_nano__:1614739608000000000
__value__:123.0
更多信息，請參見時序數據（Metric）。

支持和其他函數組合使用。相關示例，請參見轉換Log為Metric。

e_drop

根據條件判斷是否丟棄日志。

  • 函數格式

    e_drop(condition=True)

    支持固定標識DROP，等價于e_drop()。

  • 參數說明

    參數名稱參數類型是否必填說明
    conditionBool否默認為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()。

  • 參數說明

    參數名稱參數類型是否必填說明
    conditionBool否默認為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

基于日志字段的值分裂出多條日志，并且支持通過JMES提取字段后再進行分裂。

  • 函數格式

    e_split(字段名, sep=',', quote='"', lstrip=True, jmes=None, output=None)
    分裂規則：
    1. 如果配置了jmes參數，則將日志字段的值轉化為JSON列表，并使用JMES提取值作為下一步的值。如果沒有配置jmes參數，則將字段的值直接作為下一步的值。
    2. 如果上一步的值是一個列表或JSON列表格式的字符串，則按照此列表分裂并結束處理。否則使用sep、quote或lstrip將上一步的值進行CSV解析，根據解析后的多個值進行分裂并結束處理。

  • 參數說明

    參數名稱參數類型是否必填說明
    字段名String是需要分裂的字段名。特殊字段名的設置請參見事件類型。
    sepString否用于分隔多個值的分隔符。
    quoteString否用于引用多個值的配對類字符的引用符。
    lstripString否是否將值左邊的空格去掉，默認為True。
    jmesString否將字段值轉化為JSON對象，并使用JMES提取特定值，再進行分裂操作。
    outputString否設置一個新的字段名，默認覆蓋舊字段名。

  • 返回結果

    返回日志列表，列表中字段的值都是源列表中的值。

  • 函數示例

    • 原始日志
      __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

輸出日志到指定的Logstore中，并可配置輸出時的topic、source、tag等信息。

  • 函數格式

    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是您首次執行數據加工預覽時，系統在當前Project下自動創建的專屬Logstore，不支持修改配置及寫入其他數據，不收取任何費用。

  • 參數說明

    說明 如果您在e_output函數、e_coutput函數中配置了name、project、logstore參數，在后續創建數據加工任務面板中又配置了目標Project、目標庫，則以e_output函數、e_coutput函數配置為準。具體說明如下所示：
    • 如果您在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信息。

    參數名稱參數類型是否必填說明
    nameString否存儲目標的目標名稱，默認為None。
    projectString否輸出日志到已存在的Project。
    logstoreString否輸出日志到已存在的Logstore。
    topicString否為日志設置新的日志主題。
    sourceString否為日志設置新的日志來源信息。
    tagsDict否為日志設置新的標簽，以字典格式傳入。
    說明 關鍵字不需要加__tag__:前綴。
    hash_key_fieldString否指定日志的一個字段名。加工任務基于該字段Hash值，將日志輸出到存儲目標的特定Shard。
    說明 如果日志中不存在指定字段，則自動切換到負載均衡模式，將日志隨機寫入存儲目標的某個Shard上。
    hash_keyString否指定一個Hash值。加工任務將日志固定輸出到存儲目標的特定Shard。
    說明 hash_key_field參數優先級高于該參數，即加工語法中已經配置hash_key_field參數時，該參數不起作用。
    • 設置默認存儲目標
      您在使用e_output函數、e_coutput函數時，需要在創建數據加工任務面板中配置一個默認存儲目標，日志服務默認以標號1中配置的存儲目標為默認存儲目標。例如：下圖中，符合e_output函數加工規則的數據分別投遞到target_01、target_02、target_03下的目標Logstore中，其他在加工過程中沒有被丟棄的數據存儲到默認存儲目標（target_00）下的目標Logstore中。默認存儲目標
    • 高級參數配置
      使用e_output函數、e_coutput函數時，如果配置的目標Project、Logstore不存在，您可以在創建數據加工任務面板中，將高級參數配置中的key設置為config.sls_output.failure_strategy，value設置為{"drop_when_not_exists":"true"} 來跳過該日志，被跳過的日志會被丟棄，并且上報為warning級別的日志。如果不設置高級參數配置，數據加工任務將一直等待目標Project、Logstore被創建后再執行加工任務。
      警告 您在使用高級參數配置解決目標Project、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字段的值計算Hash，并根據此Hash值將日志固定輸出到存儲目標的特定Shard上。
      • 原始日志
        __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個Shard。
# Shard 0的范圍[00000000000000000000000000000000,80000000000000000000000000000000)。
# Shard 1的范圍[80000000000000000000000000000000,ffffffffffffffffffffffffffffffff)。
# db_version的取值5.6和5.7，對應的Hash值分別為0ebe1a34e990772a2bad83ce076e0766和f1867131d82f2256b4521fe34aec2405。

# Shard 0:
__topic__:
db_name: db-01
db_version:5.6

# Shard 1:
__topic__:
db_name: db-02
db_version:5.7
    • 示例3：直接指定Hash值，將日志固定輸出到存儲目標的特定Shard上。
      • 原始日志
        __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個Shard。
# Shard 0的范圍[00000000000000000000000000000000,80000000000000000000000000000000)。
# Shard 1的范圍[80000000000000000000000000000000,ffffffffffffffffffffffffffffffff)。

# Shard 0:
__topic__:
db_name: db-01
db_version:5.6

__topic__:
db_name: db-02
db_version:5.7

# Shard 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)

  • 參數說明

    參數名稱參數類型是否必填說明
    namesString、StringList、Tuple List是時序數據的Metric名稱，可以是單個字符串、多個字符串列表或者元組列表，其值為對應日志字段名稱。
    • String：將一個日志字段轉換為時序數據的Metric名稱。包含一個字符串，例如取值為rt。返回一條包含__name__:rt的時序數據。
    • StringList：將日志字段轉換為時序數據的Metric名稱。包含多個字符串，例如取值為["rt", "qps"]。返回兩條時序數據，分別包含__name__:rt和__name__:qps。
    • Tuple List：將多個日志字段轉換為時序數據的Metric名稱，并重新命名。包含多個元組，例如取值為 [("rt","max_rt"),("qps", "total_qps")] 。元組的第一個元素是原日志字段，第二個為加工后的時序數據Metric名稱字段。返回兩條時序數據，分別包含__name__:max_rt和__name__:total_qps。
    labelsString、StringList、Tuple List否時序數據的labels信息字段，可以是單個字符串、多個字符串列表或者元組列表，其值為對應日志字段名稱。
    說明 如下描述中host和app為日志字段名稱，hostvalue和appvalue為日志字段的值。
    • String：將一個日志字段轉換為時序數據的labels信息。包含一個字符串，例如取值為host。返回一條包含__label__:host#$#hostvalue的時序數據。
    • StringList：將日志字段轉換為時序數據的labels信息。包含多個字符串，例如取值為["host", "app"]。返回兩條時序數據，分別包含__label__:host#$#hostvalue和__label__:app#$#appvalue。
    • Tuple List：將多個日志字段轉換為時序數據的labels信息，并重新命名。包含多個元組，例如取值[("host","hostname"),("app", "appname")] 。元組的第一個元素是原日志字段，第二個為加工后的時序數據labels信息字段。返回兩條時序數據，分別包含__label__:hostname#$#hostvalue和__label__:appname#$#appvalue。
    time_fieldString否時序數據的時間字段。默認使用日志中__time__字段作為時序數據的時間字段。
    time_precisionInt否原始日志數據時間字段的時間單位，支持秒、毫秒、微秒、納秒。默認按照秒存儲。例如time_field="ms"表示原日志數據時間單位為毫秒。
    ignore_none_namesBoolean否日志字段不存在時，是否忽略轉換為時序數據。
    • True（默認值）：忽略，即不轉換為時序數據。
    • False：不忽略，不存在時上報錯誤。
    ignore_none_labelsBoolean否日志字段不存在時，是否忽略轉換為時序數據。
    • 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字段作為新增labels信息字段。
      • 原始日志
        __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字段作為新增labels信息字段。
      • 原始日志
        __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字段作為新增labels信息字段。
      • 原始日志
        __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后作為新增labels信息字段。
      • 原始日志
        __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字段作為新增labels信息字段。
      • 原始日志
        __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字段作為新增labels信息字段，并指定原始日志數據時間單位為毫秒。
      • 原始日志
        __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字段作為新增labels信息字段，將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

  • 更多參考

    支持和其他函數組合使用。相關示例，請參見轉換Log為Metric。