Monitoring .NET Framework

支援的作業系統

監視 .NET Framework 僅支援 Windows ®。 支援的 Windows 作業系統與 Windows 代理程式需求相同。

支援的版本

Instana 支援監視在 .NET Framework 4.5.1 以及更新版本上執行的應用程式。

支援追蹤的程式庫及架構

若要進行記載，您可以設定環境變數 INSTANA_LOG_LEVEL_CAPTURE ，以防止為層次低於所設定的日誌建立跨距。 此值可以是 WARN、 ERROR或 OFF (以停用此選項)。 預設值是 warn。

性能簽章

對於每個感應器，會持續根據送入的度量值來評估性能簽章的策劃知識庫。 根據評估，會根據使用者影響來引發問題或發生事件。

內建事件 會根據實體上的性能簽章失敗來觸發問題或突發事件，而 自訂事件 會根據任何實體的個別度量值臨界值來觸發問題或突發事件。

如需 .NET 感應器內建事件的相關資訊，請參閱 內建事件參照。

追蹤如何運作

當您透過變更配置檔來啟用追蹤時，會針對使用受支援技術的所有應用程式收集追蹤資料。 .NET Framework-追蹤使用與所有其他追蹤套件相同的架構。 多語言應用程式中的分散式追蹤會自動收集，並顯示在 Instana 使用者介面中。

當啟用追蹤的應用程式啟動時，您可能會發現與不追蹤的啟動相比，啟動時間會增加。 增加的原因是附加側寫程式，檢查所參照組件中包含的類別，然後即時編譯部分方法的程式碼以進行檢測。 在套用檢測之後，與 Instana 提供的任何其他追蹤套件一樣，對應用程式執行時期效能的影響非常低。

追蹤元件設定是代理程式的大部分自動功能。 不過，如果要設定追蹤，請完成下列各節所說明的手動步驟。

設定 Tracing for .NET Framework

當 Instana 代理程式在 Windows 機器上啟動時， Instana 代理程式會安裝 .NET Framework 的追蹤延伸。 延伸由數個包含實際追蹤元件的檔案組成。 因為 Instana 使用 .NET 架構中定義的 Profiling API ，所以它涉及 COM-Libraries 及受管理組件。 在啟用追蹤的情況下，會登錄檔案，讓所有應用程式都可以使用它們來進行追蹤。 依預設會啟用感應器及追蹤延伸。

當代理程式啟動時， InstanaPCP 會記載追蹤啟用程序的相關資訊，如下列範例所示 (縮短日誌行)。 顯示已啟用 .NET Framework 追蹤的 configuration.yaml 。

INFO  | com.instana.agent - 1.1.326 | Writing location for instrumentation-advices to registry
INFO  | com.instana.agent - 1.1.326 | Setting up tracing-environment
INFO  | com.instana.agent - 1.1.326 | Registering native profiler for .NET
INFO  | com.instana.agent - 1.1.326 | Agent UUID received:ac:bc:32:ff:fe:90:7d:bb
INFO  | com.instana.agent - 1.1.326 | Registering System.Collections.Immutable.dll in GAC
INFO  | com.instana.agent - 1.1.326 | .NET Tracing is enabled
INFO  | com.instana.agent - 1.1.326 | Registering instrumentation-DLLs in GAC
INFO  | com.instana.agent - 1.1.326 | Registering Instana.ManagedTracing.dll in GAC
INFO  | com.instana.agent - 1.1.326 | Setting environment-variables for .NET tracing
INFO  | com.instana.agent - 1.1.326 | Registry-Key for WAS-Environment does not exist, will create now
INFO  | com.instana.agent - 1.1.326 | Setting environment for WAS
WARN  | com.instana.agent - 1.1.326 | You should consider restarting the service WAS in order to make it use the new profiler. Already running application will not use it until restarted.
INFO  | com.instana.agent - 1.1.326 | Registry-Key for W3SVC-Environment does not exist, will create now
INFO  | com.instana.agent - 1.1.326 | Setting environment for W3SVC
WARN  | com.instana.agent - 1.1.326 | You should consider restarting the service W3SVC in order to make it use the new profiler. Already running application will not use it until restarted.
INFO  | com.instana.agent - 1.1.326 | Setting memoryUsageExcessThreshold set to configured value of 100000000
INFO  | com.instana.agent - 1.1.326 | Self-Monitoring for Windows-Extensions has been started successfully
INFO  | com.instana.agent - 1.1.326 | Setting memoryUsageWarningThreshold set to configured value of 80000000
INFO  | com.instana.agent - 1.1.326 | Starting tracing-session
INFO  | com.instana.agent - 1.1.326 | Windows-Extension REST-Endpoint has been setup successfully at http://localhost:42657
INFO  | com.instana.agent - 1.1.326 | Registering Instana.ManagedTracing.Modules.dll in GAC
INFO  | com.instana.agent - 1.1.326 | Instana ETW-Reader setup and listening

延伸會登錄 COM-DLL (側寫程式) ，其中有 3 個受管理組件，其中包含實際的檢測碼，或檢測工作所需的元件 (Instana.ManagedTracing.dll、 Instana.ManagedTracing.Base.dll、 System.Collections.Immutable.dll)。 登錄元件之後，延伸會更新登錄，以便在下次啟動 W3SVC 或 WebSphere Application Server 的任何實例時附加側寫程式。 日誌中會新增關於重新啟動已在執行中的應用程式的警告。 Instana 不會自動重新啟動這些服務，因為我們不想岔斷您的服務。

對 IIS 管理的應用程式啟用追蹤

如果您執行 IIS 管理的應用程式，則不需要再執行任何設定; InstanaPCP 會處理所有項目。 在 Instana 代理程式和 InstanaPCP 應用程式都在執行之後，請執行 IIS 重設。 您可以使用 Task Manager for Windows 來檢查 InstanaPCP 是否在執行中。

附註: 如果您未執行 IIS 重設，則 IIS 工作者不知道它們需要進行檢測，且您無法追蹤 IIS 管理的應用程式。

啟用追蹤非 IIS 管理的應用程式

「Instana 代理程式」不會對每一個 .NET 型應用程式啟用追蹤，因為這可能會產生不想要的元件行為。 例如，追蹤不在監視需求範圍內的 Windows 系統應用程式。

SET COR_ENABLE_PROFILING=1
SET COR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}

COR_ENABLE_PROFILING=1
COR_PROFILER={FA8F1DFF-0B62-4F84-887F-ECAC69A65DD3}

自訂追蹤

Instana 的 。NET 追蹤 SDK 會在 Instana 的自動檢測不適用的情況下啟用自訂追蹤 (亦即，您使用 Instana 不會自動追蹤的元件)。

停用 .NET Framework 追蹤

當您想要停止追蹤 .NET Framework 應用程式時，請將配置檔變更回其起始狀態，或將對應的旗標設為 "false"。

configuration.yaml ，已停用 .NET Framework-追蹤

# CLR Tracing
    com.instana.plugin.clr:
      tracing:
        enabled: false

將配置變更回其起始狀態之後，請重新啟動代理程式，讓變更生效。

在代理程式中停用追蹤不會從已啟動啟用追蹤的處理程序 (亦即，工作者處理程序) 移除或分離側寫程式。 若要確定側寫程式未載入至應用程式，請重新啟動主機處理程序。

未定義環境變數

監視問題類型: clr_env_var_not_defined

未正確設定啟動 Instana .NET Framework 追蹤所需的至少一個環境變數。

• 對於在 IIS 上管理的應用程式， iisreset 可能尚未發出，或者在代理程式可以登錄追蹤所需的程式庫之前已發出。 解決方案是從提升的命令提示字元執行 iisreset 。

  如果這樣做沒有幫助，請考慮重新啟動機器。 視您執行的 Windows 版本，以及在 Instana 代理程式啟動時正在安裝或解除安裝應用程式而定，可能需要重新啟動。

• 對於不在 IIS 上管理的應用程式，請參閱 啟用追蹤非 IIS 管理的應用程式 區段，以取得環境變數清單，以及您需要設定以追蹤 .NET Framework 應用程式的值。

環境變數具有無效值

監視問題類型: clr_env_var_invalid_value

至少有一個啟動 Instana .NET Framework 追蹤所需的環境變數沒有正確的值。 (視遺漏 哪些 環境變數而定，您可能仍會在 .NET Framework 應用程式的 Instana 儀表板中看到度量值，但絕對不會看到追蹤資料。) 如需環境變數及您需要設定以使用 Instana 來追蹤 .NET Framework 應用程式的值清單，請參閱 啟用追蹤非 IIS 管理的應用程式 一節。

此外，環境變數可能具有錯誤值，因為存在另一個 APM 工具。 (若要連接 .NET 執行時期，各種 APM 工具會使用類似機制。) 此狀況記錄在 Instana 使用者介面的訊息中。

在 Instana 可以追蹤 .NET Framework 應用程式之前，請關閉其他 APM 代理程式，至少針對 .NET Framework 監視。 如需如何關閉其他 APM 代理程式的相關資訊，請參閱其他 APM 工具的說明文件。

InstanaPCP 不在執行中

監視問題類型: clr_instana_pcp_not_running

您可能會在代理程式日誌中找到警告訊息，指出 InstanaPCP does not seem to be running。 當代理程式嘗試與 InstanaPCP 互動但失敗時，會觸發此訊息。 通常，代理程式會在引導程序早期啟動 InstanaPCP ，然後可以與它進行通訊。 在下列情況下， InstanaPCP 可能無法啟動:

• 代理程式未以足夠的專用權執行 (不是以「本端系統」或「管理者」身分執行)。
• 不支援主機上的 .NET Framework 版本。 僅支援 .NET Framework 4.5.1 以及更新版本。
• 由於記憶體過度耗用， InstanaPCP 已自行重新啟動。

如果您看到此訊息反覆出現，請完成下列檢查:

1. 請確保代理程式以具有本端管理專用權的使用者身分執行。 如果沒有，請使用不同的使用者帳戶來執行代理程式，或授與使用者本端管理專用權。 當您從安裝套件安裝 Instana 代理程式時，服務通常會以「本端系統」執行，這會提供服務足夠的專用權。

2. 請檢查您機器上安裝的 .NET Framework 版本。 Windows 安裝程式套件會自動安裝 InstanaPCP 所需的 .NET Framework 最低版本。 不過，如果您從 ZIP 保存檔安裝主機代理程式，則可能需要自行安裝架構。 如果您不確定是否有正確的版本，請嘗試從指令行手動執行 InstanaPCP ，方法是在 <agent-dir>\system\com\instana\agent-windows-extensions\<latest>\agent-windows-extensions-<latest> 目錄中找到它。 如果您未安裝正確版本的 .NET Framework ，則會顯示相關聯的提示。

3. 檢查您是否在日誌中看到指向過度使用的訊息，如下所示:

   InstanaPCP.exe Private-Bytes is above warning-treshhold for XXX times now
   
   Killing InstanaPCP.exe for excessive memory-usage. Possible memory-leak in native Windows-Libraries.
   

   這些訊息是由下列兩個問題之一所造成:

   1. 執行 InstanaPCP 的 Windows 機器具有舊版 IIS7 ，且具有特定的記憶體洩漏。 可以透過安裝 Microsoft 更新來修補此洩漏。 此問題可能在 Windows 2008 機器上發生。 在安裝此 Microsoft 更新之前，請聯絡 Instana 支援中心，以確定您的機器上發生記憶體洩漏問題。 然後，支援團隊可以提供您更新 Microsoft 套件的鏈結。

   2. 許多 .NET 應用程式正在伺服器上執行，而那些應用程式會產生許多追蹤資料。 在此情況下，請將變更套用至代理程式 configuration.yaml 檔案中的下列設定，以增加 InstanaPCP 的記憶體限制:

      com.instana.plugin.clr:
        pcp_warn_limit: <MB-treshold before warning>
        pcp_stop_limit: <MB-treshold  to stop / restart the process>
      

InstanaPCP 未連接

監視問題類型: clr_instana_pcp_not_connected

主機代理程式無法連接至 InstanaPCP 處理程序，這會阻止擷取及處理 .NET 處理程序的追蹤資料及執行時期度量值。

這通常是暫時性失敗，會在 InstanaPCP 完成起始設定之後快速自行解決。 如果沒有，請聯絡 Instana 支援中心。