Haskell のモニタリング

SDK を WAI ミドルウェア・プラグインとして使用して、WAI アプリケーションのすべての着信 HTTP 要求に対して、SDK がエントリー・スパンを自動的に作成するようにすることができます。 Instana トレース・ヘッダーと W3C トレース・コンテキスト・ヘッダーは、プラグインによって自動的に考慮されます。 出口スパンは、 withHttpExit または startHttpExit/completeExit 関数を使用して手動で作成する必要があることに注意してください (以下を参照してください)。

ミドルウェア・プラグインは、HTTP 応答に追加の HTTP 応答ヘッダー (Server-Timing) も追加します。 このヘッダーは、Web サイト・モニター・バックエンド相関を有効にします。

import qualified Instana.Wai.Middleware.Entry as InstanaWaiMiddleware

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

with で始まるすべての関数は (他のパラメーターの中でも) 入出力アクションを受け入れます。 SDK は、スパンを事前に開始してから、指定された入出力アクションを実行し、その後でスパンを完了します。 この記法の使用は、自分でスパンを開始して完了する必要がある低水準 API よりも推奨されます。

• withRootEntry: トレースのルートである (親スパンがない) エントリー・スパンを作成します。
• withEntry: 親スパンを持つエントリー・スパンを作成します。
• withHttpEntry: Instana トレース・ヘッダーまたは W3C トレース・コンテキスト・ヘッダーについて着信 HTTP 要求を検査し、エントリー・スパンを作成する便利な関数。 正しいメタデータをスパンに自動的に追加します。 Instana WAI ミドルウェア・プラグインの使用時に着信 HTTP 要求を処理する必要がないことに注目してください (上記を参照)。
• withHttpEntry_: より汎用性の高いタイプのシグニチャーを使用するものの、機能が少ない withHttpEntry のバリアント。 withHttpEntryの場合と同様に、着信ヘッダー (Instana ヘッダーまたは W3C トレース・コンテキスト) からのトレースが自動的に続行されますが、HTTP 応答の状況コードはキャプチャーされず、Web サイト・モニターのバックエンド相関 (Server-Timing) の応答ヘッダーも追加されません。 可能な場合は、この関数の代わりに withHttpEntry を使用することをお勧めします。 または、withHttpEntry_ ブロックの内部で postProcessHttpResponse を呼び出して、上記の 2 つの欠落した機能に対応することもできます。 Instana WAI ミドルウェア・プラグインの使用時に着信 HTTP 要求を処理する必要がないことに注目してください。
• withExit: エグジット・スパンを作成します。 エグジット・スパンには親としてエントリー・スパンが必要であるため、withRootEntry または withEntry の呼び出しの中でのみ呼び出すことができます。
• withHttpExit: 特定の HTTP クライアント要求のエグジット・スパンを作成します。 正しいメタデータをスパンに自動的に追加するため、発信 HTTP 要求のトレース時に withExit よりも優先されます。 また、Instana トレース HTTP ヘッダーと W3C トレース・コンテキスト HTTP ヘッダー HTTP を要求に追加して、トレース・コンテキストをダウンストリームに伝搬します。
• postProcessHttpResponse: HTTP エントリーの応答を処理します。 この関数は、HTTP エントリー・スパンがまだアクティブである間に呼び出す必要があります。 withHttpEntry_ ブロック内、または startHttpEntry から completeEntry の間で使用できます。 この関数は 2 つのことを実現します。すなわち、応答から HTTP 状況コードをキャプチャーし、現在アクティブなスパンに注釈として追加します。 また、Web サイトのバックエンド相関のモニターを可能にする HTTP 応答に、追加の HTTP 応答ヘッダー (サーバー・タイミング) を追加します。 クライアント・コードでは、これを直接呼び出す必要はほとんどありません。 代わりに、両方を自動的に実行する withHttpEntry を使用して着信 HTTP 要求をキャプチャーします。
• addAnnotation: 現在のスパンにタグを追加します。

• startRootEntry: トレースの先頭である (親スパンがない) エントリー・スパンを開始します。 いずれかの時点で completeEntry を呼び出す必要があります。
• startEntry: エントリー・スパンを開始します。 いずれかの時点で completeEntry を呼び出す必要があります。
• startHttpEntry: 着信 HTTP 要求のエントリー・スパンを開始します。 正しいメタデータをスパンに自動的に追加します。 WAI ミドルウェア・プラグインの使用時に着信 HTTP 要求を処理する必要はありません (上記を参照)。 いずれかの時点で completeEntry を呼び出す必要があります。
• startExit: エグジット・スパンを開始します。 いずれかの時点で completeExit を呼び出す必要があります。
• startHttpExit: 発信 HTTP 要求のエグジット・スパンを開始します。 正しいメタデータをスパンに自動的に追加するため、発信 HTTP 要求のトレース時に startExit よりも優先されます。 また、HTTP ヘッダーを要求に追加して、トレース・コンテキストをダウンストリームに伝搬します。 いずれかの時点で completeExit を呼び出す必要があります。
• completeEntry: エントリー・スパンをファイナライズします。 スパンは、Instana エージェントに送信するために SDK のスパン・バッファーに入れられます。
• completeExit: エグジット・スパンをファイナライズします。 スパンは、Instana エージェントに送信するために SDK のスパン・バッファーに入れられます。

Instana のカスタム・トレースに関する資料を読んでいることを確認してください。この資料には、Instana トレースをコードに統合するための便利な情報が多数含まれています。特に、(InstanaSDK.addTagおよびInstanaSDK.addTagAtを介して) スパンに追加できるメタデータについて説明しています。

Instana は、いわゆる登録されたスパンと SDK スパンとを区別します。 登録されたスパンは通常、自動トレースによって作成され、Instana の処理パイプラインで登録されているスパンごとに特殊な処理があります。 これに対して、SDK スパンは、トレース SDK (Haskell トレース SDK や、他のランタイム・プラットフォーム用のその他の類似 SDK のような) を使用して作成されるタイプのスパンです。 SDK スパンは、Instana の処理パイプラインによってより汎用性の高い方法で処理されます。

この SDK を使用して作成されるほぼすべてのスパンが SDK スパンであることに注意してください。 この SDK が登録されたスパンを作成する例外は次の 2 つのみです。

• HTTP/WAI エントリー (サーバー) スパン
• HTTP エグジット (クライアント) スパン

このSDKには、これらの登録済みスパンを作成するための特別な関数（withHttpEntry、 withHttpExit および対応する低レベル関数 startHttpEntry と startHttpExit）が用意されています（ 「ブラケットのスタイル 」および「 低レベル」 を参照： API ）。