指導教學: 使用 Instana 追蹤 SDK 檢測自訂 Java HTTP 架構

程式碼範例

custom-http-sample 指導教學的程式碼範例位於 github.com。 它會實作下列實務範例:

如果您執行範例並開啟 http://localhost:8080，則會收到回應 Hello, Stan!。 不過，如果您在 Instana 中分析呼叫，您會看到追蹤已中斷。

追蹤 1:

追蹤 2:

送出要求是使用 Apache HTTP 用戶端來實作， Instana 的自動追蹤支援此用戶端。 遺漏的鏈結是自訂 HTTP 伺服器上的項目跨距 (送入呼叫) GET /greeting 。

啟用追蹤自訂 HTTP Server

對於支援的架構， Instana 代理程式會自動指示 Java 應用程式。 對於自訂 HTTP 伺服器，我們需要新增一些註釋，以告知 Instana 代理程式哪些方法呼叫應該啟動新的跨距。

首先，新增 mvn 相依關係

<dependency>
  <groupId>com.instana</groupId>
  <artifactId>instana-java-sdk</artifactId>
  <version>1.2.0</version>
</dependency>

其次，在處理自訂 HTTP 伺服器中的 HTTP 要求的方法中新增 @Span 註釋。

@Span(type = Span.Type.ENTRY, value = "my-custom-http-server")
public String apply(Map<String, String> headers) {
  // ...
}

此註釋告訴 Java 代理程式產生 ENTRY 文字段 (又稱為。 伺服器跨距)。

第三，將下列內容新增至 Instana 代理程式的 configuration.yaml 檔案，以告知它應該掃描套件 com.instana.sample.* 中的 Java 類別是否有 @Span 註釋:

com.instana.plugin.javatrace:
  instrumentation:
    sdk:
      packages:
        - 'com.instana.sample'

現在，自訂伺服器已檢測，您會看到從 /greeting的送入呼叫觸發對 /name 的送出呼叫。

不過，追蹤仍會中斷，因為在送入呼叫和送出呼叫之間不會傳遞追蹤 ID。

處理送入追蹤標頭

Instana 使用下列 HTTP 標頭，將追蹤資訊從一個服務傳遞至下一個服務:

• X-INSTANA-T: 追蹤 ID
• X-INSTANA-S: 母項跨距 ID
• X-INSTANA-L: 層次 0 表示應該抑制追蹤，這可能適用於性能檢查

為了使客戶 HTTP 伺服器中的追蹤環境定義產生關聯，您需要將下列方法新增至 GreetingHandler:

private void correlateTracing(Map<String, String> request) {
  String level = request.remove(SpanSupport.LEVEL);
  String traceId = request.remove(SpanSupport.TRACE_ID);
  String parentSpanId = request.remove(SpanSupport.SPAN_ID);

  if (SpanSupport.SUPPRESS.equals(level)) {
    SpanSupport.suppressNext();
  } else if (traceId != null && parentSpanId != null) {
    SpanSupport.inheritNext(traceId, parentSpanId);
  }
}

請注意，我們會在評估標頭之後移除它們，只會保留原始標頭，因為它們會在沒有 Instana 追蹤的情況下傳送。

不過，您不能只在 apply()中呼叫 correlateTracing() ，因為在呼叫含有 @Span 註釋的方法之前，必須先評估標頭。 作為暫行解決方法，您可以將 apply() 方法重新命名為 doApply() 並新增步驟，如下所示:

@Override
public String apply(Map<String, String> headers) {
  correlateTracing(headers);
  return doApply(headers);
}


@Span(type = Span.Type.ENTRY, value = "my-custom-http-server")
private String doApply(Map<String, String> headers) {
  // ...
}

當您現在執行 curl http://localhost:8080時，您會在 Instana 中看到完整的追蹤

新增標籤

到目前為止，我們的 my-custom-http-server span 只是一般的 ENTRY span ，沒有任何其他註釋。 如果你看一下細節，它們看起來是很空的。

您可以在作用中 @Span 環境定義內呼叫 SDK 的 SpanSupport.annotate() 方法，以將註釋新增至現行跨距。 Instana 支援部分 OpenTracing的語意使用慣例，如 Java 追蹤 SDK 文件中所述。 為了新增 HTTP 註釋，請在 doApply() 方法頂端新增下列行:

@Span(type = Span.Type.ENTRY, value = SPAN_NAME)
private String doApply(Map<String, String> headers) {
  SpanSupport.annotate(Span.Type.ENTRY, SPAN_NAME,"tags.http.url", "http://localhost:8080/greeting");
  SpanSupport.annotate(Span.Type.ENTRY, SPAN_NAME,"tags.http.method", "GET");
  SpanSupport.annotate(Span.Type.ENTRY, SPAN_NAME,"tags.http.status_code", "200");
  // ...
}

現在，自訂 HTTP 伺服器的 ENTRY 跨距的詳細資料會顯示指定的 HTTP meta 資料。

請注意，從 Jetty 到自訂 HTTP 伺服器的對應 EXIT 跨距已具有 HTTP meta 資料，因為用戶端使用 Instana 自動追蹤所支援的 Apache HTTP 用戶端。

SpanSupport.annotate(Span.Type.ENTRY, SPAN_NAME,"tags.error", "true");