OpenTelemetry Collector 由接收器 (Receivers)、導出器 (Exporters)、處理器 (Processors)、連接器 (Connectors) 和擴展 (Extensions) 等組件組成。每個組件通常是一個或多個管道的一部分。本文幫助您了解如何解決 Collector 的常見問題，以及當您懷疑找到了一個錯誤時該怎麼辦。
當您的遙測客戶端生成了數據，但後端沒有接收到它，請使用指標 otelcol_receiver_accepted_spans 來確保 Collector 已接收到數據點。如果您期望該數據點已經被計入此指標，但尚未這樣做，請檢查指標 otelcol_receiver_refused_spans 以確保它沒有被 Collector 拒絕。
請參見指標部分，以獲得有關 Collector 自己指標的更多信息。
當兩個指標都沒有顯示已看到的數據點時，這表示 Collector 根本沒有接收到數據點。在這種情況下，請檢查您的遙測客戶端和 Collector 之間的連接。在可能的情況下，簡化數據源（通常是您的工作負載）和 Collector 之間的網絡。例如，嘗試直接在您的機器上運行所有內容，而不是作為容器。有關如何在本地運行 Collector 的更多信息，請參考入門指南。
快速驗證 Collector 是否收到數據的方法是使用類似於以下的配置：
receivers:
otlp:
protocols:
grpc:
exporters:
logging:
service:
pipelines:
traces:
receivers: [ otlp ]
processors:
exporters: [ logging ]
基於此，當通過跟踪管道接收數據時，您應該看到與下面類似的輸出：
2023-05-05T15:04:58.982-0300 info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "logging", "#spans": 512}
如果您沒有看到這樣的輸出，那麼這是一個很好的指示，顯示您的接收器沒有接收到您期望的數據。
當您確認 Collector 已收到數據點後，下一步應該檢查導出器端的類似指標：otelcol_exporter_sent_spans 和 otelcol_exporter_send_failed_spans。如果您只看到sent spans，則導出器報告它能夠將所有數據點發送到目的地。在這種情況下，請檢查後端的日誌以獲得線索。
請參閱指標以獲得更多有關 Collector 自身指標的信息。
要找出導出器是否不按預期工作的好方法是在您當前使用的相同管道中添加一個logging導出器。這樣做時，您應該看到將遙測數據打印到控制台，確認導出器已查看到數據：
2023-05-07T10:53:48.893-0300 info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "logging", "#spans": 2}
如果您的後端仍然看不到任何數據，請嘗試禁用導出器可能具有的任何韌性機制，例如發送隊列或重試機制。以下是一個配置文件的示例，其中包含了上面的所有建議：
receivers:
otlp:
protocols:
grpc:
exporters:
logging:
otlp:
endpoint: failing.example.com:4317
sending_queue:
enabled: false
retry_on_failure:
enabled: false
service:
pipelines:
traces:
receivers: [ otlp ]
processors:
exporters: [ logging, otlp ]
此時，指標可能如下所示，表明lggging導出器能夠導出數據，但 otlp 導出器沒有：
otelcol_exporter_sent_spans{exporter="logging",service_instance_id="d9853063-c63c-48db-8b13-69e379b38314",service_name="otelcol",service_version="0.75.0"} 4
otelcol_exporter_sent_spans{exporter="otlp",service_instance_id="d9853063-c63c-48db-8b13-69e379b38314",service_name="otelcol",service_version="0.75.0"} 0
此時，查找線索的最佳地點是 Collector 控制台。如果它沒有顯示任何可能有助於解釋問題的進一步日誌，請仔細檢查導出器的文檔，以獲得該導出器的具體指令。
當您需要對遠程 OTLP 服務器進行身份驗證時，例如 Grafana Cloud OTLP，請使用 auth 擴展並告訴導出器使用它們。請查看《連接 OpenTelemetry Collector 到 Grafana Cloud 數據庫》以獲得有關如何獲取您的用戶名和密碼的更多信息。這比直接在 URL 中以用戶名和密碼的形式傳遞認證數據更為可取。以下是建議的示例：
extensions:
basicauth/traces:
client_auth:
username: "1234" # your Username / Instance ID
password: "ey..." # your API key with the "MetricsPublisher" role
exporters:
otlphttp:
endpoint: "https://otlp-gateway-prod-us-central-0.grafana.net/otlp"
auth:
authenticator: basicauth/traces
當向 Grafana Tempo 或 Grafana Cloud Traces 發送數據時，請確保您正在使用 OTLP gRPC 導出器，且端點只包含主機名和端口，如以下示例所示：
exporters:
otlp:
endpoint: tempo-us-central1.grafana.net:443
您可以通過查看Grafana Cloud帳戶頁面的Tempo部分找到Grafana Cloud Traces的正確主機名和端口。在“詳細信息”下，您應該看到像這樣的URL：https://tempo-us-central1.grafana.net/tempo，這在 Collector 配置中轉換為 tempo-us-central1.grafana.net:443。
當向 Grafana Mimir 或 Grafana Cloud Metrics 發送數據時，請確保您正在使用 Prometheus Remote Write 導出器，且端點包含完整的 URL，包括推送端點的完整路徑，如以下示例所示：
exporters:
prometheusremotewrite:
endpoint: https://prometheus-blocks-prod-us-central1.grafana.net/api/prom/push
您可以通過查看Grafana Cloud帳戶頁面的Prometheus部分找到Grafana Cloud Metrics的正確主機名和端口。在“詳細信息”下，您應該看到Prometheus Remote Write端點，如下所示：https://prometheus-blocks-prod-us-central1.grafana.net/api/prom/push，這可以在 Collector 配置中直接使用。
當向 Grafana Loki 或 Grafana Cloud Logs 發送數據時，請確保您正在使用 Loki 導出器，且端點包含完整的 URL，包括推送端點的完整路徑，如以下示例所示：
exporters:
loki:
endpoint: https://logs-prod-us-central1.grafana.net/loki/api/v1/push
您可以通過查看Grafana Cloud帳戶頁面的Loki部分找到Grafana Cloud Logs的正確主機名和端口。在“詳細信息”下，您應該看到一個像這樣的URL：https://logs-prod-us-central1.grafana.net，這可以轉換為 https://logs-prod-us-central1.grafana.net/loki/api/v1/push，並在 Collector 配置中使用。
Collector 提供了一套工具，可用於進一步的故障排除，如下所示。
記錄導出器可以加入到任何管道中，並會在控制台打印它所看到的遙測數據的基本信息。
本文檔中早些時候看到的一個例子是這樣的：
2023-05-07T10:53:48.893-0300 info TracesExporter {"kind": "exporter", "data_type": "traces", "name": "logging", "#spans": 2}
然而，當您想檢查實際導出的數據時，您應該增加記錄導出器的detailed程度，如下所示：
exporters:
logging:
verbosity: detailed
以下示例輸出顯示了使用記錄導出器進行追踪時可以預期的內容。
當您仍在設置您的收集管道時，日誌將是您最好的故障排除工具。它們可以直接在運行收集器實例的控制台上查看。
可以通過在配置文件的頂級service節點下更改telemetry設置來配置詳細程度，如下所示：
service:
telemetry:
logs:
level: debug
initial_fields:
service: my-instance
可以添加 initial_fields，以便收集器產生的每個日誌條目都包括它們。當將所有收集器的日誌發送到集中位置時，這很有用，可以識別哪個收集器產生了哪個日誌條目。
以下是使用上述配置的收集器產生的日誌條目的示例輸出：
2023-05-05T14:16:52.935-0300 info TracesExporter {"service": "my-instance", "kind": "exporter", "data_type": "traces", "name": "logging", "#spans": 2000}
可能的日誌級別有：debug、info、warn、error、dpanic、panic、fatal。級別遵循日誌庫 Zap 的語義。
除了已經提到的選項外，以下屬性可以用於進一步調整收集器的日誌記錄器的行為：
development，將日誌記錄器設置為開發模式，在出現問題時允許提供更詳細的反饋。當開發自己的組件時，這特別有用，但在設置管道時則不太有用。encoding，允許默認輸出格式嚴格為 json 或默認的控制台格式。disable_caller，禁用將調用者的位置添加到日誌條目。disable_stacktrace，禁用自動記錄堆棧追踪。sampling，為日誌指定一個取樣策略（見下文）。output_paths，指定寫入日誌條目的位置，其中stderr和stdout被解釋為輸出設備，而不是文本文件。error_output_paths，與上述相同，但專門用於錯誤消息。取樣配置可以包括以下選項：
initial，根據 Zap 的語義，這設置了在限流發生之前特定消息的每秒日誌條目的最大數量。計數器每秒重置。thereafter，也根據 Zap 的語義，當已經進行限流時，設置允許記錄的每秒條目數量。計數器每秒重置。以下是設置所有字段的示例：
service:
telemetry:
logs:
level: debug
initial_fields:
service: my-instance
development: true
encoding: json
disable_caller: true
disable_stacktrace: true
sampling:
initial: 10
thereafter: 5
output_paths:
- /var/log/otelcol.log
- stdout
error_output_paths:
- /var/log/otelcol.err
- stderr
收集器使用 OpenMetrics 格式在 localhost:8888/metrics 上公開其自己的指標，可以在生產管道上使用，以了解收集器及其組件的運行時行為。使用指標，您可以檢查接收器、處理器和導出器各自看到了多少數據點。參見「接收器問題」(https://grafana.com/docs/opentelemetry/collector/troubleshooting/#receiver-issues)和「導出器問題」(https://grafana.com/docs/opentelemetry/collector/troubleshooting/#exporter-issues)以獲得具體示例。
可以通過更改配置文件中的telemetry設置來配置詳細程度，如下所示，位於 service 頂級節點下：
service:
telemetry:
metrics:
level: detailed
以下級別可用：
none，告訴收集器不應收集任何指標。這實際上完全禁用了指標端點。basic，只有由組件作者認為是必要的指標。normal，用於常規使用的指標。detailed，具有現有指標的可能新指標或屬性。level屬性外，還可以使用address指定綁定指標端點的地址（host:port, 例如localhost:8888）。zpages
此擴展提供了幾個可在瀏覽器中查看的端點，提供有關收集器自身有效配置的洞察。例如，URL http://localhost:55679/debug/servicez 顯示收集器的版本、進程的開始時間以及配置的管道和啟用的擴展。
URL http://localhost:55679/debug/tracez 提供了收集器自己的跨度的簡單查看器，包括在預定延遲桶中的跨度數量。
OpenTelemetry Collector 專案有一個名為 telemetrygen 的工具，可以生成遙測數據以測試管道。請參考該工具的 readme 以獲取安裝說明。
當您有一個帶有 OTLP 接收器和啟用了 gRPC 協議的本地 OpenTelemetry Collector 時，您可以像這樣運行它：
telemetrygen traces --traces 1 --otlp-insecure
telemetrygen logs --logs 1 --otlp-insecure
telemetrygen metrics --metrics 1 --otlp-insecure
一個合適的 OpenTelemetry Collector 會像這樣：
receivers:
otlp:
protocols:
grpc:
exporters:
logging:
service:
pipelines:
traces:
receivers: [ otlp ]
processors:
exporters: [ logging ]
logs:
receivers: [ otlp ]
processors:
exporters: [ logging ]
metrics:
receivers: [ otlp ]
processors:
exporters: [ logging ]
在故障排除後，如果您懷疑 Collector 中存在錯誤，您可以採取以下選項：
loki 接收器和輸出器，請與 Grafana Labs 的支持開啟問題。otlp 接收器和輸出器、batch處理器、logging輸出器等），請對 OpenTelemetry Collector 核心存儲庫開啟問題。loadbalancer 輸出器、spanmetrics 處理器、tailsampling 處理器等），請對 OpenTelemetry Collector contrib 存儲庫開啟問題。我們也在 Grafana Labs 的 Community Slack 的 #opentelemetry 頻道上提供服務。
看影片追技術