Winston + highlight.io 日志接入实战：用 HTTP Transport 将 Node.js JSON 日志送入全栈监控平台

可观测性后端【免费下载链接】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点击查看免费下载导读本篇指南讲解如何在 Node.js 服务中使用 Winston 日志框架接入 highlight.io 的日志摄取能力借助 Winston 内置的HttpTransport将应用日志以 JSON 形式实时上报到 highlight.io 云端与前端会话回放、错误监控打通形成全栈可观测闭环。读完本文你将掌握完整的 Winston 接入配置、请求头与路径语义、日志验证方法并理解 highlight.io 服务端/v1/logs/json端点的底层实现让日志从本地可见升级为平台可查、可检索、可关联。1. 接入前的准备前置依赖在配置 Winston Transport 之前请先确认两件事前端集成可选但推荐如果你正在为应用接入 highlight.io 前端 SDK请先按 前端快速开始 完成初始化并参考前后端关联映射指南让后端日志能与前端会话正确关联。这一步不强制但能显著提升全栈排查效率。获取项目 ID登录 highlight.io 控制台在项目设置中找到你的Project ID。它将被填入 HTTP 请求头的x-highlight-project字段中用于日志归属识别。2. 核心配置创建 Winston HTTP TransportWinston 自带transports.Http可将日志序列化后通过 HTTP 上报。highlight.io 官方 Quick Start定义于 winston.tsx给出了如下开箱即用的配置import {createLogger, format, transports} from winston; const highlightTransport new transports.Http({ host: pub.highlight.run, path: /v1/logs/json, ssl: true, headers: { x-highlight-project: YOUR_PROJECT_ID, x-highlight-service: EXAMPLE_NODEJS_SERVICE, }, }) export const logger createLogger({ level: info, format: format.combine( format.json(), format.errors({ stack: true }), format.timestamp(), format.prettyPrint(), ), transports: [new transports.Console(), highlightTransport], })配置项逐项拆解配置项取值含义hostpub.highlight.runhighlight.io 公有云日志摄取域名对应生产环境入口path/v1/logs/jsonJSON 日志接收端点服务端由HandleJSONLog处理器承载见下文源码ssltrue使用 HTTPS 加密传输生产环境必须开启headers[x-highlight-project]YOUR_PROJECT_ID必填标识日志归属的项目headers[x-highlight-service]你的服务名建议填写便于按服务维度过滤日志几点实战建议替换占位符将YOUR_PROJECT_ID替换为真实项目 ID将EXAMPLE_NODEJS_SERVICE替换为你的服务名如order-service否则日志会被归到错误的项目或显示为默认服务名。日志级别level: info意味着info及以上级别warn、error都会进入 Transport 管道若只关心错误可调整为error。Format 组合format.json()保证日志被序列化为 JSON 载荷format.errors({ stack: true })会将 Error 对象展开并附带堆栈format.timestamp()为每条日志注入时间戳format.prettyPrint()则便于本地控制台阅读。生产环境中也可按需去掉prettyPrint以降低本地输出噪音。双 Transport 并存Console与highlightTransport同时挂载意味着日志本地照常打印、远端同步上报无需改动任何业务代码中的logger.info/error调用点。3. 底层原理/v1/logs/json端点是如何处理日志的配置中的path: /v1/logs/json并非虚构地址它在 highlight.io 后端有真实实现。查看 backend/http/logging.go 中的路由注册func Listen(r *chi.Mux, t trace.Tracer) { tracer t r.Route(/v1, func(r chi.Router) { r.Use(highlightChi.Middleware) r.HandleFunc(/logs/raw, HandleRawLog) r.HandleFunc(/logs/json, HandleJSONLog) r.HandleFunc(/logs/firehose, HandleFirehoseLog) }) }可以看到/v1路由族同时暴露了三种日志摄取入口/logs/json接收结构化 JSON 日志即本指南 Winston 所用的端点支持批量数组与 NDJSON 流式体/logs/raw接收纯文本原始日志日志内容即请求体级别默认记为info见 HandleRawLog/logs/firehose面向 AWS Firehose 等流式管道的高吞吐入口。HandleJSONLog在解析请求时会读取x-highlight-project等头部与project、service查询参数将 JSON 中的每条日志转换为内部hlog.Log结构补齐service.name等 OpenTelemetry 语义属性后通过SubmitHTTPLog交给下游ClickHouse存储。这正是Winston 上报 → 服务端规范化 → 可检索存储的完整链路。值得注意Winston HTTP Transport 默认会将每条日志作为独立 JSON 对象 POST 上去而HandleJSONLog同样支持 NDJSON多行 JSON批量体。若你的应用日志吞吐量很大可以考虑使用自定义 transport 做本地批量缓冲减少 HTTP 请求次数从源码结构与端点设计看服务端已为批量场景做了支持。4. 验证日志是否成功上报完成配置后用以下方法验证链路是否打通对应 Quick Start 中的verifyLogs步骤在业务代码中主动输出一条日志例如logger.info(Hello from my Node.js service)启动服务确认控制台正常打印Console Transport 生效登录 highlight.io 控制台进入Logs日志检索页面选择对应的项目按服务名EXAMPLE_NODEJS_SERVICE或你填写的服务名过滤应能看到刚输出的日志记录包含时间戳、级别与完整 JSON 载荷。如果日志迟迟未出现按以下顺序排查项目 ID 是否填写正确x-highlight-project与查询参数project二选一即可但 header 方式是 Winston 配置的标准做法网络是否可达pub.highlight.run公网域名防火墙/代理需放行 443 端口日志级别是否低于level: info而被过滤查看服务端端点测试样例确认请求格式与预期一致——仓库测试 backend/http/logging_test.go 展示了POST /v1/logs/json的多种合法请求体单条 NDJSON、批量 JSON 数组、带project/service查询参数等可作为对照参考。5. 进阶与其他日志摄取方式对比highlight.io 不止支持 Winston同一套平台还提供多种摄取路径便于按场景选型方式适用场景特点Winston HTTP Transport本文Node.js Winston 栈零额外依赖仅用 Winston 内置能力配置即用Pino Transport追求极致性能的 Node.js 服务与 Pino 的 JSON 序列化原生契合OTLP 协议已采用 OpenTelemetry 的异构系统标准协议多语言 SDK 通用便于与 traces/metrics 统一出口/v1/logs/raw原始端点快速验证、脚本化上报请求体即消息文本无需构造 JSON若你的服务已在使用 OpenTelemetry也可直接用 OTLP 上报而跳过 Winston Transport两种方式在 highlight.io 的 Logs 视图中统一展示。6. 小结本文围绕 Winston 与 highlight.io 的集成完整覆盖了从 HTTP Transport 配置、请求头与路径语义、日志验证到底层端点实现的全部要点用transports.Httppub.highlight.run/v1/logs/json即可完成接入核心代码不超过 20 行x-highlight-project与x-highlight-service两个请求头承担了项目归属与服务标识的关键职责后端 backend/http/logging.go 的/v1路由族提供了 JSON、Raw、Firehose 三种摄取入口测试用例logging_test.go可帮助你验证请求格式完成上报后前端会话回放、错误监控与后端日志可在同一平台统一检索真正实现全栈可观测。现在替换占位符、启动服务去 Logs 页面看看你的第一条 Winston 日志吧。赞分享可观测性后端【免费下载链接】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点击查看免费下载相关推荐highlight.io 接入 Pino.js利用 HTTP JSON transport 将结构化日志发送到日志平台highlight.io 接入 Pino.js利用 HTTP JSON transport 将结构化日志发送到日志平台 本文介绍如何将 Node.js 服务中可观测性后端highlight.io 日志接入指南通过 Render Log Stream 将托管平台日志流入 highlight 全栈监控highlight.io 日志接入指南通过 Render Log Stream 将托管平台日志流入 highlight 全栈监控 Render 是主流的 Pa可观测性后端highlight.io Express.js 服务端监控实战用 Node.js SDK 接入错误、日志与 Traceshighlight.io Express.js 服务端监控实战用 Node.js SDK 接入错误、日志与 Traces 本文基于 highlight.io可观测性后端上一篇Mona Sans 可变字体现代网页设计的终极排版解决方案下一篇OpCore-Simplify重新定义黑苹果配置的技术哲学与实践创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考