全部產品
Search

搜尋本產品

    Simple Log Service：事件操作函數

    文件中心

    Simple Log Service：事件操作函數

    更新時間：Jun 30, 2024

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

    函數列表

    類型函數說明
    事件操作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的日誌資料匯總到一個Logstore。

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

    支援和其他函數組合使用。相關樣本，請參見將Logstore中的日誌欄位轉換MetricStore中的度量指標。

    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函數時，需要在建立資料加工任務面板中配置一個預設儲存目標，Log Service預設以標號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滿足Regex，輸出到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的日誌資料匯總到一個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

    • 更多參考

      支援和其他函數組合使用。相關樣本，請參見將Logstore中的日誌欄位轉換MetricStore中的度量指標。