highlight.io Environments 完全指南：为会话、错误与告警打上环境标签

可观测性后端【免费下载链接】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 的 Environments环境功能允许你在初始化 SDK 时通过H.init()的environment选项为每一条会话Session和每一个错误Error标注其来源环境如production、staging、development从而在会话列表与错误列表中按环境进行检索与过滤。本文以 environments.md 为核心骨架结合 highlight.io 仓库中前端 SDK、ClickHouse 存储与告警后端的真实实现系统讲解环境标签的配置方式、数据落库原理以及它如何影响告警的创建与过滤。什么是 EnvironmentsEnvironments 是 highlight.io 中用于区分数据来源环境的字符串标签。通过为每次 SDK 初始化指定一个环境名highlight.io 会将该环境名写入会话、错误以及日志、链路等观测数据的记录中。这样一来你可以在统一的观测平台上快速回答这个问题在哪个环境出现生产环境是否发生异常等问题而无需把 staging 与 production 的数据混在一起排查。从源码结构看environment被定义为 highlight.io 检索体系中的保留字段Reserved Key之一schema.graphqls 中ReservedLogKey枚举包含environmentschema.graphqls 中ReservedTraceKey枚举包含environmentschema.graphqls 中ReservedErrorObjectKey枚举包含environmentschema.graphqls 中ReservedSessionKey枚举包含environment。这意味着environment与level、service_name、trace_id等字段一样是 highlight.io 内置的、可直接用于检索与过滤的标准化字段而非普通自定义属性。如何设置环境H.init 的 environment 选项要将会话和错误标记到某个环境只需在初始化 SDK 时传入environment选项H.init(YOUR_PROJECT_ID, { environment: process.env.ENVIRONMENT, })这是 environments.md 给出的核心用法。当environment未显式设置时默认值为production见 client.md 中对该参数的说明。该默认值在客户端 SDK 的构造函数中有明确实现。在 sdk/highlight-run/src/client/index.tsx 中this.environment options.environment ?? production即只要未传入environmenthighlight.io 就会按production处理确保每一条数据都有环境归属不会出现无环境的脏数据。环境选项的类型与取值范围environment选项的类型声明位于 sdk/highlight-run/src/client/index.tsxenvironment?: development | production | staging | string也就是说SDK 层虽然给出三个常用预置值development、production、staging但实际接受任意字符串。你可以自由使用qa、canary、dev-123等自定义环境名highlight.io 会把它们作为独立的环境标签存储与展示。环境名与数据的上报链路在 sdk/highlight-run/src/client/index.tsx 附近客户端在初始化时会随会话数据一并携带environment字段由后端将其写入对应存储表。环境数据在 ClickHouse 中的落库结构highlight.io 后端使用 ClickHouse 作为核心存储。从迁移脚本可以看出Environment字段被持久化在多张核心表中会话表backend/clickhouse/migrations/000012_create_sessions_table.up.sql中sessions表定义了Environment String列见该文件第 23 行会话按(ProjectID, CreatedAt, ID)排序存储错误对象表backend/clickhouse/migrations/000019_create_error_objects_table.up.sql同样包含Environment String列日志表与链路表backend/clickhouse/migrations/000060_add_environment_to_logs.up.sql与backend/clickhouse/migrations/000061_add_environment_to_traces.up.sql分别为logs与traces表新增了Environment String列说明环境字段是逐步推广到全量观测数据类型的。在后端查询层environment作为保留键被映射到 ClickHouse 的Environment列。例如 backend/clickhouse/errors.go 中的字段映射string(modelInputs.ReservedErrorObjectKeyEnvironment): Environment,日志侧同理backend/clickhouse/logs.go 将ReservedLogKeyEnvironment映射为Environment列。这意味着你在前端搜索框中输入environment:production最终会转化为对 ClickHouseEnvironment列的精确过滤。按环境搜索与过滤会话、错误环境设置完成后你就可以在 highlight.io 的会话列表、错误列表中基于环境进行检索与过滤。由于environment是保留字段它支持与其它保留字段如has_errors、service_name、browser_name等组合成复合查询。例如在会话搜索中你可以组合environment:production has_errors:true该查询只返回生产环境中发生过错误has_errors为真的会话。在错误列表中你也可以用environment:staging单独筛出 staging 环境上报的错误。环境过滤的可靠性有测试用例作为保障。在 backend/clickhouse/logs_test.go 中TestReadLogsWithEnvironmentFilter构造了production与development两条日志验证按环境过滤后只返回对应环境的数据NewLogRow(now, 1, WithEnvironment(production)), NewLogRow(now, 1, WithEnvironment(development)),配合WithEnvironment这一 LogRow 构造选项见 backend/clickhouse/log_row.go测试断言按环境读取时结果与期望完全一致。这从实现层面印证了基于环境过滤是 highlight.io 的原生、可验证能力。在前端界面中环境也会作为日志表格的独立列展示见 frontend/src/pages/LogsPage/LogsTable/CustomColumns/columns.ts 中的environment列定义错误实例详情页同样会展示环境信息见 frontend/src/pages/ErrorsV2/ErrorInstance/ErrorInstance.tsx。环境如何决定告警的创建与过滤除了数据检索环境还直接参与告警Alerts的创建逻辑。原文档明确指出Environments are also used to determine whether Alerts are created.在告警配置中环境扮演两个角色1. 指定告警关注的环境创建告警时你可以通过Environments参数指定该告警作用于哪些环境。在告警后端 backend/alerts/sessionalerts.go 中marshalEnvironments将环境列表序列化后写入告警配置func marshalEnvironments(environments []string) (*string, error) { envBytes, err : json.Marshal(environments) ... }告警记录同时保存了Environments关注环境与ExcludeRules排除规则两类环境相关配置见 backend/alerts/sessionalerts.goenvString, err : marshalEnvironments(input.Environments) ... excludeRulesString, err : marshalEnvironments(input.ExcludeRules) ... ExcludedEnvironments: envString,2. 排除不需要告警的环境在会话告警的创建页面上highlight.io 提供了Excluded environments排除环境选择器见 frontend/src/pages/Alerts/SessionAlert/SessionAlertPage.tsx。该下拉框的候选项来自environment_suggestion接口即按项目历史数据聚合出的已有环境名前端会通过dedupeEnvironments去重见 frontend/src/pages/Alerts/utils/AlertsUtils.ts。典型场景你只关心生产环境的错误。此时可以创建一条错误告警将ExcludedEnvironments设为[development, staging]这样开发环境与预发环境产生的噪声告警会被自动屏蔽只有生产环境的数据触发告警。反之也可以显式指定告警仅对production生效。告警数据源告警的检索源与会话/错误列表一致均基于environment这一保留字段。关于告警的通用配置数据源选择、过滤器、冷却时间、通知渠道等可参考 alerts.md。实战建议多环境部署的最佳实践结合原文档与仓库实现推荐以下环境配置策略1. 用环境变量驱动环境标签正如原文档示例所示直接在H.init中读取构建/运行环境变量H.init(YOUR_PROJECT_ID, { environment: process.env.ENVIRONMENT, })这样在 CI/CD 流水线中部署到哪个环境就会自动带上对应的标签无需为每个环境维护一份前端代码。2. 明确设置而非依赖默认值虽然未设置时默认值为production见 client.md 与 sdk/highlight-run/src/client/index.tsx但显式传入环境名更利于避免本地开发误入 production这类数据混淆问题。例如本地开发时可显式传developmentH.init(YOUR_PROJECT_ID, { environment: process.env.NODE_ENV development ? development : production, })3. 环境名保持统一与稳定环境名会直接写入 ClickHouse 的Environment列会话、错误、日志、链路均如此并在告警的environment_suggestion中作为候选项出现。建议团队内部统一命名规范如production、staging、development、qa避免出现prod、PROD、prod-1这类同义异形标签以保证过滤和告警配置的准确性与可维护性。小结highlight.io 的 Environments 功能贯穿了采集 — 存储 — 检索 — 告警全链路采集通过 H.init() 的environment选项标记数据来源默认值为production存储Environment作为String列持久化于会话、错误、日志、链路等 ClickHouse 表如 000012_create_sessions_table.up.sql、000019_create_error_objects_table.up.sql检索environment是保留检索字段可与会话、错误、日志的其它字段组合过滤并有 logs_test.go 等测试用例验证告警通过告警配置中的环境关注与排除规则实现只对特定环境告警的精准通知见 sessionalerts.go 与 SessionAlertPage.tsx。只需一行environment配置你就能让 highlight.io 的会话回放、错误追踪与告警系统完全贴合你的多环境部署拓扑显著缩小问题排查范围。赞分享可观测性后端【免费下载链接】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为会话与错误打上应用版本标签version 配置详解Highlight为会话与错误打上应用版本标签 version 配置详解 在基于 Highlighthighlight.io开源全栈监控平台构建前端可观测性后端highlight.io 在 Gatsby.js 中的完整接入指南会话回放、错误监控与全栈日志highlight.io 在 Gatsby.js 中的完整接入指南会话回放、错误监控与全栈日志 本文基于 highlight.io 官方文档 Gatsby.j可观测性后端使用包管理器安装 VectorAPT、dpkg、RPM、YUM、pacman、Homebrew、Nix、Helm 与 MSI 全平台指南使用包管理器安装 VectorAPT、dpkg、RPM、YUM、pacman、Homebrew、Nix、Helm 与 MSI 全平台指南 本指南完整讲解开源可可观测性后端上一篇NeteaseCloudMusicFlac无损音乐批量下载指南3步把整张FLAC歌单存到本地下一篇TPFanCtrl2 完整实战指南Windows 10/11 下的 ThinkPad 双风扇控制创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考