小編精選 - 技術文章翻譯 · 09月12日

自訂 OpenTelemetry 收集器：大規模建置、運作和管理

我試著回想上次閱讀的實際教程中沒有包含一堆 em（—）破折號、分號、普通破折號以及大量令人不安的短語，例如“XYZ-thing Alert🚨”和“令人興奮的訊息！”。

好了，各位，抓緊你們的背帶褲，我們又來了。第二部分已經上線，而且還是一部頗具爭議的作品。 👇

你嘗試過建立自己的 OpenTelemetry Collector 發行版嗎？喜歡嗎？ 😂

我敢打賭你一定笑不出來。更別說像我現在這樣，因為這句話而放聲大笑了！我試過了，結果真的很難受。

我確實有一個不錯的解決方案，可以解決目前建立自訂 OpenTelemetry 收集器的常規問題，如果你有耐心堅持讀完接下來的 4 分鐘。我會盡力尊重你的時間，並將其精簡到你成功所需的最基本內容。 🤝

身為一個正常人，我覺得這很難…

現有資源和文件中關於使用 OpenTelemetry Collector Builder (OCB) 的一些步驟缺失了。我感覺自己就像在一片黑暗的森林中跌跌撞撞地前行，幾乎無法到達彼岸。 OCB 對 Go 開發者來說是一款非常棒的工具。不過，這才是關鍵。我們中的許多人並不是經驗豐富的工程師，更不用說經驗豐富的 Go 開發者了。

這就是我想寫這篇教學的原因。我將向你展示一份使用 Bindplane 開源OpenTelemetry Distribution Builder (ODB) 的實作指南。你將學習如何使用manifest.yaml檔案和 GitHub Actions 建立一個支援 OpAMP 的自訂收集器。

建立自訂 OpenTelemetry 收集器是切實的需求

自訂 OpenTelemetry 收集器已不再是小眾產品。隨著越來越多的開發者在複雜的 Kubernetes 環境、通用容器甚至邊緣環境中執行收集器，精簡二進位檔案正成為標準做法。

為什麼要建立自訂收集器？

上游OpenTelemetry Collector Contrib附帶了許多元件。這對於入門來說很棒，但在生產環境中，您不需要所有元件。簡而言之，元件越多，二進位檔案就越大，攻擊面也就越大。

自訂收集器解決了這個問題。你可以明確定義需要什麼：

僅限您使用的接收器、處理器、導出器和擴充程序
最少佔用空間
沒有不必要的依賴

OpenTelemetry 分發建構器 (ODB)

ODB是 Bindplane 用於建立自訂收集器的開源建構器。

您向它提供manifest.yaml ，它會為您提供所需的每個平台的二進位檔案和套件。

您將獲得：

多平台建置：Linux、Windows、macOS、AMD64、ARM64
多種格式：.tar.gz、.zip、.deb、.rpm
無需 Go 編碼，無需手動解決依賴關係
OpAMP 支援（開箱即用，相容於 Bindplane）

步驟 1 — 建立 GitHub 倉庫

首先建立一個空白的 GitHub 儲存庫來儲存manifest.yaml並執行 GitHub Action Workflows。

客製化飯店-col-1.png

接下來，在您的本機環境中建立一個新的 repo。

echo "# otel-distro-builder-github-action" >> README.md
git init
git add README.md
git commit -m "first commit"
git branch -M main
git remote add origin [email protected]:<YOUR_ACCOUNT_NAME>/otel-distro-builder-github-action.git
git push -u origin main

客製化飯店-col-2.png

倉庫現在可以增加manifest.yaml了。

客製化飯店-col-3.png

步驟 2 — 編寫`manifest.yaml`

manifest.yaml是您定義收集器中的內容的地方。

以下是我與 Bindplane 的同事（他們為 OpenTelemetry 專案做出了貢獻）共同審核過的建議範例。它非常精簡，但仍然包含了一些重要的模組，例如 OpAMP 支援和常用處理器。

dist:
  module: github.com/<YOUR-USERNAME>/my-custom-opentelemetry-distro
  name: my-custom-opentelemetry-distro
  description: Custom-built OpenTelemetry Collector.
  output_path: ./_build
  version: v0.0.1
conf_resolver:
  default_uri_scheme: "env"
receivers:
  - gomod: go.opentelemetry.io/collector/receiver/nopreceiver v0.128.0
  - gomod: go.opentelemetry.io/collector/receiver/otlpreceiver v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/receiver/hostmetricsreceiver v0.128.0
  - gomod: github.com/observiq/bindplane-otel-collector/receiver/telemetrygeneratorreceiver v1.79.0
exporters:
  - gomod: go.opentelemetry.io/collector/exporter/debugexporter v0.128.0
  - gomod: go.opentelemetry.io/collector/exporter/nopexporter v0.128.0
  - gomod: go.opentelemetry.io/collector/exporter/otlpexporter v0.128.0
  - gomod: go.opentelemetry.io/collector/exporter/otlphttpexporter v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/exporter/datadogexporter v0.128.0
  - gomod: github.com/observiq/bindplane-otel-collector/exporter/googlecloudstorageexporter v1.79.0
extensions:
  - gomod: go.opentelemetry.io/collector/extension/zpagesextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/ackextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/asapauthextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/awsproxy v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/basicauthextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/bearertokenauthextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding/jaegerencodingextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding/otlpencodingextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/encoding/zipkinencodingextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/headerssetterextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/healthcheckextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/httpforwarderextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/jaegerremotesampling v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/oauth2clientauthextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/observer/dockerobserver v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/observer/ecsobserver v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/observer/ecstaskobserver v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/observer/hostobserver v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/observer/k8sobserver v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/oidcauthextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/opampextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/pprofextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/sigv4authextension v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/storage/filestorage v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/extension/storage/dbstorage v0.128.0
  - gomod: github.com/observiq/bindplane-otel-collector/extension/bindplaneextension v1.79.0
processors:
  - gomod: go.opentelemetry.io/collector/processor/batchprocessor v0.128.0
  - gomod: go.opentelemetry.io/collector/processor/memorylimiterprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/attributesprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/cumulativetodeltaprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/deltatorateprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/filterprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/groupbyattrsprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/groupbytraceprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/k8sattributesprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/logdedupprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricsgenerationprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/metricstransformprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/probabilisticsamplerprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/redactionprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/remotetapprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/resourcedetectionprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/resourceprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/routingprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/spanprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/sumologicprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/tailsamplingprocessor v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/processor/transformprocessor v0.128.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/datapointcountprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/logcountprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/lookupprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/maskprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/metricextractprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/metricstatsprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/removeemptyvaluesprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/resourceattributetransposerprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/samplingprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/snapshotprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/spancountprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/throughputmeasurementprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/topologyprocessor v1.79.0
  - gomod: github.com/observiq/bindplane-otel-collector/processor/unrollprocessor v1.79.0
connectors:
  - gomod: go.opentelemetry.io/collector/connector/forwardconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/countconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/datadogconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/exceptionsconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/failoverconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/grafanacloudconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/roundrobinconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/routingconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/servicegraphconnector v0.128.0
  - gomod: github.com/open-telemetry/opentelemetry-collector-contrib/connector/spanmetricsconnector v0.128.0
providers:
  - gomod: go.opentelemetry.io/collector/confmap/provider/envprovider v1.34.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/fileprovider v1.34.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpprovider v1.34.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/httpsprovider v1.34.0
  - gomod: go.opentelemetry.io/collector/confmap/provider/yamlprovider v1.34.0
# When adding a replace, add a comment before it to document why it's needed and when it can be removed
replaces:
  # See https://github.com/google/gnostic/issues/262
  - github.com/googleapis/gnostic v0.5.6 => github.com/googleapis/gnostic v0.5.5
  # See https://github.com/open-telemetry/opentelemetry-collector-contrib/pull/12322#issuecomment-1185029670
  - github.com/docker/go-connections v0.4.1-0.20210727194412-58542c764a11 => github.com/docker/go-connections v0.4.0
  # see https://github.com/mattn/go-ieproxy/issues/45
  - github.com/mattn/go-ieproxy => github.com/mattn/go-ieproxy v0.0.1
  # see https://github.com/openshift/api/pull/1515
  - github.com/openshift/api => github.com/openshift/api v0.0.0-20230726162818-81f778f3b3ec
  - github.com/observiq/bindplane-otel-collector/internal/version => github.com/observiq/bindplane-otel-collector/internal/version v0.0.0-20250306153219-6fe3f849c29f

💡 opampextension是關鍵——它讓 Bindplane 發現並管理您的收集器。

步驟 3 — 使用 GitHub Actions 自動建置

使用**OpenTelemetry Distribution Builder GitHub Action **來完成繁重的工作。

這裡有一個你可以放入的.github/workflows/multi.yaml ：

name: Matrixed OpenTelemetry Distribution Build

on:
  push:
    tags:
      - "v*" # Runs when a version tag is pushed (e.g., v1.0.0)
  workflow_dispatch: # Enables manual triggering from the GitHub UI

permissions:
  contents: write # This is required for creating/modifying releases

jobs:
  build:
    # Configure build matrix to run multiple platform builds in parallel
    strategy:
      matrix:
        # Define the platforms we want to build for
        platform: [linux/amd64, linux/arm64, darwin/arm64, windows/amd64]
        # Map platform identifiers to simpler names for artifact handling
        include:
          - platform: linux/amd64
            os: linux
            arch: amd64
            artifact_name: linux-amd64
          - platform: linux/arm64
            os: linux
            arch: arm64
            artifact_name: linux-arm64
          - platform: darwin/arm64
            os: darwin
            arch: arm64
            artifact_name: darwin-arm64

          - platform: windows/amd64
            os: windows
            arch: amd64
            artifact_name: windows-amd64
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # Build the OpenTelemetry distribution for each platform
      - name: Build and Package
        uses: observiq/otel-distro-builder@main
        with:
          os: ${{ matrix.os }}
          arch: ${{ matrix.arch }}

      # Upload platform-specific artifacts with a unique name
      # These artifacts are available for download in the GitHub Actions UI
      - name: Upload Artifacts
        uses: actions/upload-artifact@v4
        with:
          name: distribution-artifacts-${{ matrix.artifact_name }}
          path: |
            ${{ startsWith(matrix.platform, 'linux') && format('{0}/artifacts/*.deb', github.workspace) || '' }}
            ${{ startsWith(matrix.platform, 'linux') && format('{0}/artifacts/*.rpm', github.workspace) || '' }}
            ${{ startsWith(matrix.platform, 'linux') && format('{0}/artifacts/*.apk', github.workspace) || '' }}
            ${{ startsWith(matrix.platform, 'windows') && format('{0}/artifacts/*.zip', github.workspace) || '' }}
            ${{ (startsWith(matrix.platform, 'linux') || startsWith(matrix.platform, 'darwin')) && format('{0}/artifacts/*.tar.gz', github.workspace) || '' }}
            ${{ format('{0}/artifacts/*.sbom.json', github.workspace) || '' }}
            ${{ format('{0}/artifacts/*_checksums.txt', github.workspace) || '' }}
          retention-days: 5 # Artifacts are kept for 5 days then automatically deleted

  # Create a single release containing all platform artifacts
  release:
    needs: build # Wait for all platform builds to complete
    runs-on: ubuntu-latest
    permissions:
      contents: write # Required permission for creating releases
    steps:
      # Download all platform-specific artifacts into a single directory
      - name: Download All Artifacts
        uses: actions/download-artifact@v4
        with:
          path: all-artifacts
          pattern: distribution-artifacts-* # Match all our platform-specific artifacts
          merge-multiple: true # Combine all artifacts into a single directory

      # Create a GitHub Release and attach all platform artifacts
      # This makes all platform builds available for download from the Releases page
      - name: Create Release
        uses: softprops/action-gh-release@v2
        with:
          files: all-artifacts/**/*

每個新版本發布都會：

為所有平台建立自訂收集器
將其打包成.tar.gz、.zip、.deb 和 .rpm
將它們儲存為 GitHub Actions 工件

您應該已經建立了兩個文件並準備加入到 Git。

git status

[Output]
On branch main
Your branch is up to date with 'origin/main'.

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    .github/
    manifest.yaml

提交這些變更並將其推送到您的 repo。

git add .github manifest.yaml
git commit -m "add a manifest and workflow"
git push origin main

客製化飯店-col-4.png

建立新的版本。請確保使用與manifest.yaml中指定的版本標籤相同的版本標籤。在上面的範例manifest.yaml中，我使用了v0.0.1 ，這意味著我需要在版本中設定相同的標籤。

客製化飯店-col-5.png

一旦建立了發布，您就會看到它最初是空的。

客製化飯店-col-5-5.png

開啟Actions將顯示建置正在執行。

客製化飯店-col-6.png

大約5分鐘完成。去喝杯咖啡吧。 ☕

客製化飯店-col-7.png

建置完成後，您將看到已儲存並新增至發布中的工件。

客製化飯店-col-9.png

步驟 4 — 下載並執行收集器

讓我示範如何在 Linux 虛擬機器中執行自訂收集器。從發布版本中獲取一個工件並將其提取出來。

wget https://github.com/adnanrahic/otel-distro-builder-github-action/releases/download/v0.0.1/my-custom-opentelemetry-distro_otelcol_v0.0.1_linux_amd64.tar.gz

tar -xvzf my-custom-opentelemetry-distro_otelcol_v0.0.1_linux_amd64.tar.gz

您還將獲得捆綁在 tar 中的自訂收集器的骨架collector_config.yaml 。

ls -l

[Condensed Output]
-rw-r--r-- collector_config.yaml
-rwxr-xr-x my-custom-opentelemetry-distro
-rw-r--r-- my-custom-opentelemetry-distro_otelcol_v0.0.1_linux_amd64.tar.gz
drwxr-xr-x service

讓我們稍微編輯一下，並按照本指南加入 Bindplane 的 OpAMP 配置。將其貼到設定檔中。

# To limit exposure to denial of service attacks, change the host in endpoints below from 0.0.0.0 to a specific network interface.
# See https://github.com/open-telemetry/opentelemetry-collector/blob/main/docs/security-best-practices.md#safeguards-against-denial-of-service-attacks

extensions:
  health_check:
  pprof:
    endpoint: 0.0.0.0:1777
  zpages:
    endpoint: 0.0.0.0:55679

    # Add an OpAMP connection to Bindplane.
    # Use the credentials from your account, and
    # follow the guide from the screenshot below.
  opamp:
    instance_uid: 01K42T4MGFFDZMXBY7C5C2APX9 # Generated ULID
    capabilities:
      reports_effective_config: true
    server:
      ws:
          # Bindplane Cloud OpAMP Endpoint
        endpoint: wss://app.bindplane.com/v1/opamp
        headers:
          Authorization: Secret-Key <YOUR_SECRET_KEY> 
          X-Bindplane-Labels: <YOUR_LABEL=YOUR_VALUE>
        tls:
          insecure: false

receivers:
  telemetrygeneratorreceiver/logs:
    generators:
      - additional_config:
          body: 'foo: bar'
          severity: 9
        type: logs
    payloads_per_second: 1

  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

processors:
  batch:

exporters:
  debug:
    verbosity: detailed
  nop: null

service:

  pipelines:

    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug, nop]

    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [debug, nop]

    logs:
      receivers: [telemetrygeneratorreceiver/logs, otlp]
      processors: [batch]
      exporters: [debug, nop]

  extensions: [health_check, pprof, zpages, opamp]

注意：如果您使用的是 Bindplane 的 Growth 或 Enterprise 計劃，並且想要連接 Bindplane 收集器，請使用-s後的密鑰和-k後的標籤。無論是否連接到 Bindplane，收集器都能正常運作。但是，您將無法獲得 OpAMP 的管理功能和優勢。

現在，繼續執行收集器二進位。

./my-custom-opentelemetry-distro --config collector_config.yaml

您將看到類似這樣的日誌，作為終端輸出，確認telemetrygeneratorreceiver正在建立一些虛擬日誌來驗證您的設定是否正常運作。

2025-09-02T08:44:44.255Z    info    [email protected]/service.go:282 Everything is ready. Begin running and processing data. {"resource": {"service.instance.id": "8c4d008a-700d-49d6-b6ed-41cd1e03cf18", "service.name": "my-custom-opentelemetry-distro", "service.version": "v0.0.1"}}

2025-09-02T08:44:44.454Z    info    Logs    {"resource": {"service.instance.id": "8c4d008a-700d-49d6-b6ed-41cd1e03cf18", "service.name": "my-custom-opentelemetry-distro", "service.version": "v0.0.1"}, "otelcol.component.id": "debug", "otelcol.component.kind": "exporter", "otelcol.signal": "logs", "resource logs": 1, "log records": 1}

2025-09-02T08:44:44.455Z    info    ResourceLog #0
Resource SchemaURL: 
ScopeLogs #0
ScopeLogs SchemaURL: 
InstrumentationScope  
LogRecord #0
ObservedTimestamp: 2025-09-02 08:44:44.253813518 +0000 UTC
Timestamp: 2025-09-02 08:44:44.253813518 +0000 UTC
SeverityText: 
SeverityNumber: Info(9)
Body: Str(foo: bar)
Trace ID: 
Span ID: 
Flags: 0

幾秒鐘內，您的自訂收集器將出現在Bindplane 的代理程式清單中。

客製化飯店-col-12.png

您也可以開啟收集器配置。

客製化飯店-col-13.png

Bindplane 正在取得收集器元資料以及您新增的設定。 OpAMP 擴充功能目前不支援遠端配置，這表示您無法透過 Bindplane 介面修改收集器配置。您仍然可以在收集器頁面上以 YAML 格式查看目前的收集器配置，但「選擇其他配置」按鈕將無法使用。

讓我引導您將自訂收集器新增至 Bindplane 並啟用遠端設定。

步驟 5 — 使用 OpAMP 遠端管理您的自訂收集器

您可以按照本文件指南中的說明，在 Bindplane 中新增自訂收集器作為代理類型，從而啟用遠端收集器管理。讓我一步步指導您。 🚶‍♀️

1.安裝Bindplane CLI

Bindplane CLI 可讓您管理 Bindplane 資源，包括代理類型。請依照此處的特定作業系統安裝步驟進行操作。

2. 建立 API 金鑰並設定`default`文件

建立 API 金鑰，以便使用 CLI 存取 Bindplane 中的資源。請依照此處的步驟操作。

3. 在 Bindplane 中建立代理程式類型

在 Bindplane 中，一個 Agent 類型代表一個 OpenTelemetry 收集器分佈。例如，BDOT v1 和 v2 收集器都屬於 Agent 類型。

apiVersion: bindplane.observiq.com/v1
kind: AgentType
metadata:
  name: my-custom-opentelemetry-distro
  displayName: My Custom OpenTelemetry Distro
  description: My custom OpenTelemetry collector distro.
spec:
  repositoryLink: https://github.com/<YOUR_GITHUB_USERNAME>/<YOUR_REPO_NAME>
  platformArchSet:
    - platform: darwin
      arch: arm64
    - platform: linux
      arch: amd64
    - platform: linux
      arch: arm64
    - platform: windows
      arch: amd64

這一點需要注意。 repositoryLink 需要與你執行 GitHub 作業的倉庫連結一致。在我的例子中repositoryLink它是：

https://github.com/adnanrahic/otel-distro-builder-github-action

客製化飯店-col-15.png

metadata.name值也需要與manifest.yaml中的dist.name值相符。

應用自訂代理類型。

bindplane apply -f /path/to/agent/type/file.yaml

最後，同步代理類型以將其載入到 Bindplane 中。

bindplane sync agent-versions --agent-type my-custom-opentelemetry-distro --version v0.0.1

請注意版本與發行版相符。

5. 從 Bindplane UI 安裝自訂收集器

現在，由於您已經新增了自訂代理程式類型並同步了版本，您可以選擇從 Bindplane UI 安裝它。

客製化飯店-col-14.png

由於您為 Mac、Windows 和 Linux 建立了它，因此在選擇平台時您將看到所有三個選項。

客製化飯店-col-18.png

我想將它安裝在我的 Linux VM 中，因此我將選擇 Linux 並點擊下一步。

客製化飯店-col-17.png

我將獲取這個通用的安裝單命令。在我的虛擬機器中執行它，將啟動我的自訂收集器，並透過 OpAMP 將其連接到 Bindplane。

sudo sh -c "$(curl -fsSlL 'https://raw.githubusercontent.com/observIQ/bindplane-otel-collector/refs/heads/main/scripts/generic-install/install_unix.sh')" install_unix.sh -d 'my-custom-opentelemetry-distro' -u 'https://github.com/adnanrahic/otel-distro-builder-github-action' -e 'wss://app.bindplane.com/v1/opamp' -s '01J06XSD7FVM3CHCQA3823AC2X' -v '0.0.1' -l 'install_id=937a3445-8962-441a-90f0-ee120c67edb7'

[Output]
Using repository URL: https://github.com/adnanrahic/otel-distro-builder-github-action
Auto-detected package type: deb
Downloading: https://github.com/adnanrahic/otel-distro-builder-github-action/releases/download/v0.0.1/my-custom-opentelemetry-distro_v0.0.1_linux_amd64.deb
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
100 46.9M  100 46.9M    0     0  38.4M      0  0:00:01  0:00:01 --:--:-- 98.4M
Selecting previously unselected package my-custom-opentelemetry-distro.
(Reading database ... 76875 files and directories currently installed.)
Preparing to unpack .../my-custom-opentelemetry-distro_0.0.1.deb ...
Unpacking my-custom-opentelemetry-distro (0.0.1) ...
Setting up my-custom-opentelemetry-distro (0.0.1) ...
Created symlink /etc/systemd/system/multi-user.target.wants/my-custom-opentelemetry-distro.service → /lib/systemd/system/my-custom-opentelemetry-distro.service.
Creating supervisor config...
Managing service state...
Starting my-custom-opentelemetry-distro service...
Service is running
Installation complete!
Installation directory: /opt/my-custom-opentelemetry-distro
Supervisor config: /opt/my-custom-opentelemetry-distro/supervisor_config.yaml

這將把收集器作為systemd服務啟動。

sudo systemctl status my-custom-opentelemetry-distro

[Output]
● my-custom-opentelemetry-distro.service - An OpenTelemetry Collector service named 'my-custom-opentelemetry-distro'.
     Loaded: loaded (/lib/systemd/system/my-custom-opentelemetry-distro.service; enabled; preset: enabled)
     Active: active (running) since Tue 2025-09-02 12:36:56 UTC; 2min 51s ago
   Main PID: 17005 (supervisor)
      Tasks: 7 (limit: 4681)
     Memory: 8.5M
        CPU: 249ms
     CGroup: /system.slice/my-custom-opentelemetry-distro.service
             └─17005 /opt/my-custom-opentelemetry-distro/supervisor --config=/opt/my-custom-opentelemetry-distro/supervisor_config.yaml

Sep 02 12:36:56 my-custom-opentelemetry-distro systemd[1]: Started my-custom-opentelemetry-distro.service - An OpenTelemetry Collector service named 'my-opentelemetry-distro.service - An OpenTelemetry Collector service named 'my-custom-opentelemetry-distro'.

由於 OpAMP 連線透過 websockets 運作，它會立即更新 UI 並顯示正在執行的收集器。

客製化飯店-col-20.png

6. 從 Bindplane UI 設定和管理您的自訂收集器

現在您可以為收集器建立一個配置並將其遠端推送下去。

客製化飯店-col-21.png

按一下Create Configuration按鈕可在 Bindplane 中建立和管理配置並遠端套用它。

客製化飯店-col-22.png

為其命名，選擇自訂收集器的代理類型，並選擇執行該自訂收集器的平台。在本例中，平台是 Linux。新增遙測生成器來源。

客製化飯店-col-23.png

並且，一個 Dev Null 目的地。

客製化飯店-col-24.png

這將完成您的配置建立。您仍然需要將其連接到您的自訂收集器。

客製化飯店-col-25.png

點擊Add Agents按鈕。選擇您的自訂收集器，然後點擊「儲存」。

客製化飯店-col-26.png

現在，您可以開始部署以遠端套用配置。

客製化飯店-col-27.png

這裡令人驚嘆的是，Bindplane 直接從建置中讀取收集器的功能，因此您只能看到清單中實際包含的元件。

讓我透過新增來源來向您展示。

客製化飯店-col-28.png

您將看到哪些來源不相容，哪些可以使用。這將大大提升整個團隊在建立和管理收集器配置時的生活品質和便利性。

第 6 步 — 充滿信心地進行迭代

透過此設定您可以：

更新manifest.yaml以新增或移除模組
建立新版本
GitHub Actions 建置新版本
在您的環境中部署或升級
Bindplane 即時管理更新的代理

您現在擁有一個BYOC（自備收集器）工作流程—完全自動化、版本化且由您控制。

為什麼這種方法如此有效

|特點|價值|

| --- | --- |

| 開箱即用的 OpAMP | 完整的 Bindplane 遠端設定與監控 |

| 宣告式清單 | 無需 Go 程式碼，無需手動依賴解析 |

| GitHub 原生 CI/CD | 推播 → 建置 → 打包 → 管理 |

| 多平台打包 | 一次建置，隨處執行 |

| UI 感知 Bindplane 整合 | 僅顯示支援的元件 |

未來目標

展望未來，我也想將manifest.yaml檔案抽像出來。理想情況下，我希望為 OpenTelemetry Distro Builder 提供一個範例收集器設定檔。這樣它就能根據我的配置建立一個manifest.yaml檔案。這個過程會抽象化除了我真正需要的特定接收器、導出器、擴充功能和處理器之外的所有內容。

年底前會有更多相關資訊。 😉