文法簡介 - Simple Log Service

SLS DSL基於Python語言開發，提供兩百多個內建函數來簡化資料加工任務。本文介紹DSL的語言模式、分類和運行原理等。

語言模式

SLS DSL相容Python，標準模式下，SLS DSL可視為Python的子集。除基本的資料結構與表達方式外，文法規則是以函數方式進行編排。如果您有特定UDF的需求，請提交工單。

類別	Python文法	標準模式
資料結構	數字、字串、布爾	支援。不支援`"""`形式字串。
	元組、列表、集合、字典	支援。不支援集合`set`如`{1,2,3}`。
	對象	僅支援內建擴充資料結構，如表格、日期時間對象等。
基本文法	操作符，如加減乘除等	支援比較子（`==、!=、>`等）和邏輯運算子（and、or、not），其餘不直接支援，需要通過函數支援。
	注釋	支援。
	變數定義賦值	不支援，需使用函數調用傳遞。
	條件	支援。例如e_if、e_if_else、e_switch函數。
	迴圈	不直接支援，可通過內建函數嵌套實現。例如如下遍曆數組： `e_if(op_ge(op_len(json_parse(v("x"))), 1), e_set("x0", lst_get(v("x"), 0))) e_if(op_ge(op_len(json_parse(v("x"))), 2), e_set("x1", lst_get(v("x"), 1)))`
函數	標準Python內建函數	不支援。使用200+內建函數。
	函數調用	支援。解包調用不支援。
	自訂函數def或lambda	不支援，提供兩百多個全域操作函數與運算式函數，且支援基於現有函數的自由組合調用。
模組	匯入與使用Python標準庫	不支援。
	線程與進程建立	不支援。
	匯入第三方庫	不支援。
	外部網路連接或命令調用	支援內建的資源連接器。

函數分類

標準模式的SLS DSL是通過調用函數的方式完成的，其內建兩百多個函數，主要分為兩類：

全域操作函數
主要用來接收日誌，處理並返回日誌的函數。且只有全域操作函數才能構建加工規則的每個步驟。
運算式函數
通用型函數，接受特定參數，組合調用後作為參數傳遞給全域操作函數以定義更加靈活的邏輯。

兩類函數功能對比：

函數類型	全域步驟	接收	返回	修改日誌	組合調用
全域操作函數	支援	自動接收日誌	0到多條日誌	支援大部分情況	支援
運算式函數	不支援	除個別函數支援，大部分不直接處理日誌。	特定資料結構	不支援	支援

全域操作函數

接受日誌並返回日誌的函數。

說明除全域函數外，其他內建函數不能放在每個步驟的第一行。

一個SLS DSL規則的形式如下：

全域函數1(..參數....)
全域函數2(..參數....)
全域函數3(..參數....)
全域函數4(..參數....)

全域操作函數可以分為兩類：

函數分類	描述	範例
流程式控制制函數	用於步驟流程式控制制，接收日誌，基於條件控制調用其他日誌函數完成Tlog。	`e_if`、`e_switch`、`e_if_else`等。
事件處理函數	對日誌進行加工的函數。返回0到多條日誌。	函數範例如下： `e_drop_fields`丟棄日誌欄位。 `e_kv`提取並添加日誌的索引值對。 `e_dict_map`給日誌做富化。

加工邏輯：

基本處理：
資料加工會以流式方式讀取源Logstore的資料，並將每一條日誌以字典的資料結構傳遞給加工規則，然後根據加工規則中定義的日誌函數順序處理日誌資料，並將最終的資料加工結果輸出到目標Logstore。
說明在傳遞的過程中日誌的欄位和值始終都是字串形式。例如：原日誌是{"__time__": "1234567", "__topic__": "", "k1": "test"}，函數e_set("f1", 200)設定欄位f1的值為200，經過這個函數處理後，原日誌會變成：{"__time__": "1234567", "__topic__": "", "k1": "test", "f1": "200"}，其中f1和200都是字串類型。
規則中定義的每個日誌函數會順序執行，每個函數會對每個日誌進行處理和修改，最後返回修改後的日誌。
例如e_set("type", "test")會對每個日誌添加一個欄位type，值為test，下一個函數接收到的就是修改後的日誌。
條件判斷：
- 條件判斷e_if：某些日誌可以增加條件判斷，不滿足條件的日誌就會跳過本次操作，相當於一個if的邏輯。
  例如e_if(e_match("status", "200"), e_regex("data", "ret: \d+", "result"))，會首先判斷欄位status是否為200，如果條件判斷為真，則會對欄位data用Regex提取出新欄位result；如果條件判斷為否，則不會執行任何操作。
- e_if_else：與if_else操作類似。
停止處理：
- 某些步驟可能返回0個日誌，表示刪除日誌。
  例如e_if(str_islower(v("result")), e_drop())，如果每個result欄位的值是小寫字串，則丟棄這條日誌，後續的操作將不再進行，自動重新開始下一條日誌。
- 輸出日誌可以視為一種特殊的停止處理，例如e_output提前輸出日誌到目標並刪除日誌，其後續的操作也不會再進行。
  說明函數e_coutput會複製一份當前的日誌輸出，並繼續處理後續。
分裂並行：
某些步驟也可能返回多個日誌，表示分裂日誌。
例如e_split(data)，表示根據欄位data的值將原本的一條日誌分裂成兩條日誌。假如data的值是"abc, xyz"，則分裂後兩條日誌欄位data的值分別是abc和xyz。
分裂後的每條日誌都會繼續進行後續的步驟。

運算式函數

除了全域操作函數外，SLS DSL還提供200個運算式函數，接收特定參數，返回特定的值，一般是單個運算式函數或其調用組合。形式如下：

全域操作1(運算式函數1(...), ....)
全域操作2(..., 運算式函數2(...), 運算式函數3(...),...)

運算式函數大概可以分為四類：

函數分類	描述	範例
事件檢查函數	接收日誌，提取或檢索返回特定資訊的函數，不會修改傳遞的日誌。	函數`v`返回日誌欄位的值。函數`e_search`和`e_match`返回日誌是否符合特定的條件。
資源函數	串連本地或外部資源，接收特定參數配置並返回資料，一般是字典、表格等類型。	OSS、RDS、Logstore資源函數。
控制函數	用於運算式的邏輯操作，接收特定參數並基於條件做控制，調用其他運算式函數返回結果。	`op_and`、`op_or`、`op_not`、`op_if`、`op_coalesce`等。
其他運算式函數	接受固定或者其他函數的調用結果，返回特定的值。	字串、時間、類型轉換函式等。