> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 规划经得起时间的数据流与字段

> 在第一个大流量数据源接入之前，决定如何拆分数据流、统一字段命名、为过滤字段建索引，并保护敏感值。

数据、仪表盘和告警规则一旦依赖了数据流和字段，就很难再修改：字段写入后类型固定，加密标志无法事后添加，改名的字段会让所有保存的查询失效。在接入第一个繁忙的数据源之前，先花一小时做好设计。

## 按差异拆分数据流

只有数据需要不同的契约时才单独建数据流：不同的保留期、访问规则、Schema 或查询范围限制。否则把数据放在一起，用字段区分。

| 场景 | 推荐做法 | 取舍 |
| - | - | - |
| 调试日志保留 3 天，审计日志保留一年 | 两个 `logs` 数据流，各自设置保留期。 | 同时需要两者的查询要使用两个数据流。 |
| 多个服务的日志结构相同 | 一个数据流，每条事件都带 `service.name`。 | 保留期和访问权限不能按服务区分。 |
| 由流水线分拣到各数据流的原始数据洪流 | 关闭 **可查询** 的源数据流，加一条路由流水线。 | 原始事件会保留到保留期结束，所以保留期要短。 |
| 每台 Prometheus 服务器 | 每个来源一个 `metrics` 数据流。 | 跨来源查询要指定多个数据流。 |
| 每个 Pod、版本或客户一个数据流 | 避免。改用字段区分。 | 大量小数据流会让文件数成倍增加，每次变动都会破坏仪表盘。 |

数据第一次写入时 MoleSignal 会自动创建数据流，因此发送端的一个拼写错误会悄悄产生一个新数据流。每接入一个数据源都要检查[数据流列表](https://docs.molesignal.com/zh-Hans/streams.md#数据流列表)，并提前创建重要的数据流，设置好保留期和加密字段。

## 发送之前约定字段名

能用 OpenTelemetry 名称的地方都用它，同一个含义在所有信号中使用同一个名称。跨信号跳转和应用性能都依赖这些字段。

| 字段 | 内容 | 原因 |
| - | - | - |
| `service.name` | 服务名，在日志、链路和指标中保持一致。 | 把所有信号关联到同一个服务。 |
| `deployment.environment.name` | `production`、`staging` 等。 | 让每个页面都能按环境过滤。 |
| `service.version` | 发布的版本。 | 驱动应用性能中的部署对比。 |
| `trace_id`、`span_id` | 请求内写出的每条日志都带上。 | 让日志可以一键跳转到它的链路。 |
| `level` | 统一的写法，例如小写的 `error`、`warn`、`info`。 | 日志直方图从索引统计级别。 |
| `host.name`、`k8s.pod.name` | 事件发生的位置。 | 把问题缩小到一台机器。 |

同一个字段在所有发送端中保持相同的类型：某个服务以数值发送、另一个服务以文本发送的字段，会被以 `type mismatch on field` 拒绝。请在存储前用流水线的 **类型转换** 步骤统一这类字段。不要给已有字段名赋予新含义，应新增字段。

## 为过滤字段建索引

[索引类型](https://docs.molesignal.com/zh-Hans/streams.md#schema-与字段)决定过滤的速度。除少数常见字段外，新字段默认没有索引。请检查仪表盘和告警过滤用到的字段：

* 整体比较的标识符用 **精确匹配**：`trace_id`、`user_id`、`order_id`、`service.name`。
* 按词搜索的文本（例如 `message`）用 **全文搜索**。
* 用 `<`、`>` 比较的数值和时间（例如 `duration_ms`）用 **跳过索引**。
* 只用于展示的字段不建索引。

修改索引只影响新数据，旧文件在 Compactor 合并时获得新索引。在 **数据流 → 字段与索引** 中修改，然后 **保存并应用**。

## 不要把高基数值放进标签

取值没有上限的指标标签（例如用户 ID、请求 ID 或完整 URL）会为每个取值产生一个新序列。随后[基数上限](https://docs.molesignal.com/zh-Hans/settings/platform.md#指标基数)会拒绝整个组织的新序列。把这类值放到日志或 Span 属性中，它们不会按取值产生成本；指标标签只保留服务、路由模板、方法、状态码类别这类有限集合。

服务所属团队、客户套餐这类否则要复制到每条事件中的参考数据，应放进[扩展表](https://docs.molesignal.com/zh-Hans/extend-tables.md)，由流水线在处理时查找。

## 从一开始就保护敏感值

| 需求 | 工具 | 生效时机 |
| - | - | - |
| 永远不存储某个值，例如银行卡号 | 开启 **写入时脱敏** 的[正则模式](https://docs.molesignal.com/zh-Hans/settings/data-security.md#正则模式)，或删除该字段的流水线步骤。 | 写入时，永久生效。 |
| 存储某个值，但只给少数人读取 | 创建数据流时声明的加密字段，用 `decrypt()` 读取。 | 从数据流创建时起。 |
| 在大多数查询结果中隐藏某个值 | [字段遮掩](https://docs.molesignal.com/zh-Hans/settings/data-security.md#字段遮掩)。 | 查询时，作用于结果。 |

优先在发送端或采集器中去掉敏感值。从未离开源头的值，就不可能从 MoleSignal 泄露。

## 验收标准

* 每个数据流都有负责人、存在的理由，以及有意设置的保留期。
* 一个已知请求可以从日志一键跟到它的链路。
* 仪表盘和规则过滤用到的字段都有合适的索引。
* 没有指标标签携带无上限的取值，指标页的 **基数** 显示稳定的序列数。
* 带敏感标记的测试事件按计划被脱敏、遮掩或加密。

## 相关指南

* [数据流](https://docs.molesignal.com/zh-Hans/streams.md)
* [流水线](https://docs.molesignal.com/zh-Hans/pipelines)
* [数据安全设置](https://docs.molesignal.com/zh-Hans/settings/data-security.md)
* [分阶段接入新服务](https://docs.molesignal.com/zh-Hans/best-practices/service-onboarding.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.