> ## 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.

# 分阶段接入新服务

> 从一条关键请求路径开始，保留排障上下文，在确认数据质量和成本后扩大采集范围。

接入新的结算服务时，从请求入口到支付确认这一条路径开始。先收集足以解释请求失败或变慢的证据，再扩大到全部组件。

## 先确定需要回答的问题

选定少量运行问题：请求是否成功、耗时集中在哪里、哪个依赖发生故障。为每个问题明确所需信号与负责团队。

| 问题 | 推荐证据 | 取舍 |
| - | - | - |
| 客户能否完成结算？ | 业务结果指标与客户路径检查 | 基础设施可用不代表业务成功。 |
| 哪个操作变慢？ | 使用稳定服务名和明确 Span 名称的链路 | 采样可能遗漏正在调查的请求。 |
| 请求为什么失败？ | 携带 `trace_id` 的结构化错误日志 | 原始请求体会增加数据量，也可能泄露敏感数据。 |

在不同信号中使用一致的服务与环境标识。将请求标识保留在日志和链路中；避免把唯一请求 ID 或客户 ID 用作指标标签，每种标签值组合都会增加时间序列。

## 从受控范围开始

先使用测试环境与模拟客户数据。沿同一路径分别触发成功请求、依赖故障和慢请求，验证时间戳、标识和字段类型能支持跨信号调查。

用[数据源](https://docs.molesignal.com/zh-Hans/intake#数据源页面)中的向导接入每个数据源：向导会填好端点和 Token，**验证数据到达** 会显示最近 1 小时内是否收到了数据。

随后为少量生产流量启用采集。检查拒收事件、接入量、查询延迟与失败请求覆盖率后再扩大范围。上线前约定观察周期和验收上限；低峰时段的结果不能代表高峰负载。

## 明确数据流边界

保留周期、Schema 或访问要求不同时，拆分日志数据流。要求相同时，优先用字段区分服务、环境和发布版本。避免为每个实例或部署版本创建数据流。参见[规划经得起时间的数据流与字段](https://docs.molesignal.com/zh-Hans/best-practices/stream-design.md)。

保持不同发送端的同名字段类型一致。MoleSignal 会因类型不匹配拒绝不兼容的字段值。将流水线用于生产流量前，使用缺失字段、异常类型和大消息验证转换逻辑。

在发送端或采集器中移除敏感数据，再发送遥测数据。转换时保留 `trace_id`。使用版本字段区分发布版本，避免直接改变已有字段含义。

## 平衡保留周期与调查覆盖率

根据发现和调查故障所需的时间设置保留周期。只有事件响应流程能在对应时间窗口内完成调查时，才缩短高流量诊断日志的保留周期。后续增加保留周期无法恢复已经清理的数据。参见[控制遥测数据量与成本](https://docs.molesignal.com/zh-Hans/best-practices/volume-and-cost.md)。

降低链路采集量时，验证日志仍保留有效的错误上下文。缺少链路可能来自采集或采样缺口，不能据此判断请求成功。

## 验收标准

* 能从日志中找到已知失败请求，并关联到已采集的链路。
* 测试事件经过流水线后仍保留正确类型和标识。
* 具有代表性的流量区间满足约定的数据量与查询延迟上限。
* 接收到的遥测数据中不包含敏感测试标记。
* 负责团队已准备采集与转换变更的回退方案。

## 相关指南

* [集成指南](https://docs.molesignal.com/zh-Hans/intake/integrations.md)
* [数据流](https://docs.molesignal.com/zh-Hans/streams.md)
* [流水线](https://docs.molesignal.com/zh-Hans/pipelines)
* [跨信号关联](https://docs.molesignal.com/zh-Hans/correlation.md)
* [规划经得起时间的数据流与字段](https://docs.molesignal.com/zh-Hans/best-practices/stream-design.md)


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