可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载为应用埋点做性能追踪本身就是一项繁琐的工作而多数可观测性方案还会带来供应商锁定所有埋点数据的格式、去向都被单一厂商的私有 SDK 绑死。本文以 Highlight 官方博客《Day 1: OpenTelemetry on Highlight》为主线讲解 OpenTelemetryOTel与 Highlight 的组合方案并结合当前仓库源码深入剖析 Highlight 后端是如何原生接收 OTLP 数据的——包括 OTLP 端点注册、字段提取与项目路由、Kafka ClickHouse 的落库管线以及可直接复用的 Collector 配置。读完本文你将掌握如何把任意 OTel SDK/Collector 直接指向 Highlight 完成数据上报、Highlight 如何从 OTLP 数据中提取项目与会话上下文、以及一套支持多后端扇出的 Collector 生产配置。为什么选择 OpenTelemetry消除供应商锁定博客开篇指出了一个普遍痛点为代码埋点做追踪非常痛苦而许多可观测性方案会造成供应商锁定——你投入的所有追踪工作量最终只能发往某一种你并不控制的服务器。Highlight 给出的统一解法是让 OpenTelemetry 负责数据采集与协议让 Highlight 负责存储与可视化。OpenTelemetry 提供全面的 tracing、logging、metrics 与错误监控能力且数据目的地与埋点代码解耦。它同时是有主张又灵活的借助 OTel Collector 的 processors 和 exporters你可以把同一条数据流分发到 ClickHouse、Prometheus 或其他开源数据库Highlight 则显著降低存下这些数据并可视化的工程开销只需把你的 OpenTelemetry Collector 指向 HighlightCloud 或 Self-Hosted其余工作都由 Highlight 完成。从源码结构看Highlight 后端使用 Kafka 做异步缓冲、ClickHouse 做最终存储并配套完整的搜索与查看界面一个关键的产品能力Highlight 会把服务端细粒度的 traces 与 logs归属到前端会话session上从而让你能回看哪些用户操作触发了哪些后端代码。官方入门文档位于 Native OpenTelemetry Overview其中错误监控、日志、追踪、浏览器数据的分主题指南同在该目录下错误监控、日志、追踪、浏览器、指标。四个核心收益博客原文要点博客列出的集成收益可以归纳为四点逐条展开厂商无关的埋点Vendor Agnostic Instrumentation使用 OpenTelemetry 的埋点不关心数据最终发往哪里。这种自由度让你免于供应商锁定保持可观测性策略的灵活性——今天发往 Highlight明天多一路扇出到自建后端埋点代码零改动。广泛的库与语言支持OTel 规范的开源属性意味着它覆盖大量语言与库兼容性与通用性极强。仓库中sdk/目录下的各语言 SDKGo、Node、Python、Ruby、Java、Rust、.NET 等底层均基于 OTel 构建。自动埋点Auto-InstrumentationOpenTelemetry 维护着一个包含数百个兼容库、插件与集成的大型生态注册表如果你在用的某个库已经有 OTel 插件甚至库本身已内置 OTel 埋点那么接入成本几乎为零。用 Highlight 简化数据管理集成后无需再关心追踪数据的存储与查看细节可以把精力集中在理解并优化应用性能本身。源码剖析Highlight 后端的原生 OTLP 端点博客说只需把 Collector 指向 Highlight那么 Highlight 后端到底暴露了什么答案在 backend/otel/otel.go 中的Listen方法——它注册了一组标准 OTLP 路径// backend/otel/otel.go (Listen) func (o *Handler) Listen(r *chi.Mux) { r.Route(/otel/v1, func(r chi.Router) { r.Use(highlightChi.UseMiddleware(trace.WithSpanKind(trace.SpanKindConsumer))) r.HandleFunc(/traces, o.HandleTrace) r.HandleFunc(/logs, o.HandleLog) r.HandleFunc(/metrics, o.HandleMetric) }) }即后端提供三个 OTLP 接收端点端点处理器解析格式对应信号POST /otel/v1/tracesHandleTraceptraceotlp.ExportRequestprotobufTracesPOST /otel/v1/logsHandleLogplogotlp.ExportRequestprotobufLogsPOST /otel/v1/metricsHandleMetricpmetricotlp.ExportRequestprotobufMetrics该 Handler 在 backend/main.go 中被构造并挂载otelHandler : otel.New(publicResolver)otelHandler.Listen(r)因此任何支持 OTLP 的 SDK 或 Collector 都可直接发送数据无需 Highlight 私有 SDK。一个请求的生命周期以 HandleTrace 为例HandleTracebackend/otel/otel.go#L127的处理流程展示了Kafka 高效摄入这一博客承诺的落地方式读取并解压请求体highlightHttp.GetBody读取请求体解析 protobufreq.UnmarshalProto(output)失败即返回 400逐 Resource → Scope → Span 遍历对每个 span 调用extractFields提取字段见下节。这里有两个值得注意的细节以fs开头的 spanIgnoredSpanNamePrefixes只作为 trace 摄入不再生成 log/error/metric避免文件系统操作噪音span 事件Span Events会被识别为三类特殊事件exception错误、log日志、metric数值指标分别路由到错误、日志、指标管线按类别提交到 Kafka指标 →MetricSumQueuekafkaqueue.OTeLMetricSumRow等错误 →AsyncProducerQueue消息类型PushBackendPayload按 session 作为 Kafka key无 session 的错误会随机分配 key保证同一会话的错误有序span →TracesQueue以 traceID 作为消息 key日志 →BatchedQueuePushLogsFlattened任一步骤提交失败即返回503 Service Unavailable让上游 Collector 依其重试策略重发。每条数据在提交前还会经过IsTraceIngested/IsErrorIngested等过滤函数与配额检查getQuotaExceededByProject通过 Redis 缓存每个项目的配额状态超限项目的数据被直接丢弃这是摄入管线上的重要自我保护机制。字段提取数据如何路由到正确的项目与会话backend/otel/extract.go 中的extractFields是整个摄入层的核心它把resource、span、span event、scope、log record、metric各层属性合并mergeMaps后者优先再按优先级解析出路由字段。合并顺序为originalAttrs : mergeMaps( resourceAttributes, spanAttributes, spanEventAttributes, scopeAttributes, logAttributes, metricMetadata, metricAttributes, )Highlight 特有的路由属性包括highlight.project_id— 决定数据写入哪个项目同时也支持通过请求头X-Highlight-Projecthighlight.ProjectIDHeader覆盖highlight.session_id— 会话 ID用于把后端数据归属到前端会话highlight.trace_id— 请求 ID充当后端请求的追踪标识highlight.sourcefrontend/backend、highlight.typehttp.request/highlight.internal、highlight.key等可选上下文字段。这些属性正是博客所强调的把细粒度服务端数据归属到前端会话的实现基础。按照 Native OpenTelemetry 概览文档 的说明SDK 会在 span 上额外设置highlight.project_id、highlight.session_id、highlight.trace_id三个 SpanAttributesession/request ID 来自网络请求的X-Highlight-Request头格式为sessionId/requestId并按 OTel 语义约定上报 Trace 与 Log。extractFields同时处理了大量真实世界的边缘情况均有对应单元测试backend/otel/extract_test.go、backend/otel/otel_test.go佐证项目 ID 的多来源解析属性highlight.project_id、请求头、syslog 消息前缀如119 401 ... heroku ...形式的 heroku drain、fluent tag 中的highlight.project_idxxx、Heroku drain token 反查项目映射matchHerokuDrain结果缓存在 Redissyslog / systemd 日志解析extractSyslog与extractSystemd分别处理 RFC 5424 syslog 与 systemd journal 结构化日志语义约定字段提取exception.type/exception.message/exception.stacktrace、service.name/service.version、deployment.environment、log.severity/log.message、metric.name/metric.value等错误生成getBackendErrorbackend/otel/otel.go#L66在 span 的exception事件上构造BackendErrorObjectInput堆栈会经过stacktraces.FormatStructureStackTrace(..., stacktraces.FromOTeL())格式化。此外从源码结构看还有一个安全细节生产环境下来自外部 Hobby 实例路由到云项目 1的数据会被标记为 external 并丢弃其中的 exceptionExternalHighlightData/fields.external防止跨实例数据污染。仓库中的 Collector 参考配置仓库内有两份可直接参考的 OpenTelemetry Collector 配置分别对应生产部署与本地开发生产配置deploy/otel-collector.yaml关键要点receivers: otlp: protocols: grpc: endpoint: 0.0.0.0:4317 max_recv_msg_size_mib: 1000 http: endpoint: 0.0.0.0:4318 cors: allowed_headers: - X-Highlight-Request # 放行 Highlight 上下文头 # ... # 另含 syslogRFC 5424, UDP 6513 / TCP 6514、fluentforward、tcplog、 # awsfirehosecwmetrics / cwlogs / otlp_v1等日志类接收器 processors: memory_limiter: limit_mib: 14336 spike_limit_mib: 1024 batch: metadata_keys: [x-highlight-project] # 按项目批量 send_batch_size: 1000 send_batch_max_size: 10000 attributes: actions: - key: highlight.project_id from_context: metadata.x-highlight-project action: insert # 把 header 写入属性 service: pipelines: traces: { receivers: [otlp], processors: [memory_limiter, batch, attributes], exporters: [otlphttp] } metrics: { receivers: [otlp, awsfirehose/cwmetrics, awsfirehose/otlp_v1], ... } logs: { receivers: [otlp, fluentforward, tcplog, syslog, awsfirehose/cwlogs], ... }值得关注的工程细节batch处理器以x-highlight-project元数据作为 metadata_keys保证同一项目的数据被聚在同一批中配合后端session 作为 Kafka key的排序策略端到端保持会话内有序attributes处理器把 header 中的项目 ID 注入为highlight.project_id属性使纯 header 路由的数据也能被extractFields识别otlphttpexporter使用 snappy 压缩、100 消费者、1 万条发送队列并开启指数退避重试initial_interval: 1s→max_interval: 30s最长 300s——这与后端返回 503 的让上游重试设计正好衔接。本地/自托管配置docker/collector.yml自托管版在同样的接收器基础上追加了otlp/https8318 端口挂载 TLS 证书接收器exporter 指向宿主机后端https://host.docker.internal:8082/otelsnappy 压缩 重试并附带debugexporter 便于本地调试。配合 docker/compose.yml 与 docker/run.sh 即可在本地拉起Collector 后端 ClickHouse Kafka的完整链路——这正是博客中指向 HighlightCloud 或 Self-Hosted里 Self-Hosted 一侧的实操形态。多后端扇出埋点一次分发多处博客强调 OTel 方案在数据存储上既有主张又保持灵活。当需要同时向多个可观测后端发数据时官方概览文档给出了标准的 Collector 扇出配置receivers: otlp: # 接收你的应用 SDK protocols: grpc: endpoint: 0.0.0.0:4317 http: endpoint: 0.0.0.0:4318 processors: batch: exporters: otlphttp/highlight: endpoint: https://otel.highlight.io compression: gzip otlphttp/example: endpoint: https://example.com/otel service: pipelines: traces: receivers: [otlp] processors: [batch] exporters: [otlphttp/highlight, otlphttp/example] metrics: receivers: [otlp] processors: [batch] exporters: [otlphttp/highlight, otlphttp/example] logs: receivers: [otlp] processors: [batch] exporters: [otlphttp/highlight, otlphttp/example]将应用 SDK 指向 Collector、由 Collector 扇出到 Highlight 与其他后端是埋点与目的地解耦这一收益最直接的体现。若你的语言 SDK 尚不支持原生日志上报该文档还建议以 span event 形式上报事件名log携带log.severity与log.message属性后端HandleTrace中的highlight.LogEvent分支正是这一路径的消费端。小结Highlight 的后端原生实现了 OTLPprotobuf接收端点/otel/v1/{traces,logs,metrics}backend/otel/otel.go任意 OTel SDK 或 Collector 可直接对接无供应商私有协议extractFieldsbackend/otel/extract.go负责从多层属性与请求头中提取highlight.project_id、highlight.session_id、highlight.trace_id等路由字段把后端数据归属到正确的项目与前端会话并兼容 syslog、systemd、heroku drain、fluent tag 等边缘来源数据管线为OTLP 解析 → 过滤与配额检查 → 按类别进入 Kafka 队列 → ClickHouse 落库失败时以 503 触发 Collector 重试仓库提供了生产deploy/otel-collector.yaml与本地自托管docker/collector.yml两套 Collector 配置以及按项目分批、header 注入属性、指数退避重试等可直接借鉴的工程细节通过 Collector 的 fan-out 能力同一份 OTel 埋点可同时服务多个可观测后端这是 OpenTelemetry 与 Highlight 组合方案对抗供应商锁定的核心机制。赞分享可观测性后端【免费下载链接】highlighthighlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.项目地址https://gitcode.com/gh_mirrors/hi/highlight点击查看免费下载相关推荐OpenTelemetry Collector OTLP HTTP Exporter 完全指南配置、原理与实战OpenTelemetry Collector OTLP HTTP Exporter 完全指南配置、原理与实战 导读 本文围绕 OpenTelemetry C可观测性后端运维观测理好本地音乐Salt Player 歌单就够了理好本地音乐Salt Player 歌单就够了 我数过自己手机里的歌单二十多个一半以上叫歌单1歌单2 副本歌是随便扔进去的想听哪首还得翻半天。DLSS Swapper 替换游戏DLSS版本指南不更新游戏也能优化超采样效果DLSS Swapper 替换游戏DLSS版本指南不更新游戏也能优化超采样效果 你刚把新游戏拉到最高画质帧数却不太争气——问题很可能出在游戏自带的 DLSS桌面应用上一篇8大网盘直链解析一键拿到真实下载地址下一篇Windows 离线实时语音字幕三步装好 TMSpeech会议纪要自动生成创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考