使用 Java 介紹 Lightrun
一、簡介
在本文中,我們將探索 Lightrun——一個開發人員可觀察性平台——通過將其引入應用程序並展示我們可以使用它實現的目標。
2.什麼是Lightrun?
Lightrun 是一個可觀察性平台,它允許我們檢測我們的 Java(也支持其他語言)應用程序,然後直接從 IntelliJ、Visual Studio Code 和許多其他日誌記錄平台和 APM 中查看檢測。它旨在能夠無縫地將檢測添加到在任何環境中運行的應用程序並從任何地方訪問它們,使我們能夠快速診斷從本地工作站到生產實例的任何地方的問題。
Lightrun 與兩個集成在一起的不同組件一起工作:
- Lightrun 代理作為應用程序的一部分運行,並根據要求檢測遙測。在 Java 應用程序中,它作為 Java 代理工作。我們將把這個代理作為我們想要使用 Lightrun 的每個應用程序的一部分來運行。
- Lightrun 插件作為我們開發環境的一部分運行,允許我們與代理進行通信。這是我們查看正在運行的內容、向應用程序添加新工具並接收該工具的結果的方法。
一旦所有這些都設置好了,我們就可以管理三種不同類型的儀器:
- 日誌——這些是在任何時候將任意日誌語句添加到正在運行的應用程序中,註銷任何可用值(包括複雜表達式)的能力。這些日誌可以發送到標準輸出,也可以發送回我們開發環境中的 Lightrun 插件,或者同時發送兩者。此外,它們可以有條件地調用——例如,基於代碼中預定義的特定用戶或會話 ID。
- 快照——這些允許我們在任何時候捕獲應用程序的實時快照。這將記錄快照觸發的確切時間和地點、所有變量的值以及到此為止的完整調用堆棧的詳細信息。這些也可以有條件地調用,就像日誌一樣。
- 指標——這些允許我們記錄類似於 Micrometer 生成的指標,允許我們計算一行代碼的執行次數,記錄代碼塊的時間,或者我們可能想要的任何其他數值計算。
所有這些事情都可以在我們的代碼中輕鬆完成。 Lightrun 在這里為我們提供的是能夠在已經運行的應用程序中執行這些操作,而無需更改或重新部署應用程序。這意味著我們可以在零停機時間的情況下在生產中獲得有針對性的儀器。
此外,所有這些日誌都是短暫的。它們不會保留在源代碼或正在運行的應用程序中,可以根據需要添加和刪除。
3. 示例應用
對於本文,我們有一個已經構建並可以使用的應用程序。此應用程序旨在跟踪分配給人員的任務,並允許用戶查詢此數據。此代碼可在 GitHub 上找到,需要 Java 17+ 和 Maven 3.6 才能正確構建。
該應用程序被構建為三個不同的服務——一個用於管理用戶,另一個用於管理任務,第三個用於協調這兩個服務。然後, tasks-service
和users-services
擁有自己的數據庫,並且兩者之間有一個 JMS 隊列——允許users-service
指示用戶被刪除,以便tasks-service
可以整理。
為了方便起見,這些數據庫和 JMS 隊列都嵌入在應用程序中。然而,實際上,這自然會使用真實的基礎設施。
3.1。任務服務
在本文中,我們只對tasks-service
感興趣。但是,在以後的文章中,我們將探討所有這三個以及它們如何相互作用。
此服務是在 Java 17 上使用 Maven 構建的 Spring Boot 應用程序。運行時,它具有以下 HTTP 端點:
- GET / - 允許客戶端搜索任務,按創建它的用戶和它的狀態進行過濾。
- POST / – 允許客戶端創建新任務。
- GET /{id} – 允許客戶端通過 ID 獲取單個任務。
- PATCH /{id} – 允許客戶端更新任務,更改狀態和分配給的用戶。
- DELETE /{id} – 允許客戶端刪除任務。
我們還有一個 JMS 監聽器,它可以指示用戶何時從我們的users-service
中刪除。在這種情況下,我們會自動刪除該用戶創建的所有任務,並取消分配給該用戶的所有任務。
我們的應用程序中還有一些錯誤,我們將能夠在 Lightrun 的幫助下進行診斷。
4. 設置 Lightrun
在開始之前,我們需要一個 Lightrun 帳戶並在本地進行設置。這可以通過訪問https://app.lightrun.com/並按照說明完成。
註冊後,我們需要選擇開發環境和編程語言。對於本文,我們將使用 IntelliJ 和 Java,因此我們將選擇它們並繼續:
然後,我們會獲得有關如何將 Lightrun 插件安裝到我們的環境中的說明,因此我們可以按照這些說明進行操作。
我們還需要確保從我們的開發環境登錄到我們的新帳戶,之後我們將可以從編輯器中訪問我們的 Lightrun 代理 - 還沒有:
最後,我們將獲得有關如何下載我們將用於檢測應用程序的 Java 代理的說明。這些說明是特定於平台的,因此我們需要確保遵循適合我們確切設置的說明。
完成此操作後,我們可以在安裝代理的情況下啟動我們的應用程序。確保構建了tasks-service
,然後我們可以運行它:
$ java -jar -agentpath:../agent/lightrun_agent.so target/tasks-service-0.0.1-SNAPSHOT.jar
此時,Web 瀏覽器中的 Onboarding 屏幕將允許我們繼續前進,我們開發環境中的 UI 將自動更新以顯示我們的應用程序正在運行:
請注意,這些都連接到我們的 Lightrun 帳戶,因此無論應用程序在哪裡運行,我們都可以看到它們。這意味著我們可以在本地機器、Docker 容器或任何其他支持我們運行時的環境中運行的應用程序上使用完全相同的工具,無論它在世界的哪個地方。
5. 捕捉快照
Lightrun 最強大的功能之一是能夠將快照添加到當前正在運行的應用程序中。然後,這些將允許我們在應用程序中的給定點捕獲確切的執行狀態。然後,這可以為我們的代碼中發生的確切情況提供寶貴的見解。它們可以被認為是“虛擬斷點”,只是它們不會中斷程序的流程。相反,它們會捕獲您可以從斷點看到的所有信息,供我們稍後查看。
快照——以及日誌和指標——是從我們的開發環境中添加的。我們通常會通過右鍵單擊要添加儀器的行然後選擇“Lightrun”選項來執行此操作。
然後我們可以通過從後續菜單中選擇它來添加我們的儀器:
這將打開一個面板,允許我們添加快照:
在這裡,我們需要選擇要檢測的代理,並可能指定有關其工作方式的其他詳細信息。
當我們對一切都滿意時,我們然後點擊創建按鈕。然後,這將在我們的側邊欄中添加一個新的 Snapshot 條目,我們將在代碼行上看到一個藍色的相機圖標。
這表明該行將在執行時捕獲快照:
請注意,如果出現問題,相機將變為紅色。通常,這意味著運行代碼與源代碼不對應,儘管可能存在其他原因並且也需要在此處進行探討。
6. 診斷錯誤——搜索任務
不幸的是tasks-service,
有一個錯誤,即執行過濾的任務搜索永遠不會返回任何內容。如果我們執行未過濾的搜索,那麼這將正確返回所有任務,但是一旦添加了過濾器——無論是createdBy
、 status,
還是兩者——然後我們突然就沒有結果了。
例如,如果我們調用http://localhost:8082?status=PENDING那麼我們應該得到一些結果,但是我們總是得到一個空數組。
我們的應用程序的架構使得我們有一個TasksController
來處理傳入的 HTTP 請求。然後調用TasksService
來完成真正的工作,這在TasksRepository
方面起作用。
這個存儲庫是一個 Spring Data 接口,這意味著我們沒有可以直接檢測的代碼。相反,我們將在TasksService
中添加一個快照。特別是,我們將把它添加到search()
方法的第一行。這將讓我們看到調用方法時存在的初始條件,而不管我們最終在方法內部通過哪個代碼路徑:
完成此操作後,我們將調用我們的端點。同樣,我們將得到與空數組相同的結果。
然而,這一次我們將在我們的開發環境中捕獲一個快照——我們可以在 Snapshots 選項卡上看到它:
這向我們顯示了捕獲快照的堆棧跟踪以及捕獲快照時所有可見變量的狀態。讓我們關注這裡的變量。其中兩個是傳遞給方法的參數,第三個是this
。這些參數可能是最有趣的,所以我們將看看這些參數。
馬上,我們就能看出問題所在。在createdBy
參數中,我們已經獲得了值“PENDING”——這是我們正在搜索的狀態!
仔細查看代碼,我們發現不幸的是,我們在TasksController
和TasksService.
這是一個簡單的解決方法,如果我們要做到這一點——通過交換TasksService
中的參數或從TasksController
傳入的值——然後突然間,我們的搜索將開始正常工作。
七、總結
在這裡,我們快速介紹了 Lightrun 可觀察性平台、如何開始使用它,以及它可以給我們帶來的一些好處。我們將在接下來的文章中更深入地探討這些。
為什麼不在您的下一個應用程序中使用它,以便對其運行方式更有信心和洞察力。