- 可观测性
- 后端
【免费下载链接】highlight
highlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.
session replay（会话回放）是 highlight.io 全栈可观测性平台的核心能力之一，但当业务流量上升、或你只关心特定类型的会话时，未经筛选的录制会迅速淹没你的 session feed。highlight.io 提供了从服务端摄取（ingestion）过滤到客户端自定义控制的多层会话过滤方案：既可以在数据进入系统之前就丢弃大部分无关流量，也可以在客户端通过manualStart精确决定"何时录、录什么"。
本指南以 filtering-sessions.md 为核心脉络，系统讲解 highlight.io 的全部会话过滤手段，包括三种摄取过滤器（采样、限流、排除查询）、按用户标识过滤、仅保留有错误的会话、基于自定义逻辑的manualStart方案，以及彻底关闭录制的disableSessionRecording，并结合仓库源码说明每一层过滤在底层是如何生效的。
为什么需要过滤会话？
在你的应用中，并不是所有会话都值得被完整录制和分析：
- 大量内部员工、爬虫或测试账号的访问会污染 session 列表，让你难以找到真正需要排查的用户路径；
- 某些环境（如
development、staging）产生的会话对你的错误排查没有价值； - 当产品出现流量尖峰时，会话录制成本与存储压力会急剧上升。
highlight.io 的会话过滤机制就是为这些场景设计的。一个需要特别记住的关键规则是：
被过滤掉的会话不计入你的计费配额。
也就是说，无论你是通过摄取过滤器在服务端丢弃数据，还是在客户端主动停止录制，highlight 都只会按照实际保留下来（retained）的数据进行计费，这让你可以在控制成本的同时，只保留对排障真正有意义的回放。
设置摄取过滤器（Ingestion Filters）
摄取过滤器是在数据进入 highlight.io 之前进行的第一道闸门，运行在服务端。你可以按产品维度（sessions、errors、logs、traces 四种数据类型）分别独立配置，共支持以下三种过滤方式，三者可以组合使用。
1. 按百分比采样（Sampling）
按比例随机保留一部分数据。例如，你可以配置只摄取全部会话的 1%：
- 对于每一条到达的数据，highlight 会基于该产品模型的标识符（identifier）做一次随机化决策，从而保证同一数据始终被一致地保留或丢弃；
- 对于traces（链路追踪），随机决策基于
Trace ID，这样同一 trace 下的所有子 span 会同进同出——要么整条链路都被摄取，要么整条都被丢弃，避免出现残缺不全的链路。
在源码中，采样率以项目级配置的形式持久化在数据库中。以 backend/model/model.go 为例，模型为五种产品各保存了一个采样率字段，且默认值均为1（即默认全量采样）：
SessionSamplingRate float64 `gorm:"default:1"` ErrorSamplingRate float64 `gorm:"default:1"` LogSamplingRate float64 `gorm:"default:1"` TraceSamplingRate float64 `gorm:"default:1"` MetricSamplingRate float64 `gorm:"default:1"`对应地，私有 GraphQL API 的EditProjectSettingsmutation 也接收一个sampling输入对象，其中包含session_sampling_rate、error_sampling_rate、log_sampling_rate、trace_sampling_rate、metric_sampling_rate等字段（见 backend/private-graph/graph/generated/generated.go 中的Sampling类型定义）。也就是说，你在前端项目设置页面里配置的每一项采样率，最终都会写入这些字段，供摄取管道的随机采样逻辑读取。
2. 分钟级速率限制（Rate Limit）
在1 分钟的时间窗口内限制摄取的数据点上限。例如，配置每分钟最多摄取 100 个会话：
- 当你的产品出现流量尖峰时，这一设置可以限制被记录的会话数量，避免突发的海量流量打爆存储与预算；
- 速率限制同样按产品独立配置（sessions / errors / logs / traces 各自拥有独立的每分钟上限）。
在数据模型中，对应的字段为SessionMinuteRateLimit、ErrorMinuteRateLimit、LogMinuteRateLimit、TraceMinuteRateLimit、MetricMinuteRateLimit（backend/model/model.go）。这些字段为可空指针类型，未设置（NULL）即表示不启用限流；配置后在 GraphQL 的Sampling类型中对应session_minute_rate_limit、error_minute_rate_limit等Int64字段（generated.go）。
3. 排除查询（Exclusion Query）
设置一个排除规则查询，命中的数据将直接不被摄取。例如，配置排除查询为environment: development，那么所有带有development环境标签的会话都会被丢弃。
提示：这个排除查询复用了 highlight.io 的查询语法，与你在 session feed、日志搜索中使用的搜索语法一致（该语法的完整定义可参见 antlr/SearchGrammar.g4）。因此你熟悉的字段（如
environment、browser、visitedURL等）都可以直接用于排除规则。
对应的存储字段为SessionExclusionQuery、ErrorExclusionQuery、LogExclusionQuery、TraceExclusionQuery、MetricExclusionQuery（backend/model/model.go），在 GraphQL 中对应Sampling类型下的session_exclusion_query等字段（generated.go）。
计费规则：只为实际保留的数据付费
三种摄取过滤器共享同一条计费原则：只按实际保留的数据计费。
例如，配置仅摄取 1% 的会话，则你只会被收取这 1% 会话的费用——会话的计量口径为 events-and-users.md 中定义的会话：会话在H.init（或手动延迟录制时的H.start）时开始，同一会话最长持续录制 4 小时，每个浏览器标签页实例独立成会话；单标签页关闭后 15 分钟内重新打开会恢复原会话，超过 15 分钟则开启新会话。
所有摄取过滤器的配置入口位于项目设置页面的Filters（过滤）标签页中，按产品（sessions、errors、logs、traces）分别展开配置。
按用户标识符过滤会话
有时你可能希望彻底排除某个特定用户的会话（例如内部人员、测试账号或已知的问题用户）。highlight.io 支持在项目设置中维护一个"Filtered Sessions"（已过滤会话）列表，把你希望排除的用户标识符添加进去即可。
需要特别注意的是，匹配依据是调用H.identify方法时传入的第一个参数identifier。从源码看，SDK 的identify(user_identifier, user_object)方法（sdk/highlight-run/src/client/index.tsx）会把第一个参数写入会话数据sessionData.userIdentifier，并在初始化时从存储中恢复后自动调用（同文件第 356-357 行）。因此，请务必保证你在H.identify中使用的 identifier 与你在 "Filtered Sessions" 输入框中填写的字符串完全一致。
只保留有错误的会话：Has Error过滤
如果你主要使用 highlight.io 做错误监控（error monitoring），而不是回放分析，那么你并不需要为每一个正常会话都录制回放。此时可以在项目设置中定位到会话相关的摄取过滤器，通过设置Has Error: false过滤器，让系统只记录发生过错误的会话。
这一设置与下面的disableSessionRecording是两种不同的"只留错误"思路：
Has Error: false是服务端过滤，从源头丢弃没有错误的会话，既节省存储也节省计费；disableSessionRecording是客户端开关，彻底不录制回放数据，但错误、日志等产品仍然正常工作。
基于自定义逻辑过滤：manualStart手动控制录制
服务端摄取过滤器解决的是"数据进来之后要不要"的问题，但有些过滤逻辑依赖运行时状态，例如：
只录制已登录用户的会话，跳过未登录访客的会话。
这种场景无法用静态规则表达，highlight.io 为此提供了manualStart配置项，把"何时开始录制"的决策权完全交给你。其原理是：设置manualStart: true后，SDK不会在页面加载时自动开始录制。从源码可以看到，初始化逻辑在 sdk/highlight-run/src/index.tsx 处显式判断了该选项：
if (!options?.manualStart) { await highlight_obj.initialize() }即只有manualStart为false（默认值）时才自动调用initialize()开始录制；为true时则跳过，等待你在合适的时机手动调用H.start()。该选项的官方注释（sdk/highlight-run/src/client/types/types.ts）也明确指出：它应与H.start()/H.stop()配合，用于自行控制录制时机，默认值为false。
配置方式如下：
H.init('<YOUR_PROJECT_ID>', { manualStart: true, // ... 其他选项 })然后在你的业务逻辑中，用H.start手动开始会话：
useEffect(() => { if (userIsLoggedIn) { H.start() } }, [userIsLoggedIn])对应的H.stop()在底层调用stopRecording(manual)（sdk/highlight-run/src/client/index.tsx）：它会停止 rrweb 的录制观察器、停止所有事件监听器，并将录制状态置为NotRecording，同时写入一条Stop自定义事件用于审计。SDK 的测试用例也覆盖了这一流程——highlight.start()、highlight.stop()、highlight.identify('123', {})均在 sdk/highlight-run/src/tests/index.test.tsx 中被断言，你可以将其作为"如何编写基于manualStart的过滤逻辑"的参考模板。
彻底禁用会话录制：disableSessionRecording
如果你使用 highlight.io只做错误监控或日志记录，完全不需要 session replay 功能，那么最干净的做法是在初始化时设置disableSessionRecording: true：
import { H } from 'highlight.run'; H.init('<YOUR_PROJECT_ID>', { disableSessionRecording: true, // ... });从源码看，该选项的默认值为false（types.ts），其语义是"完全关闭用户会话回放的录制"，并明确提示：除非你只用 highlight.io 做错误监控，否则不要开启它。开启后，SDK 在初始化会话时不仅不录制回放，还会联动关闭网络请求录制——在 client/index.tsx 中，enableNetworkRecording的判定逻辑如下：
if (this.options.disableSessionRecording) { enableNetworkRecording = false } else if (this.options.disableNetworkRecording !== undefined) { enableNetworkRecording = false } else if (typeof this.options.networkRecording === 'boolean') { enableNetworkRecording = false } else { enableNetworkRecording = this.options.networkRecording?.recordHeadersAndBody || false }即disableSessionRecording: true时网络内容录制也会被一并关闭，最终通过initializeSession的disable_session_recording参数（client/index.tsx）同步到服务端。而错误监控、日志等其他产品功能不受影响，仍然正常工作。
小结：如何组合使用这些过滤手段
highlight.io 的会话过滤体系可以归纳为三层防线，你可以根据场景自由组合：
| 过滤手段 | 生效位置 | 典型场景 | 配置入口 |
|---|---|---|---|
| 采样（Sampling） | 服务端摄取 | 控制总体数据量，如只保留 1% | 项目设置 → Filters |
| 分钟级速率限制 | 服务端摄取 | 应对流量尖峰，如每分钟 100 个会话 | 项目设置 → Filters |
| 排除查询 | 服务端摄取 | 排除特定环境/属性，如environment: development | 项目设置 → Filters |
| Filtered Sessions 列表 | 服务端摄取 | 排除特定用户（按H.identify的 identifier 匹配） | 项目设置 → Session Replay |
Has Error: false | 服务端摄取 | 只保留发生过错误的会话 | 项目设置 → Filters |
manualStart+H.start/H.stop | 客户端 | 基于运行时状态（如登录态）自定义录制时机 | H.init配置 |
disableSessionRecording | 客户端 | 只使用错误监控/日志，完全关闭回放 | H.init配置 |
选择建议：
- 想控制成本与数据量，优先配置采样与速率限制；
- 想清理噪音（排除内部流量、无价值环境、特定用户），使用排除查询与 Filtered Sessions；
- 需要精确到运行时机的过滤（如未登录不录制），用
manualStart； - 只想用错误监控或日志，直接
disableSessionRecording: true。
无论选择哪一层，highlight.io 都只会对实际保留的数据计费。如果需要进一步了解会话如何被定义与计量（4 小时上限、15 分钟恢复窗口、每标签页独立会话），可阅读 events-and-users.md；关于H.identify等 SDK 方法更完整的签名说明，见 docs-content/sdk/client.md。
- 可观测性
- 后端
【免费下载链接】highlight
highlight.io: The open source, full-stack monitoring platform. Error monitoring, session replay, logging, distributed tracing, and more.
相关推荐
highlight.io Session Replay 功能全景：从会话录制到检索、过滤与实时回放的完整指南
highlight.io Session Replay 功能全景：从会话录制到检索、过滤与实时回放的完整指南 Session Replay（会话回放）是 hig
可观测性后端highlight.io 会话回放进阶：Canvas/WebGL 录制与 iframe 跨域录制完全指南
highlight.io 会话回放进阶：Canvas/WebGL 录制与 iframe 跨域录制完全指南 Canvas 元素（含 WebGL）与 iframe
可观测性后端B站硬核会员100道题卡到崩溃？本地运行的AI自动答题工具帮你一把
B站硬核会员100道题卡到崩溃？本地运行的AI自动答题工具帮你一把 B站硬核会员试炼要连答100道专业题，横跨十几个分区，答挂了当天只能干等。bili hard
AI 应用工作流自动化AI 技能
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
