Monitoring Haskell

Instana 對 Haskell 應用程式監視及追蹤的支援已深入記載在 Instana Haskell 追蹤 SDK 的 Github 頁面上。其 API 文件可在 Hackage上取得。

Haskell 追蹤 SDK 是什麼，不是什麼
安裝
用量

Haskell 追蹤 SDK 是什麼，不是什麼

「Instana Haskell 追蹤 SDK」不支援自動檢測/追蹤，因為我們在大部分其他語言中都支援它。相反地， SDK 可讓您手動建立文字段，就像 Instana Trace SDK for Java 一樣。除了提供方便的 API 來建立跨距，「Haskell 追蹤 SDK」也會負責建立與 Instana 代理程式的連線，並以有效率的方式將跨距傳送至代理程式，這不會妨礙正式作業程式碼的效能。最後 (但並非最不重要) ，它會收集執行時期度量值，並將它們報告給 Instana。

安裝

若要在應用程式中使用 Instana Haskell 追蹤 SDK ，請將 instana-haskell-trace-sdk 新增至相依關係 (例如，新增至纜線檔的 build-depends 區段)。如果您是使用堆疊，則可能需要將 SDK (具有您要使用的版本號碼) 新增至 stack.yaml 檔案中的 extra-deps 區段:

extra-deps:
- instana-haskell-trace-sdk-0.7.0.0

視您使用的堆疊解析器而定，您可能還需要將 aeson-extra 新增至 extra-deps:

- aeson-extra-0.4.1.3@sha256:8ad8e4d28e46280ea98af2e94dcaaf524c396c9d91b1eba867961efc6e7f923f,2997

使用情形

範例應用程式: 查看 Monad Shop 以實際查看 Instana Haskell 追蹤 SDK。

起始設定

在使用 SDK 之前，您需要起始設定它一次，通常是在應用程式啟動期間。

import qualified Instana.SDK.SDK as InstanaSDK

main :: IO ()
main = do
  -- ... initialize things ...

  -- initialize Instana
  instana <- InstanaSDK.initInstana

  -- ... initialize more things

InstanaSDK.initInstana 所傳回的值 instana :: Instana.SDK.InstanaContext 是所有進一步呼叫的必要項目，亦即，用於建立將傳送至代理程式的跨距。一旦 SDK 收到 initInstana 呼叫，它就會嘗試連接至代理程式 (非同步，在個別執行緒中)。

SDK 可以透過環境變數或直接在程式碼中配置，方法是將配置參數傳遞至起始設定函數或兩者。

如果您想要以程式設計方式傳遞配置參數，請使用 initConfiguredInstana 而非 initInstana:

import qualified Instana.SDK.SDK as InstanaSDK

main :: IO ()
main = do

  -- Example snippet for using the Instana SDK and providing a configuration
  -- (agent host, port, ...) directly in code. You only need to specify the
  -- configuration values you are interested in and can omit everything else
  -- (see https://www.yesodweb.com/book/settings-types).
  let
    config =
      InstanaSDK.defaultConfig
        { InstanaSDK.agentHost = Just "127.0.0.1"
        , InstanaSDK.agentPort = Just 42699
        , InstanaSDK.serviceName = Just "A Great Hakell Service"
        , InstanaSDK.forceTransmissionAfter = Just 1000
        , InstanaSDK.forceTransmissionStartingAt = Just 500
        , InstanaSDK.maxBufferedSpans = Just 1000
        }
  instana <- InstanaSDK.initConfiguredInstana config

對於在建立配置記錄時省略或設為 Nothing的配置參數， SDK 將回復為環境變數 (請參閱如下所示) ，然後為預設值。

起始設定函數也有方括弧樣式變式，稱為 withInstana 和 withConfiguredInstana:

import qualified Instana.SDK.SDK as InstanaSDK

main :: IO ()
main = do
  InstanaSDK.withInstana runApp

runApp :: InstanaContext -> IO ()
runApp instana = do
  -- do your thing here :-)

或者，具有方括弧樣式及配置記錄:

import qualified Instana.SDK.SDK as InstanaSDK

main :: IO ()
main = do
  let
    config =
      InstanaSDK.defaultConfig
        { InstanaSDK.agentHost = Just "127.0.0.1"
        , InstanaSDK.agentPort = Just 42699
        , InstanaSDK.serviceName = Just "A Great Hakell Service"
        , InstanaSDK.forceTransmissionAfter = Just 1000
        , InstanaSDK.forceTransmissionStartingAt = Just 500
        , InstanaSDK.maxBufferedSpans = Just 1000
        }

  InstanaSDK.withConfiguredInstana config runApp

runApp :: InstanaContext -> IO ()
runApp instana = do
  -- do your thing here :-)

建立跨距

自動追蹤 HTTP 項目

您可以讓 SDK 自動為 WAI 應用程式中所有送入的 HTTP 要求建立項目跨距，方法是將它用作 WAI 中介軟體外掛程式。外掛程式會自動將 Instana 追蹤標頭及 W3C 追蹤環境定義標頭納入考量。請注意，仍需要透過 withHttpExit 或 startHttpExit/completeExit 函數手動建立結束跨距 (請參閱如下所示)。

中介軟體外掛程式也會將其他 HTTP 回應標頭 (Server-Timing) 新增至 HTTP 回應。此標頭會啟用網站監視後端相關性。

import qualified Instana.Wai.Middleware.Entry as InstanaWaiMiddleware

main = do
  Warp.run 3000 $ InstanaWaiMiddleware.traceHttpEntries instana $ app

方括弧樣式 (高階 API)

以 with 開頭的所有函數接受 (以及其他參數) IO 動作。 SDK 將在之前啟動跨距，然後執行給定的 IO 動作，並在之後完成跨距。建議使用此樣式，而不是需要您自行啟動及完成的低階 API。

withRootEntry: 建立作為追蹤根目錄的項目跨距 (沒有母項跨距)。
withEntry: 建立具有母項跨距的項目跨距。
withHttpEntry: 此便利函數會檢查 Instana 追蹤標頭或 W3C 追蹤環境定義標頭的送入 HTTP 要求，並建立項目跨距。它會自動將正確的 meta 資料新增至跨距。請注意，使用 Instana WAI 中介軟體外掛程式時，您完全不需要處理送入的 HTTP 要求 (請參閱上方)。
withHttpEntry_: withHttpEntry 的變式，具有較一般的類型簽章，但特性較少。就像 withHttpEntry 一樣，它會自動繼續來自送入標頭 (Instana 標頭或 W3C 追蹤環境定義) 的追蹤，但不會擷取 HTTP 回應的狀態碼，或新增網站監視後端相關性 (Server-Timing) 的回應標頭。如果可能的話，建議使用 withHttpEntry 來取代此函數。或者，您也可以在 withHttpEntry_ 區塊內呼叫 postProcessHttpResponse ，以涵蓋上述兩個遺漏的特性。請注意，使用 Instana WAI 中介軟體外掛程式時，完全不需要處理送入的 HTTP 要求。
withExit: 建立結束跨距。這只能在 withRootEntry 或 withEntry 呼叫內呼叫，因為結束跨距需要進入跨距作為其母項。
withHttpExit: 為給定的 HTTP 用戶端要求建立結束跨距。它會自動將正確的 meta 資料新增至跨距，因此在追蹤送出的 HTTP 要求時，應該偏好使用 withExit 。它也會將 Instana 追蹤 HTTP 標頭及 W3C 追蹤環境定義 HTTP 標頭 HTTP 新增至要求，以向下游傳送追蹤環境定義。
postProcessHttpResponse: 處理 HTTP 項目的回應。當 HTTP 項目跨距仍在作用中時，需要呼叫此函數。它可以在 withHttpEntry_ 區塊內使用，或在 startHttpEntry 與 completeEntry之間使用。此函數會完成兩件事: 它會從回應中擷取 HTTP 狀態碼，並將它作為註釋新增至目前作用中的跨距。它也會將其他 HTTP 回應標頭 (Server-Timing) 新增至給定的 HTTP 回應，以啟用網站監視後端相關性。用戶端程式碼應該很少需要直接呼叫它。相反地，請使用 withHttpEntry來擷取送入的 HTTP 要求，它會自動執行這兩個動作。

低層次 API/Explicit 開始及完成

startRootEntry: 啟動作為追蹤開頭的項目跨距 (沒有母項跨距)。您需要在某個時間點呼叫 completeEntry 。
startEntry: 啟動項目跨距。您需要在某個時間點呼叫 completeEntry 。
startHttpEntry: 啟動送入 HTTP 要求的項目跨距。它會自動將正確的 meta 資料新增至跨距。使用 WAI 中介軟體外掛程式時，完全不需要處理送入的 HTTP 要求 (請參閱上述)。您需要在某個時間點呼叫 completeEntry 。
startExit: 啟動結束跨距。您需要在某個時間點呼叫 completeExit 。
startHttpExit: 啟動送出 HTTP 要求的結束跨距。它會自動將正確的 meta 資料新增至跨距，因此在追蹤送出的 HTTP 要求時，應該偏好使用 startExit 。它也會將 HTTP 標頭新增至要求，以向下游傳送追蹤環境定義。您需要在某個時間點呼叫 completeExit 。
completeEntry: 終結項目跨距。這會將跨距放入 SDK 的跨距緩衝區，以傳輸至 Instana 代理程式。
completeExit: 終結結束跨距。這會將跨距放入 SDK 的跨距緩衝區，以傳輸至 Instana 代理程式。

最佳作法

請確定您已閱讀 Instana 的自訂追蹤文件。本文件包含許多有用的資訊，可用來將 Instana 追蹤整合至您的程式碼; 此外，它還說明哪些 meta 資料可以新增至文字段 (透過 InstanaSDK.addTag 和 InstanaSDK.addTagAt)。

Instana 會區分所謂的已登錄跨距與 SDK 跨距。已登錄的跨距通常是由自動追蹤所建立，且在 Instana 的處理管線中，每一個已登錄的跨距都有特殊化處理。相反地， SDK 跨距是使用追蹤 SDK 所建立的跨距類型 (例如 Haskell 追蹤 SDK 或其他執行時期平台的其他類似 SDK)。透過 Instana 的處理管線，以更通用的方式處理 SDK 跨距。

請注意，幾乎所有使用此 SDK 建立的文字段都應該是 SDK 文字段。只有兩個例外，此 SDK 為其建立已登錄的跨距:

HTTP/WAI 項目 (伺服器) 跨距及
HTTP 結束程式 (用戶端) 跨距。

SDK 提供特殊函數來建立這些已登錄的文字段 (withHttpEntry、 withHttpExit 以及對應的低階函數 startHttpEntry 和 startHttpExit，請參閱上述)。

透過環境變數配置

您也可以透過環境變數來配置 SDK ，而不像上述那樣以程式設計方式來配置 SDK:

INSTANA_AGENT_HOST: 要連接的 Instana 代理程式的 IP 或主機。預設值: 127.0.0.1。
INSTANA_AGENT_PORT: 要連接之 Instana 代理程式的埠。預設值: 42699。
INSTANA_SERVICE_NAME: 置換 Instana 中的預設服務名稱。
INSTANA_FORCE_TRANSMISSION_STARTING_AFTER: 在傳輸至代理程式之前，通常會先緩衝 Spans。此設定會強制在給定的毫秒數之後傳輸所有緩衝的跨距。預設值: 1000。
INSTANA_FORCE_TRANSMISSION_STARTING_AT: 當已緩衝給定的跨距數目時，此設定會強制傳輸所有緩衝的跨距。
INSTANA_MAX_BUFFERED_SPANS: 將跨距數目限制為緩衝區。達到限制時，將捨棄跨距。此設定是一種安全防護，可防止因緩衝過多的跨距數量而導致記憶體洩漏。它必須大於 INSTANA_FORCE_TRANSMISSION_STARTING_AT。
INSTANA_LOG_LEVEL: 請參閱「配置除錯記載」一節。
INSTANA_LOG_LEVEL_STDOUT: 請參閱「配置除錯記載」一節。
INSTANA_OVERRIDE_HSLOGGER_ROOT_HANDLER: 請參閱「配置除錯記載」一節。

進一步閱讀

如需相關資訊，請參閱 Github 和 Hackage的相關文件。