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

函數列表

類型函數說明
事件操作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列表格式的字符串,則按照此列表分裂并結束處理。否則使用sepquotelstrip將上一步的值進行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_strategyvalue設置為{"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:將rtqps字段所在的日志轉換為時序數據格式,并將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:將rtqps字段所在的日志轉換為時序數據格式,替換字段名稱為max_rttotal_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:將rtqps字段所在的日志轉換為時序數據格式,替換字段名稱為max_rttotal_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_user1request_length字段所在的日志轉換為時序數據格式,替換字段名稱為remote_user2request_length1,并將status1字段作為新增labels信息字段。
      • 原始日志
        __time__:1652943594
        remote_user:89
        request_length:4264
        request_method:GET
        status:200
      • 加工規則
        # remote_user1status1不存在,忽略,即不做轉換。
        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