什么是 OpenTelemetry？

OpenTelemetry 是一個開源的可觀測性框架，由云原生基金會(CNCF)托管。它是 OpenCensus 和 OpenTracing 項目的合并。旨在為所有類型的可觀測信號(如跟蹤、指標和日志)提供單一標準。

• https://opentelemetry.io
• https://www.cncf.io
• https://opencensus.io

OpenTelemetry 指定了如何收集遙測數據并將其發送到后端平臺。通過提供通用的數據格式和 API, OpenTelemetry 使組織更容易共享和重用遙測數據，從而與各種可觀測性工具和平臺集成。

OpenTelemetry 架構促進了靈活性、互操作性和可擴展性，使開發人員能夠采用滿足其特定需求和環境的可觀測性實踐。

遙測數據類型

OpenTelemetry 支持不同的遙測數據類型：

• OpenTelemetry Trace 表示跨多個組件和服務的請求或操作的執行路徑。它們提供詳細的時間和上下文信息，允許開發人員了解請求流并確定性能瓶頸。
• OpenTelemetry Metrics 是對系統行為或資源利用率的定量測量。它們有助于監控和分析一段時間內的性能，并可用于警報、容量規劃和趨勢分析。
• OpenTelemetry Logs 包含有關應用程序中發生的事件、錯誤和活動的結構化或非結構化文本信息。它們對于調試、審計和故障排除非常有用。

如何使用 OpenTelemetry?

開始使用 OpenTelemetry 最簡單的方法是選擇一個分布式跟蹤工具( Jaeger/SigNoz/Uptrace)并遵循他們的文檔。

• https://www.jaegertracing.io
• https://signoz.io
• https://uptrace.dev

術語表

• OpenTelemetry API 是一個編程接口，您可以使用它來檢測代碼以收集遙測數據，如跟蹤、指標和日志。
• OpenTelemetry SDK 是 OpenTelemetry API 的官方實現，用于處理和將收集的遙測數據導出到后端。
• OpenTelemetry Instrumentation 是流行框架和庫的插件，它們使用 OpenTelemetry API 來記錄重要的操作，例如 HTTP 請求、DB 查詢、日志、錯誤等等。
• OpenTelemetry Collector 是應用程序和后端之間的代理。它接收遙測數據，對其進行轉換，然后將數據導出到可以永久存儲數據的后端。Collector 還可以作為一個代理，從被監視的系統中提取遙測數據，例如，OpenTelemetry Redis 或文件系統指標。
• OTLP 是 SDK 和 Collector 使用的 OpenTelemetry 協議，用于將數據導出到后端或其他收集器。作為傳輸協議，OTLP 可以使用 gRPC (OTLP/gRPC) 或 HTTP (OTLP/HTTP)。
• OpenTelemetry Backend 負責接收、存儲和分析 OpenTelemetry 收集的遙測數據。它充當數據的中央存儲庫或處理管道，允許您聚合、查詢、可視化并從應用程序生成的遙測數據中獲得見解。
• OpenTelemetry Jaeger 是 OpenTelemetry 生態系統中的一個項目，通常被用作默認的 OpenTelemetry 后端，用于存儲、分析和可視化遙測數據。

OpenTelemetry 架構

概覽圖

OpenTelemetry 架構旨在提供一種標準化的方法來收集、傳輸和處理來自應用程序和服務的遙測數據。它由幾個關鍵組件組成，這些組件協同工作以實現分布式系統中的可觀測性。

圖片

可觀測性信號

OpenTelemetry 提供了一種捕獲可觀測性信號的標準化方法：

• Metrics(指標) 表明存在問題。
• Traces(跟蹤) 會告訴你問題出在哪里。
• Logs(日志) 可以幫助您找到根本原因。

OpenTelemetry Metrics 是幫助量化系統行為的定量指標。它們提供有關應用程序某些方面的當前狀態或速率的信息，例如 CPU 使用情況、內存消耗或請求延遲。OpenTelemetry 允許您定義和記錄自定義指標，以監視應用程序的性能和運行狀況。

• https://opentelemetry.io/docs/concepts/signals/metrics/

OpenTelemetry Traces 提供了請求在分布式系統中執行路徑的詳細記錄。它們捕獲單個操作及其關系的時間信息，使您能夠了解請求流、確定瓶頸并解決性能問題。使用 OpenTelemetry，您可以對代碼進行檢測，以生成分布式跟蹤并在服務之間進行關聯。

• https://opentelemetry.io/docs/concepts/signals/traces/

OpenTelemetry Logs 是在應用程序執行期間發生的事件或消息的文本記錄。它們幫助您理解應用程序行為、診斷問題和審計活動。OpenTelemetry 提供了一種機制，可以從應用程序中捕獲結構化日志，并用上下文信息豐富它們。

• https://opentelemetry.io/docs/concepts/signals/logs/

Instrumentation 庫(檢測工具程序)

OpenTelemetry 為不同的編程語言提供了庫，開發人員可以使用這些庫來檢測他們的應用程序并收集遙測數據。

Instrumentation 官方詳細文檔

• https://opentelemetry.io/docs/instrumentation/

OpenTelemetry SDK

OpenTelemetry SDK（軟件開發工具包）是一個庫和工具的集合，使開發人員能夠對其應用程序進行檢測并收集遙測數據以進行監控。

Otel SDK 提供了一個標準化和可擴展的框架，用于將 OpenTelemetry 集成到各種編程語言和環境中。

Exporters(導出器)

OpenTelemetry 導出器負責將遙測數據發送到外部系統或后端進行存儲、分析和可視化。

OpenTelemetry 提供了一系列導出程序，支持導出遙測數據的不同協議和格式。這樣的導出器允許用戶將 OpenTelemetry 與其首選的監控和分析工具無縫集成。

OpenTelemetry 協議

OpenTelemetry Protocol（OTLP）是一種開源的、與供應商無關的協議，用于從軟件系統和應用程序收集、傳輸和導出遙測數據。

OTLP 定義了在檢測應用程序和后端系統之間交換的連接格式和數據結構。它指定了遙測數據的編碼格式，包括指標、跟蹤和日志的模式，以及在網絡中傳輸這些數據的規則。

OTLP 導出器允許將收集的遙測數據傳輸到后端進行處理和分析。

Context Propagation(上下文傳播)

Context propagation 確保相關的上下文數據(如 trace IDs、span IDs 和其他元數據)在應用程序的不同服務和組件之間一致地傳播。

通過傳播上下文，OpenTelemetry 確保從不同服務和組件收集的遙測數據保持相關，即使在分布式和微服務架構中也是如此。它支持端到端跟蹤，從而更容易理解請求流、性能瓶頸和系統依賴關系。

Resource(資源)

Resource 屬性是鍵值對，提供有關被監視實體(如服務、進程或容器)的元數據。它們有助于識別資源，并提供可用于過濾和分組遙測數據的附加信息。

通過在遙測數據中包含資源信息，OpenTelemetry 可以更好地分析、可視化和理解系統行為。它有助于關聯和上下文化來自不同來源的遙測數據，并提供觀測到的應用程序或服務的更全面的視圖。

OpenTelemetry Collector(收集器)

OpenTelemetry Collector 通過提供靈活、可擴展的遙測數據收集和處理解決方案，在 OpenTelemetry 生態系統中發揮著關鍵作用。

• https://opentelemetry.io/docs/collector/

Otel Collector 作為一個集中的中介，簡化了數據收集的復雜性，并實現了與不同后端和系統的靈活集成。

OpenTelemetry 后端

OpenTelemetry 不包括特定的內置后端或存儲系統來處理和分析數據。相反，OpenTelemetry 提供了基于您的特定需求和偏好選擇和集成各種后端系統的靈活性。

后端系統從插入指令的應用程序或 OpenTelemetry Collector 接收導出的遙測數據。這些系統負責存儲、分析和可視化遙測數據。

OpenTelemetry 分布式追蹤

分布式追蹤允許您查看請求如何通過不同的服務和系統、每個操作的時間、發生時的任何日志和錯誤。

分布式追蹤工具提供對系統行為的可見性，幫助識別性能問題，協助調試，并幫助確保分布式應用程序的可靠性和可伸縮性。

OpenTelemetry 跟蹤在微服務架構的上下文中特別有價值，在微服務架構中，應用程序由多個獨立的服務組成，共同工作以滿足用戶請求。

追蹤是如何工作的？

在現代應用程序中，尤其是那些基于微服務或無服務器架構的應用程序，不同的服務經常相互交互以滿足單個用戶請求。這使得識別性能瓶頸、診斷問題和分析整個系統行為具有挑戰性。

分布式跟蹤旨在通過創建跟蹤來解決這些挑戰，跟蹤是單個用戶請求通過各種服務和組件的過程的表示。每個跟蹤都由一系列相互連接的 span 組成，其中每個 span 代表特定服務或組件中的單個操作或活動。

當請求進入服務時，跟蹤上下文將與請求一起傳播。這通常涉及到將跟蹤頭注入到請求中，允許下游服務參與同一跟蹤。

當請求在系統中流動時，每個服務都會生成自己的 span，并使用有關其操作持續時間、元數據和任何相關上下文的信息更新跟蹤上下文。

圖片

分布式跟蹤工具使用生成的跟蹤數據來提供對系統行為的可見性，幫助識別性能問題，幫助調試，并幫助確保分布式應用程序的可靠性和可擴展性。

Spans(跨度)

Span 表示跟蹤中的一個操作(工作單元)。span 可以是遠程過程調用(RPC)、數據庫查詢或進程內函數調用。一個 span 有:

• span name(操作名稱)。
• 父 span。
• span kind(類型)。
• 開始和結束時間。
• 報告操作成功或失敗的 status。
• 描述操作的一組鍵值 attributes。
• events 的時間軸。
• 指向其它 span 的鏈接列表。
• 在不同服務之間傳播 trace ID 和其他數據的 span context。

trace 是一個 span 樹，它顯示了請求通過應用程序所產生的路徑。root span 是跟蹤中的第一個 span。

圖片

Span 名稱

OpenTelemetry 后端使用 span 名稱和一些屬性將相似的 span 組合在一起。要正確地對 span 進行分組，請給它們起簡短而簡潔的名字。唯一的 span 名稱的總數應小于 1000。否則，您將有太多的 span 組，您的體驗可能會受到影響。

下面的名字很好，因為它們簡短、獨特，并且有助于將相似的 span 分組在一起:

以下名稱不正確，因為它們包含變量 params 和 args：

Span 類型

Span kind 必須是以下值之一:

• server 用于服務器操作，例如 HTTP 服務器處理程序。
• client 用于客戶端操作，例如 HTTP 客戶端請求。
• producer 對于消息生產者，例如 Kafka producer。
• consumer 一般用于消息消費者和異步處理，例如 Kafka consumer。
• internal 用于內部操作。

Status code(狀態碼)

狀態碼表示操作成功或失敗。必須是以下值之一:

• ok - 成功。
• error - 失敗。
• unset - 允許后端分配狀態的默認值。

Attributes(屬性)

要記錄上下文信息，您可以用帶有特定于操作的信息的屬性對 span 進行注釋。例如，HTTP 端點可能具有 http.method = GET 與 http.route = /projects/:id。

您可以隨意命名屬性，但對于常見操作，您應該使用 semantic attributes 約定。它定義了一個公共屬性鍵列表，其中包含它們的含義和可能的值。

Events(事件)

您還可以用具有開始時間和任意數量屬性的事件注釋 span 。事件和 span 的主要區別在于事件沒有結束時間(因此沒有持續時間)。

事件通常表示異常、錯誤、日志和消息(例如在 RPC 中)，但是您也可以創建自定義事件。

Context(上下文)

當 Span context 通過不同的組件和服務傳播時，它攜帶有關該 span 的信息。

Trace/span context 是一個請求范圍的數據，例如：

• Trace ID. 表示整個 trace 或 query 的全局唯一標識符。trace 中的所有 span 都具有相同的 trace ID。
• Span ID. trace 中特定 span 的唯一標識符。trace 中的每個 span 都有不同的 span ID。
• Trace flags. 指示 trace 的各種屬性的 flag，例如是否對其進行了采樣。采樣是指確定應記錄哪些 span 并將其報告給可觀測性后端的過程。
• Trace State. 一個可選字段，包含與 trace 相關的其他供應商或應用程序特定數據。

Span context 對于保持分布式系統中 span 的連續性和相關性非常重要。它允許不同的服務和組件將其 span 與正確的跟蹤相關聯，并提供對請求或事務流的端到端可見性。

Span context 通常使用服務之間通信協議的標頭或元數據進行傳播，類似于 baggage 數據的傳播方式。這確保了當服務接收到請求時，它可以提取 span context，并將傳入的 span 與正確的 trace 相關聯。

您可以使用上下文中的數據進行 span 相關性或采樣，例如，您可以使用 trace id 來知道哪些 span 屬于哪些 trace。

Context propagation(上下文傳播)

上下文傳播確保相關的上下文數據，如 trace ID、span ID 和其他元數據，在應用程序的不同服務和組件之間一致地傳播。

OpenTemetry 在進程內的函數之間傳播上下文(進程內傳播)，甚至從一個服務傳播到另一個服務(分布式傳播)。

進程內傳播可以是隱式的，也可以是顯式的，這取決于所使用的編程語言。隱式傳播通過將活動上下文存儲在線程局部變量(Java, Python, Ruby, NodeJS)中自動完成。顯式傳播需要顯式地將活動上下文作為參數從一個函數傳遞到另一個函數(Go)。

對于分布式上下文傳播，OpenTelemetry 支持幾種協議，這些協議定義了如何序列化和傳遞上下文數據:

• W3C trace context 在 traceparent header 中, 例如, traceparent=00-84b54e9330faae5350f0dd8673c98146-279fa73bc935cc05-01。

https://www.w3.org/TR/trace-context/

• B3 Zipkin 在以 x-b3- 開始的 header 中, 例如, X-B3-TraceId。
• https://github.com/openzipkin/b3-propagation

W3C trace context 是默認啟用的推薦傳播器。

Baggage(行李)

Baggage 的工作原理類似于 span context，允許您將自定義 key:value 對(屬性)從一個服務傳播到另一個服務。在 gRPC 世界中，有一個類似的概念叫做 gRPC metadata。

• https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/baggage/api.md

Baggage 允許您將鍵值對與請求或事務關聯起來。這些鍵值對表示可能與請求或事務處理相關的上下文信息，例如 user ID、session ID 或其他特定于應用程序的元數據。

Baggage 有助于維護和關聯跨分布式系統的上下文信息，從而實現對應用程序行為的更好的可觀測性和分析。它提供了一種標準化的方式來在整個系統中傳遞相關數據，而不依賴于特別的機制或手動檢測。

什么時候優先去 Instrumentation

Instrumentation 官方詳細文檔

• https://opentelemetry.io/docs/instrumentation/

您不需要記錄每個操作來充分利用跟蹤。這可能會花費很多時間，而且通常是不必要的。優先考慮以下操作：

• Network 操作, 例如，HTTP 請求或 RPC 調用。
• Filesystem 操作, 例如，讀/寫文件。
• Database 查詢，它結合了網絡與文件系統操作。
• Errors and logs，例如，使用結構化日志。

OpenTelemetry Metrics(指標)

OpenTelemetry Metrics 是一個關于如何收集、聚合和發送指標到 OpenTelemetry APM 工具(如 Uptrace 或 Prometheus )的標準。

在定義新標準的同時，OpenTelemetry 還致力于與現有的指標工具協議(如 Prometheus 和 Statsd)一起工作。此外，OpenTelemetry Collector 甚至支持更多的協議，如 AWS Metrics、InfluxDB、Chrony 等。

OpenTelemetry 還允許您通過示例關聯指標和跟蹤，這些示例應該向您展示系統狀態的更廣泛的圖像。

什么是指標?

指標是表示系統運行狀況和性能的數值數據點，例如 CPU 利用率、網絡流量和數據庫連接。

您可以使用指標來度量、監視和比較性能，例如，您可以度量服務器響應時間、內存利用率、錯誤率等等。

Instruments

instrument 是一種特定類型的指標(例如，counter, gauge, histogram)，用于收集關于應用程序行為的特定方面的數據。

您通過創建具有以下功能的 instrument 來捕獲測量結果:

• 唯一的名稱，例如 http.server.duration。
• 一種 instrument 類型，例如 Histogram。
• 一個可選的指標單位，例如 milliseconds 或 bytes。
• 可選描述。

Timeseries(時間序列)

一個 instrument 可以生成多個時間序列。時間序列是一個具有唯一屬性集的指標，例如，對于相同的指標名稱，每個主機都有一個單獨的時間序列。

Additive(可加) instruments

Additive 或 summable instruments 產生的時間序列，當加在一起時，產生另一個有意義和準確的時間序列。測量 non-decreasing 數的 Additive instruments 也稱為 monotonic(單調的)。

例如，http.server.requests 是一個 additive 時間序列，因為您可以將來自不同主機的請求數相加，以獲得請求總數。

但是，system.memory.utilization(百分比) 不是相加的，因為來自不同主機的內存利用率之和沒有意義(90% + 90% = 180%)。

Synchronous(同步) instruments

Synchronous instruments 與它們正在測量的操作一起被調用。例如，為了測量請求的數量，只要有新的請求，就可以調用 counter.Add(ctx, 1)。同步測量可以具有關聯的 trace context。

對于 synchronous instruments，additive 和 grouping instruments 之間的區別在于 additive instruments 產生 summable 時間序列，grouping instruments 產生 histogram。

Asynchronous(異步) instruments

Asynchronous instruments 定期調用回調函數來收集測量值。例如，您可以使用觀察器定期測量內存或 CPU 的使用情況。Asynchronous 測量不能具有關聯的 trace context。

在 UpDownCounterObserver (additive) 和 GaugeObserver (grouping)之間進行選擇時， 對于 summable 時間序列，請選擇 UpDownCounterObserver，否則，請選擇 GaugeObserver。例如，要測量 system.memory.usage (bytes)，應使用 UpDownCounterObserver。但要測量 system.memory.utilization（百分比），您應該使用 GaugeObserver。

選擇 instruments

1. 如果您需要直方圖、熱圖或百分位數，請使用 Histogram。
2. 如果您想通過記錄增量值來計數：

如果該值是 monotonic 的，請使用 Counter。

否則，使用 UpDownCounter。

3. 如果你想通過記錄一個絕對值來測量某個東西：

• 如果該值是 monotonic 的，請使用 CounterObserver。
• 否則，請使用 UpDownCounterObserver。
• 如果該值是 additive/summable 的：
• 如果該值不 additive/summable，請使用 GaugeObserver。

Counter

synchronous monotonic

Counter 是一種同步 instrument，用于測量相加的非遞減值，例如：

• processed requests
• errors
• received bytes
• disk reads

Counters 用于測量一個事件的發生次數或一個值隨時間的累積。它們只能隨著時間的推移而增加。

對于 Counter 時間序列，后端通常計算增量并顯示速率值，例如，per_min(http.server.requests) 返回每分鐘處理的請求數。

CounterObserver

asynchronous monotonic

CounterObserver 是 Counter instrument 的異步版本。

UpDownCounter

synchronous additive

UpDownCounter 是一種同步 instrument，用于測量可隨時間增加或減少的附加值，例如：

• active requests
• open connections
• memory in use (megabytes)

對于加法非遞減(non-decreasing)值，應使用 Counter 或 CounterObserver。

對于 UpDownCounter 時間序列，后端通常顯示最后一個值，但不同的時間序列可以加在一起， 例如，go.sql.connections_open 返回打開的連接總數， go.sql.connections_open{service.name = myservice} 返回一個服務的打開連接數。

UpDownCounterObserver

asynchronous additive

UpDownCounterOserver 是 UpDownCounter instrument 的異步版本。

Histogram

synchronous grouping

直方圖是一種同步 instrument，它根據記錄的值生成直方圖，例如：

• request latency
• request size

直方圖用于測量值隨時間的分布。對于直方圖時間序列，后端通常顯示百分位數、熱圖和直方圖。

GaugeObserver

asynchronous grouping

GaugeObserver 是一種異步 instrument，用于測量 sum 不能產生有意義或正確結果的非相加值，例如：

• error rate
• memory utilization
• cache hit rate

對于 GaugeObserver 時間序列，后端通常顯示最后一個值，不允許將不同的時間序列相加。

Metrics 示例

郵件數量

要測量發送的電子郵件數量，您可以創建 Counter instrument，并在發送電子郵件時遞增：

import "go.opentelemetry.io/otel/metric"

var emailCounter = meter.NewInt64Counter(
	"some.prefix.emails",
	metric.WithDescription("Number of sent emails"),
)

emailCounter.Add(ctx, 1)

稍后，您可以添加更多屬性來收集詳細的統計信息，例如：

• kind = welcome 和 kind = reset_password 可以測量不同的電子郵件。
• state = sent 和 state = bounced 以衡量退回的電子郵件。

操作延遲

要測量操作的延遲，您可以創建 Histogram instrument 并與操作同步更新：

import "go.opentelemetry.io/otel/metric"

var opHistogram = meter.NewInt64Histogram(
	"some.prefix.duration",
	metric.WithDescription("Duration of some operation"),
)

t1 := time.Now()
op(ctx)
dur := time.Since(t1)

opHistogram.Record(ctx, dur.Microseconds())

緩存命中率

要測量緩存命中率，可以創建一個 CounterObserver 并觀察緩存統計信息：

import "go.opentelemetry.io/otel/metric"

var counter metric.Int64CounterObserver

// Arbitrary key/value labels.
hits := []attribute.KeyValue{attribute.String("type", "hits")}
misses := []attribute.KeyValue{attribute.String("type", "misses")}
errors := []attribute.KeyValue{attribute.String("type", "errors")}

batchObserver := meter.NewBatchObserver(
	func(ctx context.Context, result metric.BatchObserverResult) {
		stats := cache.Stats()

		result.Observe(hits, counter.Observation(int64(stats.Hits)))
		result.Observe(misses, counter.Observation(int64(stats.Misses)))
		result.Observe(errors, counter.Observation(int64(stats.Errors)))
	})

counter = batchObserver.NewInt64CounterObserver("some.prefix.cache_operations")

出錯率

要直接測量錯誤率，您可以創建一個 GaugeObserver 并觀察該值，而不必擔心它是如何計算的：

import "go.opentelemetry.io/otel/metric"

_ = meter.NewFloat64GaugeObserver("some.prefix.error_rate",
	func(ctx context.Context, result metric.Float64ObserverResult) {
		result.Observe(rand.Float64())
	},
	metric.WithDescription("Error rate as reported by some other system"),
)

OpenTelemetry Logs(日志)

OpenTelemetry Logs 允許以一種能夠與其他可觀察信號進行關聯和更好集成的方式記錄和收集日志。

日志對于理解應用程序行為、診斷問題和監視系統運行狀況至關重要。分布式跟蹤和指標提供了對系統性能的有價值的見解，而日志提供了關于特定事件、錯誤和應用程序行為的詳細上下文和信息。

概述

雖然 OpenTelemetry 主要關注于收集指標和跟蹤，但它也通過其日志 API 支持日志收集。OpenTelemetry 支持現有的日志解決方案，并確保它可以與現有的日志庫和日志收集工具一起很好地工作。

OpenTelemetry 提供了一個日志 API，允許您檢測應用程序并生成結構化日志。OpenTelemetry Logging API 旨在與其他遙測數據(如指標和跟蹤)一起工作，以提供統一的可觀測性解決方案。

OpenTelemetry 強調結構化的日志，允許您通過屬性或元數據向日志條目附加額外的上下文信息。這允許您包含相關的詳細信息，例如 timestamps, request IDs, user IDs, correlation IDs 和其他有助于日志分析和故障排除的自定義上下文。

不同類型的日志

OpenTelemetry 支持從應用程序或系統中的各種源捕獲日志。根據日志的生成和收集方式，日志可以分為 3 類。

系統和基礎設施日志

系統日志提供有關系統操作、性能和安全性的寶貴信息。系統日志通常由系統內的各種組件生成，包括操作系統、應用程序、網絡設備和服務器。

系統日志是在主機級別編寫的，具有無法輕易更改的預定義格式和內容。系統日志不包括有關跟蹤上下文的信息。

Legacy first-party 日志

First-party 日志由內部應用程序生成，記錄特定的應用程序事件、錯誤和用戶活動。這些日志對于應用程序調試和故障排除非常有用。

通常，開發人員可以修改這些應用程序，以更改日志的編寫方式和包含的信息。例如，為了將日志與跟蹤關聯起來，開發人員可以手動將跟蹤上下文添加到每個日志語句中，也可以使用日志庫的插件自動添加。

例如，要傳播上下文并將日志記錄與 span 相關聯，可以在日志消息中使用以下屬性：

• trace_id 用于 TraceId, 十六進制編碼。
• span_id 用于 SpanId, 十六進制編碼。
• trace_flags 用于 trace flags, 根據 W3C traceflags 格式進行格式化。

例如：

request failed trace_id=958180131ddde684c1dbda1aeacf51d3 span_id=0cf859e4f7510204

New first-party 日志

啟動新項目時，您可以遵循 OpenTelemetry 的建議和最佳實踐， 了解如何使用自動檢測發出日志，或將日志庫配置為使用 OpenTelemetry log 附加程序。

OpenTelemetry 的日志 API 允許開發人員對其應用程序進行 instrument， 以生成結構化日志，這些日志可以由日志后臺或日志管理系統收集和處理。日志 API 提供了一種將附加上下文信息附加到日志條目（如標簽、屬性或元數據）的方法。

使用 Logger API 記錄不同嚴重性級別的事件或消息，如 debug、info、warn、error 等。您還可以將其他屬性或上下文附加到日志條目以提供更多信息。

OpenTelemetry 還提供了一種標準化的方法，用于在分布式系統中傳播日志中的上下文。這確保了相關的執行上下文被一致地捕獲和保存，即使日志是由系統的不同組件生成的。

OpenTelemetry Logs 數據模型允許將 TraceId 和 SpanId 直接包含在 LogRecords 中。

OpenTelemetry 收集器

OpenTelemetry Collector 是一個靈活且可擴展的代理，用于收集、處理和導出遙測數據。它簡化了從多個源接收和管理遙測數據的任務，并能夠將數據導出到多個后端或可觀測性系統。

OpenTelemetry Collector 支持多個日志源，包括應用程序日志、日志文件、日志庫和第三方日志系統。它提供了與流行的日志框架和庫的集成，實現了日志數據的無縫接收。

收集器提供了轉換和豐富日志數據的功能。您可以修改日志屬性、添加元數據或使用其他上下文信息豐富日志，以增強其價值，并使其對分析和故障排除更有意義。

收集和處理后，OpenTelemetry Collector 可以將日志數據導出到各種日志后端或系統。它支持將日志導出到流行的日志記錄平臺、存儲系統或日志管理工具，以進行長期存儲、分析和可視化。

OpenTelemetry 后端

一旦日志數據導出到日志后端，您就可以使用平臺的功能處理和分析日志。這可以包括過濾、搜索、聚合和可視化日志，以深入了解應用程序的行為并解決問題。

OpenTelemetry Sampling(采樣)

OpenTelemetry 采樣通過減少創建（采樣）span 的數量，降低了跟蹤的成本和冗長程度。就性能而言，采樣可以節省收集、處理和導出 span 所需的 CPU 周期和內存。

什么是采樣？

在分布式追蹤中使用采樣來控制收集并發送到跟蹤后端的數據量。它有助于平衡數據量和跟蹤精度之間的權衡。

在分布式跟蹤中，請求在流經系統時生成 span。span 表示在處理該請求期間發生的單個操作或事件。在一個復雜的系統中，這些 span 可能會變得非常多，并且將它們全部發送到跟蹤后端可能會導致大量的開銷和存儲成本。

抽樣涉及到決定哪些時間段要記錄，哪些時間段要丟棄。

采樣：何時何地

采樣可能發生在 span 處理的不同階段：

• 創建 trace 時 - 頭部采樣；
• 當后端接收到 trace 時 - 速率限制采樣；
• 當完整的 trace 可用時 - 基于尾部的采樣；

抽樣策略的選擇取決于幾個因素，包括期望的可觀測性水平、可用資源和系統的特定用例。

概率抽樣

抽樣提供了一種抽樣概率，使得僅使用部分抽樣 span 就能對所有 span 進行準確的統計計數。例如，如果采樣概率為 50%，采樣的 span 數為 10，則調整后的(總) span 數為 10 / 50% = 20。

基于頭部的采樣

基于頭部的抽樣盡可能早地做出抽樣決策，并使用 context 將其傳播給其他參與者。這允許通過不收集任何用于刪除 span (操作)的遙測數據來節省 CPU 和內存資源。

基于頭部的采樣是最簡單、最準確、最可靠的采樣方法，與所有其他方法相比，您應該更喜歡這種方法。

基于頭的采樣的一個缺點是，不能對有錯誤的 span 進行采樣，因為創建 span 時該信息不可用。為了解決這個問題，可以使用基于尾部的采樣。

基于頭部的采樣也不考慮流量峰值，并且可能收集比期望的更多的數據。這就是 rate-limiting 采樣變得方便的地方。

OpenTelemetry 中基于頭的采樣

OpenTelemetry 有 2 個 span 屬性負責客戶端采樣：

• IsRecording - 當為 false 時，span 將丟棄屬性、事件、鏈接等。
• Sampled - 當為 false 時，OpenTelemetry 刪除 span。

您應該檢查 IsRecording 屬性，以避免收集昂貴的遙測數據。

if span.IsRecording() {
    // collect expensive data
}

Sampler 是一個接受將要創建的 root span 的函數。該函數返回一個采樣決策，該決策必須是:

• Drop - trace 被丟棄。IsRecording = false, Sampled = false。
• RecordOnly - 記錄 trace，但不采樣。IsRecording = true, Sampled = false。
• RecordAndSample - 記錄并采樣 trace。IsRecording = true, Sampled = true。

默認情況下，OpenTelemetry 對所有跟蹤進行采樣，但您可以將其配置為對部分跟蹤進行采樣。在這種情況下，后端使用概率抽樣來調整 span 的數量。

OpenTelemetry 采樣器

AlwaysOn sampler 對每個 trace 進行采樣，例如，將為每個請求啟動并導出一個新的 trace。

AlwaysOff sampler 不采樣 trace，換句話說，刪除所有 trace。您可以使用此采樣器執行負載測試或暫時禁用 trace。

TraceIDRatioBased sampler 使用 trace id 對跟蹤的一小部分進行采樣，例如，20% 的跟蹤。

Parent-based sampler 是一種復合采樣器，它根據 span 的父元素表現出不同的行為。當您開始一個新的 trace 時，采樣器將決定是否對其進行采樣，并將該決策向下傳播到其他服務。

速率限制采樣

速率限制采樣發生在服務器端，并確保您不會超過某些限制，例如，它允許每秒采樣 10 個或更少的跟蹤。

限速采樣支持調整計數，但精度較低。為了獲得更好的結果并提高性能，您應該將限速采樣與更有效和準確的基于頭部的采樣一起使用。

大多數后端在必要時自動應用限速采樣。

基于尾部采樣

在基于頭部的采樣的抽樣中，抽樣決策是預先做出的，通常是隨機的?；陬^部的采樣不能對失敗或異常長時間的操作進行采樣，因為這些信息只能在跟蹤結束時獲得。

使用基于尾部的采樣，我們延遲采樣決策，直到跟蹤的所有 span 可用，這使得基于來自跟蹤的所有數據的更好的采樣決策。例如，我們可以對失敗或異常長的跟蹤進行采樣。

大多數 OpenTelemetry 后端在必要時自動應用基于尾部的采樣，但是你也可以使用 OpenTelemetry Collector 和 tailsamplingprocessor 來根據你的需要配置采樣。

基于概率的采樣

基于概率的采樣根據配置的概率或采樣率隨機選擇要記錄的跟蹤的子集。例如，您可以設置采樣率為 10%，這意味著只記錄 10% 的跡線，其余的跡線被丟棄。

當您希望減少跟蹤數據的數量，同時仍然保持系統行為的代表性樣本時，基于概率的采樣非常有用。它有助于在開銷和所需的可觀測性級別之間取得平衡。

以下是如何在 OpenTelemetry Go 中配置基于概率的采樣器，基于 Uptrace。

import "go.opentelemetry.io/contrib/samplers/probability/consistent"

sampler := consistent.ParentProbabilityBased(
	consistent.ProbabilityBased(0.5), // sample 50% of traces
)

uptrace.ConfigureOpentelemetry(
	uptrace.WithTraceSampler(sampler),

	// Other options
)

OpenTelemetry Collector(收集器)

OpenTelemetry Collector 是一個高性能、可擴展和可靠的數據收集管道，用于可觀察性數據。它從各種來源接收遙測數據，執行處理和轉換為通用格式，然后將數據導出到各種后端進行存儲和分析。

Otel Collector 支持多種數據格式、協議和平臺，使其成為可觀察性需求的靈活、可擴展的解決方案。

OpenTelemetry Collector 是如何工作的？

OpenTelemetry Collector 是應用程序和分布式跟蹤工具(如 SigNoz/Jaeger)之間與供應商無關的代理/中間人。

OpenTelemetry Collector 的工作原理是接收來自各種來源的遙測數據， 對數據進行處理和規范化，然后將其導出到各種后端進行存儲和分析。

Otel Collector 提供強大的數據處理能力，允許您執行聚合，過濾，采樣和豐富的遙測數據。在將數據發送到后端系統之前，您可以轉換和重塑數據以滿足特定的監視和分析需求。

Otel Collector 是用 Go 語言編寫的，使用 Apache 2.0 license ，允許您更改源代碼并安裝自定義擴展。這是以運行和維護您自己的 OpenTelemetry Collector 實例為代價的。

何時使用 OpenTelemetry Collector?

大多數情況下，將遙測數據直接發送到后端是開始使用 OpenTelemetry 的好方法。但是，您可能希望在服務旁邊部署收集器，以獲得批處理、重試、敏感數據過濾等功能。

OpenTelemetry Collector 最突出的特性是能夠操作整個軌跡，而不是單個 span。為了實現這一點，OpenTelemetry Collector 緩沖接收到的 span，并按 trace id 對它們進行分組。這是實現基于 tail-based sampling 的關鍵要求。

OpenTelemetry Collector 也可以作為一個 agent，從被監控的系統中提取遙測數據，例如，OpenTelemetry Redis 或 host metrics。

Otelcol 與 Otelcol-Contrib

OpenTelemetry Collector 在 GitHub 上有 2 個存儲庫:

• opentelemetry-collector 是只包含最關鍵組件的核心。它以 otelcol 二進制文件的形式分發。

• https://github.com/open-telemetry/opentelemetry-collector

• opentelemetry-collector-contrib 包含核心和所有額外的可用組件，例如，Redis 和 PostgreSQL 接收器。它以 otelcol-contrib 二進制文件的形式分發。
• https://github.com/open-telemetry/opentelemetry-collector-contrib

您應該始終安裝和使用 otelcol-contrib，因為它和核心一樣穩定，并且支持更多的特性。

安裝

OpenTelemetry Collector 為 Linux、MacOS 和 Windows 分發預編譯的二進制文件。

Linux

要安裝 otelcol-contrib binary 和相關的 systemd 服務，運行以下命令將 0.82.0 替換為所需的版本，并將 amd64 替換為所需的架構:

Debian

wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.82.0/otelcol-contrib_0.82.0_linux_amd64.deb
sudo dpkg -i otelcol-contrib_0.82.0_linux_amd64.deb

RPM

wget https://github.com/open-telemetry/opentelemetry-collector-releases/releases/download/v0.82.0/otelcol_0.82.0_linux_amd64.rpm
sudo rpm -ivh otelcol_0.82.0_linux_amd64.rpm

您可以使用以下命令檢查已安裝服務的狀態:

sudo systemctl status otelcol-contrib

使用以下命令檢查日志:

sudo journalctl -u otelcol-contrib -f

您可以在 /etc/otelcol-contrib/config.yaml 中編輯配置。并重新啟動 OpenTelemetry Collector:

sudo systemctl restart otelcol-contrib

從源代碼編譯

你也可以在本地編譯 OpenTelemetry Collector:

git clone https://github.com/open-telemetry/opentelemetry-collector-contrib.git
cd opentelemetry-collector-contrib
make install-tools
make otelcontribcol
./bin/otelcontribcol_linux_amd64 --config ./examples/local/otel-config.yaml

配置

OpenTelemetry Collector 是高度可配置的，允許您自定義其行為并將其集成到可觀測性堆棧中。它提供了用于指定輸入、處理器和導出器的配置選項，使您能夠根據自己的特定需求定制代理。

默認情況下，你可以在 /etc/otelcol-contrib/config.yaml 中找到配置文件。例如(Uptrace):

# receivers configure how data gets into the Collector.
receivers:
  otlp:
    protocols:
      grpc:
      http:

# processors specify what happens with the received data.
processors:
  resourcedetection:
    detectors: [env, system]
  cumulativetodelta:
  batch:
    send_batch_size: 10000
    timeout: 10s

# exporters configure how to send processed data to one or more backends.
exporters:
  otlp/uptrace:
    endpoint: otlp.uptrace.dev:4317
    headers:
      uptrace-dsn: 'https://<token>@uptrace.dev/<project_id>'

# service.pipelines pull the configured receivers, processors, and exporters together into
# pipelines that process data.
#
# receivers, processors, and exporters that are not used in pipelines are silently ignored.
service:
  pipelines:
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/uptrace]
    metrics:
      receivers: [otlp]
      processors: [cumulativetodelta, batch, resourcedetection]
      exporters: [otlp/uptrace]
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp/uptrace]

您可以通過官方文檔了解更多關于 Otel Collector 的信息。

• https://opentelemetry.io/docs/collector/configuration/

故障排除

如果 otelcol 沒有像預期的那樣工作，您可以檢查日志輸出是否存在潛在問題。日志記錄的詳細程度默認為 INFO，但您可以使用配置文件更改它:

service:
  telemetry:
    logs:
      level: 'debug'

查看潛在問題的日志。

sudo journalctl -u otelcol-contrib -f

您還可以啟用 metrics 來監視 OpenTelemetry Collector:

receivers:
  prometheus/otelcol:
    config:
      scrape_configs:
        - job_name: 'otelcol'
          scrape_interval: 10s
          static_configs:
            - targets: ['0.0.0.0:8888']

service:
  telemetry:
    metrics:
      address: ':8888'
  pipelines:
    metrics/hostmetrics:
      receivers: [prometheus/otelcol]
      processors: [cumulativetodelta, batch, resourcedetection]
      exporters: [otlp/uptrace]

擴展

Extensions 為 OpenTelemetry Collector 提供了額外的功能，并且不需要直接訪問遙測數據， 例如，健康檢查擴展響應健康檢查請求。

extensions:
  # Health Check extension responds to health check requests
  health_check:
  # PProf extension allows fetching Collector's performance profile
  pprof:
  # zPages extension enables in-process diagnostics
  zpages:
  # Memory Ballast extension configures memory ballast for the process
  memory_ballast:
    size_mib: 512

資源檢測

為了檢測來自主機的資源信息，Otel Collector 自帶 resourcedetection processor。

• https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor

Resource Detection Processor 自動檢測和標記有關數據生成環境的元數據。這種元數據稱為 "resources"，為遙測數據提供上下文，可以包括主機、服務、容器和云提供商等信息。

例如，要檢測 host.name 和 os.type 屬性，可以使用系統檢測器：

processors:
  resourcedetection:
    detectors: [env, system]

service:
  pipelines:
    metrics:
      receivers: [otlp, hostmetrics]
      processors: [batch, resourcedetection]
      exporters: [otlp/uptrace]

要添加自定義屬性，如 IP 地址，你可以使用 env 變量和 env 檢測器:

export OTEL_RESOURCE_ATTRIBUTES="instance=127.0.0.1"

為了檢測更多的信息，您可以使用更專門的檢測器，例如，如果您正在使用 Amazon EC2，您可以使用 ec2 檢測器來發現 cloud.region 和 cloud.availability_zone 屬性：

processors:
  resourcedetection/ec2:
    detectors: [env, ec2]

如果您正在使用 Google Cloud:

processors:
  resourcedetection/gcp:
    detectors: [env, gcp]

如果你正在使用 Docker:

processors:
  resourcedetection/docker:
    detectors: [env, docker]

您可以查看官方文檔，了解 Heroku、Azure、Consul 和許多其他可用的檢測器。

• https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/processor/resourcedetectionprocessor#system-metadata

內存限制器

memorylimiterprocessor 是一個組件，允許用戶在處理遙測數據時限制 OpenTelemetry Collector 消耗的內存量。它可以防止收集器使用過多的內存，這可能導致性能問題甚至崩潰。

• https://github.com/open-telemetry/opentelemetry-collector/blob/main/processor/memorylimiterprocessor/README.md

Memory Limiter Processor 的工作方式是定期檢查 OpenTelemetry Collector 消耗的內存量，并將其與用戶定義的內存限制進行比較。如果收集器使用的內存超過指定的限制，處理器將開始丟棄遙測數據，直到內存使用低于限制。

要啟用內存限制器：

processors:
  memory_limiter:
    check_interval: 1s
    limit_mib: 4000
    spike_limit_mib: 800

service:
  pipelines:
    metrics:
      processors: [memory_limiter]

OpenTelemetry 主機指標

hostmetricsreceiver 是一個 OpenTelemetry Collector plugin，它收集關于主機系統的各種指標，例如，CPU, RAM，磁盤指標和其他系統級指標。

• https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver

通過收集和分析主機指標，您可以深入了解主機系統的性能和運行狀況，并識別可能影響應用程序和服務整體性能的潛在問題或瓶頸。

主機指標

要開始收集主機指標，您需要在要監視的每個系統上安裝 Collector，并將以下行添加到 Collector 配置中:

processors:
  resourcedetection:
    detectors: [env, system]
  cumulativetodelta:

receivers:
  hostmetrics:
    collection_interval: 10s
    scrapers:
      # CPU utilization metrics
      cpu:
      # Disk I/O metrics
      disk:
      # File System utilization metrics
      filesystem:
      # CPU load metrics
      load:
      # Memory utilization metrics
      memory:
      # Network interface I/O metrics & TCP connection metrics
      network:
      # Paging/Swap space utilization and I/O metrics
      paging:

service:
  pipelines:
    metrics:
      receivers: [otlp, hostmetrics]
      processors: [cumulativetodelta, batch, resourcedetection]
      exporters: [otlp/uptrace]

文件系統指標

如果您使用的是不常見的文件系統，您可能需要更徹底地配置 filesystem 接收器，例如，只抓取支持的文件系統類型并避免警告：

receivers:
  hostmetrics:
    collection_interval: 10s
    scrapers:
      cpu:
      disk:
      load:
      filesystem:
        include_fs_types:
          match_type: strict
          fs_types: [ext3, ext4]
      memory:
      network:
      paging:

進程指標

要收集每個進程的 CPU、內存和磁盤 I/O 指標，您需要啟用各自的抓取器：

receivers:
  hostmetrics:
    collection_interval: 10s
    scrapers:
      # Process count metrics
      process:
      # Per process CPU, Memory, and Disk I/O metrics
      processes:

這些抓取器在默認情況下是禁用的，因為它們需要以更高的權限運行 OpenTelemetry Collector 才能訪問其他進程的信息。

在 Linux 上，你可以在 root 用戶下運行 otelcol-contrib:

# /lib/systemd/system/otelcol-contrib.service

User=root
Group=root

或者使用 sudo 啟動該進程：

# /lib/systemd/system/otelcol-contrib.service

ExecStart=sudo /usr/bin/otelcol-contrib $OTELCOL_OPTIONS

容器主機指標

在 Linux 上，OpenTelemetry 從 Linux 系統目錄收集指標。要收集關于主機系統而不是容器的指標，可以在運行容器時掛載主機文件系統:

# mount the entire filesystem
docker run -v /:/hostfs ...

# or mount only parts you need
docker run -v /proc:/hostfs/proc ...

然后配置 root_path，以便 hostmetrics 接收器知道根文件系統的位置:

receivers:
  hostmetrics:
    root_path: /hostfs

Refs

• https://opentelemetry.io/
• https://uptrace.dev/opentelemetry/
• React 前端應用中快速實踐 OpenTelemetry 云原生可觀測性(SigNoz/K8S)