HyperDX 自建 OTel Collector 完全指南OCB 定制编译、Datadog/StatsD 接入与 OpAMP 运维【免费下载链接】hyperdxResolve production issues, fast. An open source observability platform unifying session replays, logs, metrics, traces and errors powered by ClickHouse and OpenTelemetry.项目地址: https://gitcode.com/gh_mirrors/hy/hyperdx本文以 packages/otel-collector/README.md 为主体结合仓库内 Dockerfile、OCB 构建清单、OpAMP 控制器与 ClickHouse 迁移工具等源码系统讲解 HyperDX 如何用 OCB 定制编译 OpenTelemetry Collector以及在此自建 Collector 上如何接入 Datadog Agent、计算 span 派生指标、接入 StatsD 数据、通过CUSTOM_OTELCOL_CONFIG_FILE覆盖基座组件、升级 Collector 版本并扩展自定义组件。读完你将掌握 HyperDX 数据摄取链路从二进制构建到管道配置的完整脉络并能独立完成常用接入与调优。一、为什么 HyperDX 要自建 OTel CollectorHyperDX 是一个基于 ClickHouse 与 OpenTelemetry 的开源可观测性平台统一处理 session replay、日志、指标、trace 与错误数据。官方预构建的otel/opentelemetry-collector-contrib镜像体积大、组件冗余且无法加入 HyperDX 私有组件。为此HyperDX 通过OCBOpenTelemetry Collector Builder编译自己的 Collector 二进制只包含平台需要的组件 常用 core/contrib 组件 本仓库内自定义的 receiver/processor见 packages/otel-collector/builder-config.yaml。从源码结构看这套自建方案带来三个直接收益二进制更精简builder-config.yaml显式声明组件清单构建产物名为otelcol-hyperdx见 docker/otel-collector/Dockerfile 中的output_path与name配置可内置私有组件未来任何 HyperDX 自定义 receiver/processor 都能随 OCB 清单一起编译进二进制版本可控contrib 组件版本与 core confmap provider 版本分离管理便于跟随上游升级。二、架构与构建流程2.1 多阶段构建Collector 二进制在docker build阶段通过多阶段 Dockerfile 构建核心链路见 docker/otel-collector/Dockerfile从官方otel/opentelemetry-collector-builder:version镜像拷贝ocb二进制ocb-bin阶段将ocb放入golang:version-alpine基座ocb-builder阶段——官方 OCB 镜像可能携带比 contrib 模块要求的更老的 Go 工具链因此需要换成更新的 Go 环境用sed替换builder-config.yaml中的版本占位符__OTEL_COLLECTOR_VERSION__与__OTEL_COLLECTOR_CORE_VERSION__ocb依据解析后的 manifest 编译出自定义二进制/build/output/otelcol-hyperdx。构建命令示例注意构建上下文必须是仓库根目录docker build -f docker/otel-collector/Dockerfile .2.2 关键文件文件作用packages/otel-collector/builder-config.yamlOCB 清单声明要编译进二进制的所有组件使用__OTEL_COLLECTOR_VERSION__与__OTEL_COLLECTOR_CORE_VERSION__占位符构建时经sed替换packages/otel-collector/cmd/migrate/main.go基于 goose 的 Go 版 ClickHouse 迁移工具支持完整 TLSCA 证书、客户端证书、ServerName 覆盖、InsecureSkipVerifySeed SQL 每次运行都会重新执行因此必须幂等如CREATE TABLE IF NOT EXISTSpackages/otel-collector/go.mod /go.sum迁移工具独立的 Go module迁移工具支持的 TTL 环境变量见 cmd/migrate/main.go 的loadConfig也值得留意HYPERDX_OTEL_EXPORTER_TABLES_TTL默认720h、HYPERDX_OTEL_EXPORTER_LOGS_TTL、HYPERDX_OTEL_EXPORTER_TRACES_TTL、HYPERDX_OTEL_EXPORTER_METRICS_TTL、HYPERDX_OTEL_EXPORTER_SESSIONS_TTL各信号 TTL 会回退到TablesTTLHYPERDX_OTEL_EXPORTER_RECONCILE_TABLE_TTL控制是否对已存在的表也校准 TTL。2.3 哪些 Dockerfile 使用这个 CollectorDockerfile说明docker/otel-collector/Dockerfile独立 Collector 镜像dev与prod两个 targetENTRYPOINT为/entrypoint.sh /opampsupervisordocker/hyperdx/DockerfileAll-in-one 镜像包含 Collector、ClickHouse、MongoDB、API、App2.4 版本配置Collector 版本由两个变量控制定义在根目录.env并通过 Docker build arg 传入OTEL_COLLECTOR_VERSIONcontrib/core 组件版本例如0.149.0当前 Dockerfile 默认0.155.0OTEL_COLLECTOR_CORE_VERSIONcore confmap provider 版本例如1.55.0当前 Dockerfile 默认1.61.0。两个 Dockerfile 都带有同名ARG默认值作为独立构建时的兜底见 docker/otel-collector/Dockerfile 顶部。三、内置组件全景builder-config.yaml声明的组件分为两类HyperDX 内部使用的组件标注了具体用在哪份配置/哪个控制器中以及用户配置可用的组件user configs——后者是为了让用户在不重新编译 Collector 的前提下也能在自定义 OTel 配置中引用这些组件。3.1 Receivers组件模块使用位置nopcoreOpAMP 控制器otlpcorestandalone 配置、OpAMP 控制器、冒烟测试datadogcontribOpAMP 控制器通过ENABLE_DATADOG_RECEIVER可选开启dockerstatscontrib用户配置filelogcontrib用户配置fluentforwardcontribstandalone 配置、OpAMP 控制器、冒烟测试hostmetricscontribcustom.config.yamlk8sclustercontrib用户配置kubeletstatscontrib用户配置prometheuscontribOpAMP 控制器、冒烟测试statsdcontrib用户配置3.2 Processors组件模块使用位置batchcoreconfig.yaml、standalone 配置、OpAMP 控制器memory_limitercoreconfig.yaml、standalone 配置、OpAMP 控制器attributescontrib用户配置cumulativetodeltacontrib用户配置filtercontrib用户配置groupbyattrscontrib用户配置k8sattributescontrib用户配置logdedupcontrib用户配置metricstransformcontrib用户配置probabilisticsamplercontrib用户配置redactioncontrib用户配置resourcedetectioncontribconfig.yamldetectors 为env、system、dockerresourcecontrib用户配置spancontrib用户配置tailsamplingcontrib用户配置transformcontribconfig.yaml、standalone 配置、OpAMP 控制器3.3 Exporters组件模块使用位置clickhousecontribstandalone 配置、OpAMP 控制器debugcoreOpAMP 控制器nopcoreOpAMP 控制器otlpcore工具性包含otlphttpcorecustom.config.yaml3.4 Connectors组件模块使用位置forwardcore工具性包含routingcontribstandalone 配置、OpAMP 控制器span_metricscontrib用户配置3.5 Extensions组件模块使用位置memorylimitercore用户配置zpagescore用户配置bearertokenauthcontribstandalone-auth 配置、OpAMP 控制器file_storagecontribOpAMP 控制器sending queue 存储health_checkcontribconfig.yamlendpoint:13133、standalone-auth 配置opampcontribOpAMP supervisor 使用pprofcontrib调试/性能分析3.6 Confmap Providersenv、file、http、https、yaml五个 provider 全部来自 core 模块v__OTEL_COLLECTOR_CORE_VERSION__这意味着 Collector 配置可以引用环境变量${env:...}、本地/远程文件与 YAML 片段这也是后续CUSTOM_OTELCOL_CONFIG_FILE与effective.yaml机制的基础。四、接入 Datadogtraces / metrics / logs 三信号齐收4.1 原理datadogreceivercontrib 组件已编译进二进制因此 Datadog Agent 可以直接把traces、metrics 和 logs发给 HyperDX。该 receiver 在:8126上运行一个 HTTP 服务同时承担 Datadog intake API 的三种信号并将其翻译为 OTLP随后流入现有的traces、metrics、logs管道进入 ClickHouse。它是可选开启的OpAMP supervisor 模式在 API/OpAMP 进程上设置ENABLE_DATADOG_RECEIVERtrue。buildOtelCollectorConfig()随后会输出datadogreceiver监听0.0.0.0:8126read_timeout: 60s并挂到traces、metrics、logs/in三个管道上——这段逻辑可以直接在 packages/api/src/opamp/controllers/opampController.ts 的buildOtelCollectorConfig中看到。standalone 模式在 Collector 配置中增加datadogreceiver 块并把datadog加入traces、metrics、logs/in管道的receivers。把 Datadog Agent 指向 Collector 的:8126端点即可例如 traces 用DD_APM_DD_URL、metrics 用DD_DD_URLlogs 通过 Agent 的 logs endpoint 配置。4.2 认证在 OpAMP supervisor 模式下当强制 Collector 认证时datadogreceiver 会与otlp/hyperdx一样用团队的 ingestion API key 做认证读取的请求头是DD-API-KEY。实现上是通过bearertokenauth/datadog扩展完成的源码见 opampController.tsotelCollectorConfig.extensions[bearertokenauth/datadog] { header: DD-API-KEY, scheme: , tokens: apiKeys, };因此只需把 Datadog Agent 的DD_API_KEY设为 HyperDX 团队 ingestion API key。对应行为在 packages/api/src/opamp/controllers/tests/opampController.test.ts 中有完整单测覆盖flag 关闭时不输出 receiver开启但无 API key 或未强制认证时不附加认证开启且认证条件满足时通过DD-API-KEY认证。五、从 ingested traces 计算 span 指标RED5.1 动机与机制spanmetricsconnector被编译进二进制因此 Collector 可以直接从摄入的 trace 计算 span 派生的 RED 指标调用次数、时延直方图。它直接配合otlp/hyperdx工作但与datadogreceiver搭配最有用——因为 Datadog Agent 的 trace 目前与其他 trace 源一样RED 指标是在查询时从 traces 表实时计算的见 packages/app/src/serviceDashboard.ts 的getExpressions。这个 connector 在 Collector 侧预先计算一次而不是每次查询都算并且会生成 HyperDX ClickHouse schema 已有专用表的指数直方图时延序列otel_metrics_exponential_histogram。配置键名为span_metrics模块仍叫spanmetricsconnectorspanmetrics作为弃用别名仍然可用但新配置应使用当前名称。5.2 一个关键陷阱connector 必须声明两处Connector 必须同时出现在顶层connectors:块和某个管道的receivers/exporters引用中。只声明引用会导致校验失败service::pipelines::traces: references exporter span_metrics which is not configured因为 connector 从未被实例化。5.3 五个推荐字段超出最小配置除最小配置外文档中的示例还设置了五个字段每个都有明确的工程理由aggregation_temporality: AGGREGATION_TEMPORALITY_DELTA——connector 默认是 cumulative与下方的series_expiration/aggregation_cardinality_limit组合不兼容series 过期会删除其累加器下一个同 serviceoperation 的 span 会从 1 重新开始calls计数。而 HyperDX 的累计速率 SQLpackages/common-utils/src/core/renderChartConfig.ts 中的greatest(Value - lagInFrame(Value), 0)不会特殊处理重置会直接把负/零增量钳制掉继续走。对长时间安静的 series每个发射值都停留在1每次 diff 都是0traces.span.metrics.calls的increase图会显示恒零而端点其实一直在服务流量。Delta temporality 直接透传Value不做 diff同一文件AggregationTemporality 1分支完全不受此问题影响。namespace: traces.span.metrics——这已是 connector 的默认值v0.155.0 的DefaultNamespace显式设置是为了让本地配置中产出的指标名traces.span.metrics.calls/.duration稳定且一目了然即使未来版本改变默认值也不受影响。histogram.exponential.max_size: 160——不设置的话connector 默认产出的是显式桶explicit-bucket时延直方图otel_metrics_histogram而不是 HyperDX ClickHouse schema 已有专用表的指数直方图otel_metrics_exponential_histogram。这个字段才是真正让你落进专用表的开关。aggregation_cardinality_limit——spanmetrics默认无界聚合其内存维度 map 是独立于管道数据流的独立状态memory_limiter保护不到它那只是在管道边界拒绝进入的数据。在 Datadog firehose 这类高基数源上高基数的 span 名会把 map 撑大直到 Collector OOM。必须显式设上限。series_expiration——与上限配对使用没有它上限只是改变了何时开始疼因为 connector 默认从不过期任何东西。注意要设的是series_expiration而非metrics_expiration——它们是两个不同的字段都是真实存在、默认都是永不metrics_expiration只在某个 serviceoperation 长时间没有 span 时才整体退役其 metric 对象而series_expiration会从基数受限的 map 中逐出过期的单个维度组合而同一 metric 下的其他 series 保持活跃。基数突发填满 map 的是单个维度组合而非整个 metric所以series_expiration才是真正能腾出空间给新 series 的那个。5.4 Standalone 模式配置示例standalone 模式下traces/metrics是自有配置文件中的普通管道可以直接把span_metrics加进去。它们已经继承了基座 docker/otel-collector/config.yaml 的processors: [memory_limiter, batch]基座配置先加载无需额外添加。注意 confmap 会整体替换而非追加管道的receivers:/exporters:列表所以 Datadog trace 数据要到达span_metrics必须把datadog重新列在traces: receivers:上——它是traces管道上的 receiverspan_metrics在那里作为 exporter 消费它。如果把datadog只放在metrics: receivers:用于 Datadog 原生指标摄取对 span 派生指标毫无帮助。下面的示例故意不在 trace 侧加datadog无条件引用会破坏没配置它的用户的整个配置references receiver datadog which is not configured会让整个配置失败而非仅该管道。两种场景无法用一份拷贝粘贴的块同时满足使用前请先确认自己属于哪种connectors: span_metrics: namespace: traces.span.metrics aggregation_temporality: AGGREGATION_TEMPORALITY_DELTA histogram: exponential: max_size: 160 aggregation_cardinality_limit: 10000 series_expiration: 5m service: pipelines: traces: # 如果按上面 Datadog 章节配置了 datadog请在此处也加上——这个列表 # 会整体替换基座列表而非追加。 receivers: [otlp/hyperdx] exporters: [clickhouse, span_metrics] metrics: receivers: [otlp/hyperdx, span_metrics]5.5 OpAMP supervisor 模式用独立管道名OpAMP supervisor 模式下直接编辑默认的traces/metrics管道不会生效——这些管道上的receivers:/exporters:由 opampController.ts 动态设置远程配置会覆盖而非合并这些键。从CUSTOM_OTELCOL_CONFIG_FILE往traces/metrics里加span_metrics会被静默丢弃——不报错connector 只是编译进二进制但没接到任何管道。应该改用远程配置从不碰的独立管道名。与 standalone 不同这些是全新管道名、没有任何可继承内容所以processors:必须显式声明——但traces/spanmetrics只需要memory_limiter不要加batch它的唯一 exporter 是 connector 本身而非网络调用对已经在traces里 batch 过的 span 再做一次 batch 只会增加延迟最多 batch timeout和内存没有任何导出收益。batch在metrics/spanmetrics上才名副其实因为它确实要导出到 ClickHouseconnectors: span_metrics: namespace: traces.span.metrics aggregation_temporality: AGGREGATION_TEMPORALITY_DELTA histogram: exponential: max_size: 160 aggregation_cardinality_limit: 10000 series_expiration: 5m service: pipelines: traces/spanmetrics: # 如果通过任何方式定义了 datadog receiverENABLE_DATADOG_RECEIVERtrue # 或通过 CUSTOM_OTELCOL_CONFIG_FILE 自定义请在这里也加上——未定义的 # receiver 会让整个配置失败所有管道都失败不止这一个。 receivers: [otlp/hyperdx] exporters: [span_metrics] processors: [memory_limiter] metrics/spanmetrics: receivers: [span_metrics] exporters: [clickhouse] processors: [memory_limiter, batch]两种形态都通过真实编译出的二进制用otelcontribcol validate --config验证过包括文中标注的两种失败模式和每个 connector 字段。standalone 形态还实际运行过otelcontribcol --config ...而非仅validate日志到达Everything is ready. Begin running and processing data.并启动了span_metricsconnector证明validate的静态 schema/图校验没有隐藏只在启动期才暴露的失败。六、接入 StatsD 指标6.1 能力与边界statsdreceiver已编译进二进制因此可以直接摄入 StatsD 格式的指标无需单独的 StatsD→OTLP 桥接——它覆盖任何 StatsD 客户端不限于特定厂商的方言。它还理解 DogStatsD 标签扩展带值的标签#tag:value无需额外配置即可工作但裸标签#mytag无值需要enable_simple_tags: true下方已设置否则会被静默丢弃。重要限制该组件不支持水平扩展部署——这不是 HyperDX 特有的限制上游组件文档本身就这么说。聚合状态独立存在于每个 Collector 实例的内存中没有跨副本协调因此同一指标落在两个不同副本如负载均衡 Service 后面会被各自独立聚合而非合并造成静默拆分/少计。HyperDX 的默认部署docker-compose.yml、all-in-one 镜像中 OpAMP 管理的 Collector 是单实例所以开箱即用不会踩坑只有当某个摄取statsd的 Collector 实例扩展到多副本时才需要处理届时该流量应指向一个专用单副本实例。6.2 端口与开关docker-compose.yml 和 docker-compose.dev.yml 中otel-collector服务带有8125/udp端口映射默认被注释掉——取消注释即可启用 statsd 摄取。之所以默认关闭是因为固定的宿主机端口映射在宿主机上已有其他进程占用 8125/udp如本地 StatsD 守护进程或 Datadog Agent时会导致该服务整体启动失败从而破坏不使用该功能的默认栈。standalone/all-in-one 镜像还EXPOSE 8125/udp仅元数据不会自行占用宿主机端口。6.3 Standalone 模式配置standalone 模式下metrics是自有配置文件中的普通管道直接加statsd即可receivers: statsd: # 默认是 localhost:8125只接受本机流量——这里必须用 0.0.0.0 # 因为流量来自容器外部上面发布的端口会把流量转发到容器自身的 # loopback否则无法到达。 endpoint: 0.0.0.0:8125 enable_simple_tags: true service: pipelines: metrics: receivers: [otlp/hyperdx, statsd]6.4 OpAMP supervisor 模式独立管道名OpAMP supervisor 模式HyperDX 默认下这样改metrics管道不会生效receivers:/exporters:由opampController.ts动态设置远程配置覆盖而非合并这些键与上一节 span metrics 行为一致。从CUSTOM_OTELCOL_CONFIG_FILE往metrics.receivers里加statsd会被静默丢弃不报错receiver 启动了但没接到任何管道。改用远程配置从不碰的独立管道名receivers: statsd: endpoint: 0.0.0.0:8125 enable_simple_tags: true service: pipelines: metrics/statsd: receivers: [statsd] exporters: [clickhouse] processors: [memory_limiter, batch]两种形态都通过真实二进制的otelcontribcol validate --config验证standalone 形态同样实际运行过otelcontribcol --config ...到达Everything is ready. Begin running and processing data.——与上一节 span metrics 同等严谨且使用容器实际使用的多--config合并方式。七、通过CUSTOM_OTELCOL_CONFIG_FILE覆盖基座组件7.1 为什么不能直接改基座的memory_limiterCollector 自带的默认memory_limiter是为小容器约 2 GiB调优的docker/otel-collector/config.yaml 中为limit_mib: 1500、spike_limit_mib: 512、check_interval: 5s。在更大的 Pod 上通常想切换到limit_percentage/spike_limit_percentage模式让限制随 Pod 内存分配伸缩。但 OTel 的confmap包合并 YAML map 是逐叶合并而非整块替换而memorylimiterprocessor在两者都设置时会静默优先limit_mib。两者叠加意味着你无法通过叶合并进现有块的方式把默认memory_limiter切到百分比模式——你的百分比值会出现在effective.yaml里但继承下来的 mib 值在运行时仍然生效。7.2 受支持的替换模式新名字 管道换绑受支持的写法是定义一个新名字的 processor并在CUSTOM_OTELCOL_CONFIG_FILE中把管道processors:列表换成引用它# custom.config.yaml processors: memory_limiter/custom: check_interval: 5s limit_percentage: 75 spike_limit_percentage: 25 service: pipelines: traces: processors: [memory_limiter/custom, batch] metrics: processors: [memory_limiter/custom, batch] logs/out-default: processors: [memory_limiter/custom, transform, batch] logs/out-rrweb: processors: [memory_limiter/custom, batch]重启后Collector 会实例化memory_limiter/custom而非未被引用的默认memory_limiter。可通过查看/etc/otel/supervisor-data/effective.yaml和 Collector 启动时打印的Memory limiter configured日志行来确认。基座 config.yaml 里管道processors:列表正是声明在此处、供 bootstrapcustom 合并覆盖的而 OpAMP 远程配置packages/api/src/opamp/controllers/opampController.ts故意不设置管道上的processors:所以你的合并结果不会被覆盖。7.3 示例调优batchprocessor默认batch是为 ClickHouse 调的send_batch_size: 10000、timeout: 5s。如果你的负载需要更低延迟导出——例如对延迟敏感的 trace或短窗口冒烟测试要在发射后很快断言——就定义一个新的batch并换绑管道# custom.config.yaml processors: batch/lowlatency: send_batch_size: 1000 send_batch_max_size: 2000 timeout: 500ms service: pipelines: traces: processors: [memory_limiter, batch/lowlatency] logs/out-default: processors: [memory_limiter, transform, batch/lowlatency]注意事项只需重新声明想调优的管道没提到的管道继续使用基座默认batch。上面示例中metrics和logs/out-rrweb继续使用默认batch。处理器顺序很重要。保持memory_limiter在 batch processor 之前让背压在 batching 之前生效。更大的批次对 ClickHouse 更友好更少的 insert、更少的 MergeTree parts。默认send_batch_size: 10000、timeout: 5s是推荐起点只有在有明确理由时才调。替换块可以组合同时定义memory_limiter/custom和batch/lowlatency在同一管道引用两者如processors: [memory_limiter/custom, batch/lowlatency]。要验证新 processor 确实在运行而非只出现在effective.yaml里可以查询 Collector 在 8888 端口的 Prometheus 指标端点找新的processor标签curl -s http://localhost:8888/metrics | grep processorbatch/lowlatency # otelcol_processor_batch_batch_send_size_count{processorbatch/lowlatency} 15 # otelcol_processor_batch_timeout_trigger_send_total{processorbatch/lowlatency} 15指标端点的prometheuspull exporter 配置在 docker/otel-collector/config.yaml 的service.telemetry.metrics.readers中。7.4 更轻量的选择用环境变量调默认batch如果只需要调默认batch的send_batch_size、send_batch_max_size或timeout不必定义第二个 processor现有环境变量即可无需自定义配置文件HYPERDX_OTEL_BATCH_SEND_BATCH_SIZE默认10000HYPERDX_OTEL_BATCH_SEND_BATCH_MAX_SIZE默认0表示无上限HYPERDX_OTEL_BATCH_TIMEOUT默认5s这些变量直接在基座 config.yaml 中读取send_batch_size: ${env:HYPERDX_OTEL_BATCH_SEND_BATCH_SIZE:-10000}等因此对所有引用默认batch的地方都生效。需要不同管道不同设置、要组合 batchmemory_limiter 修改、或想覆盖memory_limiter没有等价的环境变量路径时再使用换绑模式。同一换绑模式适用于任何其他基座 processortransform、resourcedetection等——定义一个新名字的组件重新声明应使用它的管道即可。八、升级 OTel Collector 版本Step 1查询对应 core 版本在 upstream contrib manifest 中查找新 contrib 版本对应的 core provider 版本查看其providers:部分——core 版本遵循不同编号方案例如 contrib0.149.0对应 core1.55.0。Step 2更新这些文件根目录.env主要事实来源OTEL_COLLECTOR_VERSIONnew_version OTEL_COLLECTOR_CORE_VERSIONnew_core_versiondocker/otel-collector/Dockerfile— ARG 默认值ARG OTEL_COLLECTOR_VERSIONnew_version ARG OTEL_COLLECTOR_CORE_VERSIONnew_core_versiondocker/hyperdx/Dockerfile— ARG 默认值ARG OTEL_COLLECTOR_VERSIONnew_version ARG OTEL_COLLECTOR_CORE_VERSIONnew_core_versionsmoke-tests/otel-collector/docker-compose.yaml— 兜底默认值args: OTEL_COLLECTOR_VERSION: ${OTEL_COLLECTOR_VERSION:-new_version} OTEL_COLLECTOR_CORE_VERSION: ${OTEL_COLLECTOR_CORE_VERSION:-new_core_version}不需要改动的文件packages/otel-collector/builder-config.yaml——使用占位符构建时替换docker-compose.dev.yml——自动从.env读取docker-compose.ci.yml——自动从.env读取。Step 3验证构建镜像并检查版本docker build -f docker/otel-collector/Dockerfile --target dev -t hdx-otel-test . docker run --rm --entrypoint /otelcontribcol hdx-otel-test --version docker rmi hdx-otel-test九、添加自定义组件有两种方式引入自定义组件取决于组件源码在 monorepo 内还是作为独立 Go module 发布。Approach A本地源码monorepo 开发适合活跃开发——在代码库其余部分旁边迭代组件无需每次变更都发布 Go module tag。在本包下创建 Go module如packages/otel-collector/receiver/myreceiver/带自己的go.mod。在 builder-config.yaml 的对应小节增加条目用path:指向本地 modulereceivers: - gomod: github.com/hyperdxio/hyperdx/packages/otel-collector/receiver/myreceiver v0.0.0 path: ./receiver/myreceiver更新 Dockerfile把组件源码复制进 OCB 构建阶段。当前只复制了builder-config.yaml。在 docker/otel-collector/Dockerfile 和 docker/hyperdx/Dockerfile 中扩展ocb-builder阶段的COPY行# 之前只复制 manifest COPY packages/otel-collector/builder-config.yaml . # 之后同时复制自定义组件源码 COPY packages/otel-collector/builder-config.yaml . COPY packages/otel-collector/receiver/ ./receiver/或者一次性复制全部更简单但packages/otel-collector/内任何文件变更都会使 OCB 构建阶段的 Docker 层缓存失效COPY packages/otel-collector/ .把组件加入相关 OTel 配置文件或 OpAMP 控制器packages/api/src/opamp/controllers/opampController.ts。Approach B已发布的 Go module远程引用适合稳定、带版本的组件——尤其是跨仓库共享或分发给外部用户的组件。无需改 Dockerfile 的COPY。以带 tag 的版本发布 Go module如github.com/hyperdxio/my-otel-receiver v0.1.0。对于 monorepo 子目录中的 moduleGit tag 必须包含 module 路径前缀如packages/otel-collector/receiver/myreceiver/v0.1.0。在builder-config.yaml中增加条目不带path:——OCB 会像 contrib 组件一样通过 Go module proxy 拉取receivers: - gomod: github.com/hyperdxio/my-otel-receiver v0.1.0无需改 Dockerfile——OCB 在go mod download时下载。把组件加入相关 OTel 配置文件或 OpAMP 控制器。如何选择本地path:远程gomod:需要 Dockerfile COPY是否支持未发布代码是否——必须打 tag 并发布开发迭代速度快——重建镜像即可必须 push、打 tag、等待 proxy适合 monorepo是需要正确的 Go module tagging最适合活跃开发稳定/共享组件对大多数 HyperDX 开发场景推荐Approach A本地源码组件成熟且独立版本化时再用 Approach B。十、附基座管道默认配置速览理解 OpAMP supervisor 模式下管道的最终形态需要同时看两份配置bootstrap 基座 docker/otel-collector/config.yaml声明processors:与extensions与动态配置生成器buildOtelCollectorConfig()负责receivers:/exporters:。standalone 模式的等价物是 config.standalone.yaml其头部明确标注本配置派生自opampController.ts更新时应与buildOtelCollectorConfig()保持同步。基座logs管道采用routing/logsconnector 分流命中rr-web.event属性的日志进logs/out-rrweb写入hyperdx_sessions表TTL 720h其余进logs/out-default。这些管道名也是你在CUSTOM_OTELCOL_CONFIG_FILE中做换绑时唯一需要记住的锚点。【免费下载链接】hyperdxResolve production issues, fast. An open source observability platform unifying session replays, logs, metrics, traces and errors powered by ClickHouse and OpenTelemetry.项目地址: https://gitcode.com/gh_mirrors/hy/hyperdx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考