一、如何定義 DeepFlow Wasm Plugin ？

DeepFlow 的 Wasm Plugin 機制是整個 DeepFlow Pipeline 機制中的重要組成部分，它為用戶提供了一個可編程的、安全的和資源消耗可控的運行沙箱環境。此機制為 deepflow-agent 增加了靈活性和可擴展性，使用戶能夠以一種安全可靠的方式自定義和擴展代理的功能。

1、Wasm Plugin 機制為用戶提供了可編程性

通過使用 Wasm 編程語言，用戶可以編寫自定義的插件邏輯，以滿足特定的需求和應用場景。這種可編程性使得用戶能夠根據具體的業務需求，對流量進行更細粒度的處理和分析。用戶可以通過編寫自定義的 Wasm 模塊來實現特定的協議解析、數據處理、安全策略等功能，從而高度定制化代理的行為。

2、Wasm Plugin 機制提供了安全性

Wasm Plugin 運行在一個安全的沙箱環境中，這意味著插件的執行受到嚴格的限制和監控，以確保其不會對代理的穩定性和安全性造成威脅。Wasm 的設計理念和安全機制使得插件的運行受到嚴格的隔離，防止惡意插件對代理或底層系統進行攻擊或濫用資源。這種安全性保證了代理的運行環境的可信度和可靠性。

3、Wasm Plugin 機制還具有資源消耗可控性

通過限制插件的資源使用，例如 CPU 時間、內存等，Agent 可以有效地控制插件的運行消耗，以避免插件對代理性能產生不利影響。這種資源消耗可控性使得代理能夠在處理大規模流量時保持高效和穩定，避免因插件的運行而引起的性能下降或崩潰。

綜上，DeepFlow Wasm Plugin 機制通過增強原生支持的協議、支持私有協議解析、提供零侵擾分布式追蹤和自定義脫敏功能等，為用戶提供了更強大和靈活的工具。這些增強功能使得用戶能夠深入分析和處理協議數據，滿足不同業務場景需求，并提升系統的性能、安全性和可擴展性。

二、DeepFlow Wasm Plugin 到底是如何工作的？

在深入了解 Wasm Plugin 的執行流程之前，建議先對 Deepflow 協議解析有一個基本的認識。了解 Deepflow 協議解析的概念和原理可以為理解 Wasm Plugin 的執行流程提供有益的背景知識。

當我們提及 Wasm Plugin 時，通常作用于 Web 瀏覽器中執行高性能的計算任務，而 Deepflow 協議解析則涉及到數據傳輸和處理的協議層面。通過深入了解 Deepflow 協議解析，我們可以更好地理解 Wasm Plugin 在數據傳輸和處理過程中的作用和應用。因此，在探討 Wasm Plugin 的執行流程之前，對 Deepflow 協議解析進行一個基本的認識是非常有幫助的，它為我們建立起了一個更完整和全面的技術背景，使我們能夠更好地理解和應用 Wasm  Plugin 的相關概念和功能。

在 deepflow-agent 中，數據包從原始字節轉化為應用層結構的過程涉及以下幾個關鍵階段。在這些階段中，我們會使用到一些重要的數據結構和接口，它們發揮著關鍵的作用，具體可參考：

1、L7Protocol（第七層協議）：其源碼位于 l7_protocol.rs 文件中。L7Protocol 用于標識不同的協議常量，例如 HTTP、HTTPS、DNS 等。通過使用 L7Protocol，我們可以在流量中準確地識別和標記不同的應用層協議。

2、L7ProtocolParser（第七層協議解析器）：其源碼位于 l7_protocol_log.rs 文件中。這個 trait 主要用于協議的判斷和解析，它能夠根據特定的規則和模式，從流量數據中解析出 L7ProtocolInfo（第七層協議信息）。L7ProtocolParser 的實現類可以根據具體的協議特征，進行解析和識別，從而獲得有關協議的詳細信息。

3、L7ProtocolInfo（第七層協議信息）：其源碼位于 l7_protocol_info.rs 文件中。L7ProtocolInfo 是由 L7ProtocolParser 解析出來的數據結構，它包含了有關協議的詳細信息，例如協議類型、協議版本、源IP地址、目標IP地址等。L7ProtocolInfo 在后續的會話聚合和分析中發揮著重要的作用。

4、L7ProtocolInfoInterface（第七層協議信息接口）：其源碼同樣位于 l7_protocol_info.rs 文件中。所有的 L7ProtocolInfo 都需要實現這個接口，以提供一致的方法和屬性。通過實現 L7ProtocolInfoInterface，我們可以對協議信息進行統一的操作和處理，以滿足后續的需求。

5、L7ProtocolSendLog（發送到深度流分析服務器的第七層協議日志）：其源碼位于 pb_adapter.rs 文件中。L7ProtocolSendLog 是一個結構體，用于將解析后的第七層協議信息統一發送到深度流分析服務器。通過使用 L7ProtocolSendLog，我們可以將協議信息傳遞給服務器進行進一步的處理和分析。

通過以上組件和接口的協同工作，deepflow-agent 能夠準確地識別和解析不同的應用層協議，并將相關的協議信息發送到 deepflow-server器，為后續的流量分析和應用提供有價值的數據基礎。這些組件和接口的設計和實現，為 deepflow-agent 的功能和性能提供了堅實的基礎。

綜上所述，針對 Deepflow 協議解析而言，其整體的流程可概括為如下：

了解完 Deepflow 的協議解析后，我們回到 Wasm plugin，Wasm plugin 整體的執行流程如下所示：

針對上述執行流程結構，其中序列化/反序列化的結構主要涉及如下6個，具體可參考如下：

• VmCtxBase

在目前所有的 Export 函數調用的時候，host 會將 VmCtxBase 序列化到線性內存，序列化的格式參考：vm.rs#L199

同樣地，instance 也會反序列化，具體代碼可以參考：mod.rs#L152

• L7ProtocolInfo

在 Export 函數 parse_payload 最后，instance 會序列化 L7ProtocolInfo 到線性內存，

host 也會反序列化。

• VmHttpReqCtx

在 http 請求解析完成返回之前，會調用 Export 函數 on_http_req，host 會序列化 VmCtxBase 和 VmHttpReqCtx 到 instance 的線性內存

VmHttpReqCtx 的序列化的代碼和格式可以參考：vm.rs#L328instance 反序列化的代碼參考：serde.go#L173

• VmHttpRespCtx

在 http 響應解析完成返回之前，會調用 Export 函數 on_http_resp，host 會序列化 VmCtxBase 和 VmHttpRespCtx 到 instance 的線性內存

VmHttpRespCtx 的序列化的格式參考：vm.rs#L395

instance 反序列化的代碼參考：serde.go#L232

• Trace，[]KeyVal

在 Export 函數 on_http_req/on_http_resp 返回之前，instance 會將 Trace 和 []KeyVal 序列化到線性內存

序列化的代碼和格式可以參考：serde.go#L515

反序列化的代碼和格式可參考：abi_import.rs#L376

三、如何基于 Golang SDK 開發 DeepFlow Wasm Plugin ？

通常而言，Wasm Plugin 可支持多種語言進行開發。這里，我們以 Golang 為例，簡要解析如何使用 Golang 快速開發 Wasm Plugin。需要注意的是，本項目中 Golang SDK 編譯需要用到 TinyGo 工具鏈。

為什么需要 TinyGo ？

TinyGo 是一個專門為嵌入式設備和 WebAssembly（Wasm）環境設計的 Go 編程語言工具鏈。它是 Go 語言的一個輕量級替代品，旨在在資源受限的環境中運行和編譯 Go 代碼。

TinyGo 的目標是提供一個高效的 Go 編譯器和運行時環境，以便在小型設備和嵌入式系統上運行 Go 程序。相較于標準的 Go 編譯器，TinyGo 優化了編譯輸出的大小和性能，以適應資源受限的環境。這使得開發者可以使用 Go 語言的簡潔性和強大的工具生態系統來構建嵌入式系統、物聯網設備和其他資源有限的應用。

除了針對嵌入式設備，TinyGo 還支持 WebAssembly，使得開發者可以使用 Go 語言編寫的代碼在 Web 瀏覽器環境中運行。這使得開發者可以在瀏覽器中直接運行高性能的 Go 代碼，從而擴展了 Go 語言的應用范圍。

 針對 Wasm Plugin 的開發實現，我們可以參考：https://deepflow.io/docs/zh/integration/process/wasm-plugin/，其關鍵步驟主要涉及如下，具體：

1、 獲取 Golang SDK 進行項目創建

go mod init {ProjectName} 
go get github.com/deepflowio/deepflow-wasm-go-sdk

需要注意的是：確保在執行這些命令之前，已經正確設置了 Go 開發環境，并且可以訪問 GitHub。

2、 實現協議解析邏輯

package main


import (
        "github.com/deepflowio/deepflow-wasm-go-sdk/sdk"
)


func main(){
    sdk.Warn("plugin loaded")
    sdk.SetParser(SomeParser{})
}


type SomeParser struct {
}


func (p SomeParser) HookIn() []sdk.HookBitmap {
        return []sdk.HookBitmap{
                // 一般只需要 hook 協議解析
                sdk.HOOK_POINT_PAYLOAD_PARSE,
        }
}


func (p SomeParser) OnHttpReq(ctx *sdk.HttpReqCtx) sdk.Action {
        return sdk.ActionNext()
}


func (p SomeParser) OnHttpResp(ctx *sdk.HttpRespCtx) sdk.Action {
        return sdk.ActionNext()
}


func (p SomeParser) OnCheckPayload(ctx *sdk.ParseCtx) (uint8, string) {
    // 這里是協議判斷的邏輯， 返回 0 表示失敗
    // return 0, ""
    return 1, "some protocol"
}


func (p SomeParser) OnParsePayload(ctx *sdk.ParseCtx) sdk.Action {
    // 這里是解析協議的邏輯
    if ctx.L4 != sdk.TCP|| ctx.L7 != 1{
                return sdk.ActionNext()
    }
    return sdk.ActionNext()
}

注：以上是一個簡單的插件示例，展示了如何使用 "deepflowio/deepflow-wasm-go-sdk" 庫來開發自定義的插件，并實現不同的回調函數來處理網絡數據包。在實際的業務場景中，我們可以根據自己的需求進一步擴展和修改這些回調函數的實現邏輯，以滿足自身的場景訴求。  

3、編譯為 Wasm Plugin

# 建議 go 版本不低于1.21，tinygo 版本不低于 0.29
tinygo  build -o wasm.wasm  -target wasi -gc=precise -panic=trap -scheduler=none -no-debug *.go

執行命令后，將會生成名為"wasm.wasm"的WebAssembly文件，可以在支持 WebAssembly 的環境中加載和運行。

Wasm Plugin 開發完后，我們需要將其部署至 DeepFlow 中，針對 Wasm Plugin 的部署主要涉及如下步驟：

1、將編譯好的插件上傳至 Deepflow-Server

deepflow-ctl plugin create  --type wasm --image wasm.wasm --name wasm-devops

執行命令后，Deepflow-ctl 將會創建一個名為"wasm-devops"的 WebAssembly 插件，并將指定的 WebAssembly 文件作為插件的執行代碼。我們可以根據需要進一步配置和管理這個插件。  

2、Agent 端加載 Wasm Plugin

static_config:
  ebpf:
    # 對于 deepflow-agent 原生不支持的協議， eBPF 數據需要添加端口白名單才能上報
    kprobe-whitelist:
      port-list: 9999


  # 如果配置了 l7-protocol-enabled，別忘了放行 Custom 類型的協議
  l7-protocol-enabled:
  - Custom
  # other protocol


  wasm-plugins:
    - wasm-devops // 對應 deepflow-ctl 上傳插件的名稱

注：目前修改此配置后 deepflow-agent 會自動重啟。

3、驗證是否成功加載

kubectl -n deepflow logs -f deepflow-agent-xxxxx | grep -i plugin

至此，一個 Wasm Plugin 已成功開發完成，并應用至我們的業務場景中。

四、案例分享 - 解析 JSON 中的錯誤信息

在此案例中，被監控 HTTP API 的響應消息為 JSON 格式，當 API 出錯時 HTTP 協議的狀態碼可能仍然是 200，確切的錯誤信息通過 JSON 中的 OPT_STATUS 等字段返回：

{  "OPT_STATUS": "AUTH_HEADER_ERROR",   // 不等于 SUCCESS 時表示調用失敗  
   "DESCRIPTION": "請傳遞正確的驗證頭信息", // 詳細錯誤信息  
   ... // 其他返回字段
}

查閱 API 文檔后我們得知，OPT_STATUS 的值不等于 SUCCESS 時表示 API 調用失敗。在常規的 DeepFlow 解析流程中，會按照如下方式構造 HTTP 調用日志的各個字段：

• response_code：賦值為 HTTP 響應頭中的狀態碼，例如 200、404、500 等
• response_status：狀態碼小于 400 時認為正常，4XX 認為是客戶端異常，5XX 認為是服務端異常
• response_exception：賦值為 HTTP 異常狀態碼對應的英文解釋，例如 404 時此字段賦值為 Not Found
• response_result：當 HTTP 狀態碼為異常時賦值為整個 HTTP Payload

當我們安裝了 Wasm 插件后，我們可以在上述解析的基礎上，將失敗 API 的調用日志中的如下字段進行覆寫，以實現正確體現業務錯誤的效果：

• response_code：當 JSON 中 OPT_STATUS != SUCCESS、且 HTTP 狀態碼小于 400 時，此值覆寫為 500
• response_status：按照新的 response_code 重新賦值，例如 500 時賦值為服務端異常
• response_exception：當 JSON 中的 OPT_STATUS != SUCCESS時覆寫為 DESCRIPTION 字段的值
• response_result：當 response_code 大于等于 400 時賦值為整個 JSON Payload
  

我們將 Wasm 插件代碼放到了這個 GitHub 倉庫中。上述 API 行為描述的實際上是 DeepFlow 企業版中的 statistics 服務，下面演示將此 Wasm 插件注入到 DeepFlow Agent 以后，對 DeepFlow 企業版服務的自我觀測效果。首先我們在命令行中觸發一次 statistics 服務的 API 調用：

# 請求
curl https://cloud.deepflow.io/api/statistics/v1/stats/querier/DBDescription/ShowDatabases


# HTTP 響應頭
HTTP/2 401
date: Tue, 22 Aug 2023 01:44:29 GMT
content-type: application/json
content-length: 152


# HTTP 響應體
{
  "DATA": false,
  "DESCRIPTION": "請傳遞正確的驗證頭信息",
  "ERR": null,
  "LEVEL": 0,
  "OPT_STATUS": "AUTH_HEADER_ERROR"
}

上述 API 響應中，HTTP 的狀態碼為 401，OPT_STATUS=AUTH_HEADER_ERROR。我們能在 DeepFlow 頁面正確的看到客戶端異常指標（本例中插件注入在 cloud.deepflow K8s 集群的 deepflow-agent 中）：

在 DeepFlow 調用日志頁面，可以看到客戶端異常的調用日志的詳情信息，整個 JSON body 放在了 response_result里面：

對該調用發起追蹤，能看到是因為fauths返回的 401 異常：

下面是詳細的調用鏈。第一步發起 DNS 請求：

第二步調用后端服務驗證 License：

第三步發起 DNS 請求 fauths 服務的地址：

第四步調用 fauth 的 /auth API 驗證權限，中間需要訪問 Redis 獲取用戶信息：

上述案例展示了 DeepFlow 中Wasm Plugin 機制的強大能力，使得在實際業務場景中能夠輕松解決問題的跟蹤、定位和分析。

通過使用自定義的 Wasm Plugin，我們可以針對特定需求開發定制化的功能，如解析 JSON 中的錯誤信息。這種能力使得我們能夠在流量處理過程中靈活地捕捉和處理問題，無論是在調試階段還是在生產環境中。

使用 DeepFlow 的 Wasm Plugin 機制，我們可以輕松地擴展原生協議的解析能力，提取更多的業務信息。特別是對于私有協議，如 Protobuf 和 Thrift，我們可以通過自定義插件來解析這些依賴 Schema 的 Payload 內容，從中提取關鍵的業務字段。這為我們深入了解協議數據提供了便利，使得我們能夠更好地理解和利用數據。