自訂追蹤的最佳作法

使用註釋良好的文字段

為了對您的應用程式和基礎架構進行最佳監視、學習及警示， Instana 會對所有送入的資料執行進階處理和分析。 這包括來自所有來源的所有送入文字段。

為了獲得 Instana 自動分析和處理的最大好處，將適當標籤新增至您的文字段，可讓 Instana 對送入的文字段進行最佳分析及採取行動。

例如，下列 Python OpenTracing 程式碼提供很少資訊。

附註: 下列範例使用 OpenTracing 來說明，但意圖適用於所有自訂追蹤程式碼。

import opentracing

with opentracing.tracer.start_active_span('vanilla') as pscope:
  # ...
  # do something that takes 50ms
  # ...
  pscope.span.log_kv({"foo": "bar"})

從這個程式碼中，我們只知道它是一個名為 vanilla 的跨距，它花費了 50 毫秒。 我們不知道它的跨距類型 :HTTP、RPC 或傳訊跨距。 我們不知道在該期間發生了什麼，例如與基礎架構中的任何其他元件進行通訊。

如果您提供適當的環境定義 OpenTracing 標籤， Instana 會分析並擷取該文字段中要處理的資訊。

import opentracing
import opentracing.ext.tags as ext

with opentracing.tracer.start_active_span('webserver') as pscope:
    pscope.span.set_tag(ext.SPAN_KIND, "entry")
    pscope.span.set_tag(ext.PEER_HOSTNAME, "localhost")
    pscope.span.set_tag(ext.HTTP_URL, "/python/simple/two")
    pscope.span.set_tag(ext.HTTP_METHOD, "POST")
    pscope.span.log_kv({"foo": "bar"})

    # ...
    # work that took 50ms
    # ...

    pscope.span.set_tag(ext.HTTP_STATUS_CODE, 204)

這個註釋良好的跨距會進一步告訴 Instana 在跨距的環境定義中所發生的情況。 從提供的標籤中，我們知道這是對 /python/simple/two 的送入 Web 伺服器要求，產生的 HTTP 狀態碼是 204。

例如，標註良好的跨距可讓 Instana 擷取服務、監視連線及其性能，在儀表板中提供更豐富的體驗。

如需此範例的特性，請參閱 OpenTracing 規格 ，其中定義所有受支援 OpenTracing 標籤的授權性清單。 這個頁面結尾提供 Instana 支援的標籤綜合性清單 (這是 OpenTracing 標籤的超集)。

以項目跨距啟動新的追蹤

在分散式追蹤內，有三種主要類型的跨距:

• 項目: 註釋接收要求、啟動新作業或耗用訊息
• 中間: 註釋未發出或接收呼叫的內部工作 (例如，視圖呈現)
• 結束: 註釋對遠端服務進行呼叫或將訊息發佈至佇列的工作

span.kind 標籤會標示所報告的跨距類型。 如需詳細資料，請參閱此頁面結尾的表格中或 OpenTracing 規格 中的 span.kind 。

啟動新的追蹤時，請從 項目 跨距開始。 如果您未指定 span.kind 標籤，則會將該文字段視為 項目 類型文字段。 將此標籤設為適當的值，可讓您在 Instana 中進行更好的處理、視覺化後端呼叫擷取及對映。

請參閱下列 Go 範例:

// Start a new entry span and set 'kind' to Consumer (entry)
entrySpan := ot.StartSpan("RPCJobRunner")
entrySpan.SetTag(string(ext.SpanKind), string(ext.SpanKindConsumerEnum))

// Now the RPC exit span
spanName := fmt.Sprintf("%s %s", request.Service, request.Method)
clientSpan := ot.StartSpan(spanName, ot.ChildOf(entrySpan.Context()))
clientSpan.SetTag(string(ext.SpanKind), string(ext.SpanKindRPCClientEnum))
clientSpan.SetTag("rpc.call", request.Method)

// Make the RPC call

clientSpan.Finish()
entrySpan.Finish()

以錯誤標示跨距

代表包含錯誤的工作 (例如異常狀況) 的跨距應該包括 error 和 message 標籤。 如需這些標籤的定義，請參閱表格中的定義，如下所示。

在微服務之間傳遞環境定義

為了跨界限 (例如主機、佇列及服務) 傳遞環境定義，分散式追蹤包括方法。 這通常是使用載波 (例如 HTTP 標頭或訊息佇列標頭) 來完成。

如需詳細資料，請參閱我們的 HTTP 標頭說明文件。

設定服務名稱

這是選用項目。 服務名稱是套用至受監視應用程式程序的名稱。 在許多語言中，可以根據使用中的架構或處理程序指令行來自動偵測最佳服務名稱。

如果您要置換此選項，則可以設定每個「追蹤器」的服務名稱。 請參閱下列 Go 語言範例。

serviceName := "default"
if *isServer {
    serviceName = "rpc-client"
} else {
    serviceName = "rpc-server"
}

opts := instana.Options{Service: serviceName})
opentracing.InitGlobalTracer(instana.NewTracerWithOptions(&opts)

所有 Instana OpenTracing 追蹤器也透過環境變數支援此配置。 如果您設定處理程序的環境變數 INSTANA_SERVICE_NAME ，則會使用該值作為處理程序的服務名稱。 這會置換任何程式碼層次服務名稱配置。

另請參閱 Instana 整體 服務擷取技術和規則的說明文件。

設定端點及呼叫名稱

這是選用項目。 在許多語言中，會根據服務類型自動偵測端點及呼叫名稱。

如果您想要置換此選項，您可以設定端點及每個「追蹤器」的呼叫名稱。 請參閱下列 Java 語言範例。

SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "endpoint", "endpoint-name");
SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "call.name", "call-name");

如需 Instana 整體端點擷取技術及規則的相關資訊，請參閱我們的 端點文件。

改寫跨距持續時間

「追蹤 SDK」會自動計算跨距開始及結束的跨距持續時間。

它通常代表您想要測量的項目，但是當它不存在時，您可以使用 duration 標籤來改寫它。

預期的格式為毫秒。

// Overwrite the span duration with 15 milliseconds.
SpanSupport.annotate(Span.Type.ENTRY, "my-custom-span", "duration", "15");

路徑範本: HTTP 端點的視覺化分組

Instana 支援使用路徑範本自動分組端點。 這在許多架構的 Instana 追蹤中都是現成可用的支援。 使用 OpenTracing，需要額外的步驟，如下所述。

各種架構通常都有類似下列的 REST 路徑型樣:

/api/query/1956-01-31/Guido-van-Rossum
/api/query/1976-04-18/Andrew-Ng
/api/query/1912-06-23/Alan-Turing

這些類似端點可以透過報告 HTTP 跨距中具有值 /api/query/{birthdate}/{name}的 http.path_tpl 金鑰來分組， Instana 使用此範本來自動分組符合所提供型樣的端點。 然後，在 Instana 儀表板中， HTTP 端點將分組為單一端點:

/api/query/{birthdate}/{name}

如需 Go 中的範例，請參閱下列:

span := ot.GlobalTracer().StartSpan("myTemplatedSpan", ext.RPCServerOption(incomingContext))
span.SetTag("http.path_tpl", "/api/query/{birthdate}/{name}")
span.SetTag(string(ext.SpanKind), string(ext.SpanKindRPCServerEnum))
span.SetTag(string(ext.HTTPUrl), req.URL.Path)
span.SetTag(string(ext.HTTPMethod), req.Method)
span.SetTag(string(ext.HTTPStatusCode), 200)

請注意，此特性是 Instana 特定的，且不符合 OpenTracing 標準。

已處理標籤

本節列出 Instana 在識別和處理跨距時所尋找的特定標籤。 當找到文字段的下列標籤子集時， Instana 可以更好地處理、分析、視覺化及警示送入的文字段。

請注意，如下所列的標籤是標準 OpenTracing 標籤的 超集 。 每一個標籤都會標示為 OpenTracing 是否符合 ✓ 或 x (如果不符合的話)。

下列部分標籤說明直接取自 OpenTracing 語意慣例文件。

// NodeJS SDK => JSON
span.annotate('sdk.custom.tags.graphql.fields', {
    Account: [ 'id', 'name' ],
    User: [ 'id', 'name' ]
})
span.annotate('sdk.custom.tags.graphql.arguments', {
    User: [ 'where', 'orderBy' ]
})

// Java SDK => String
SpanSupport.annotate("graphql.fields", "{ \"Account\": [\"id\", \"name\"], \"User\": [\"id\", \"name\"] }");
SpanSupport.annotate("graphql.arguments", "{ \"User\": ["\where\", \"orderBy\"] }");

另請參閱

• OpenTracing 文件

• OpenCensus 文件