追踪器
由AWS X-Ray支持的分布式追踪.
全舰队+费用: * 追踪是显示存在的——构建 任意
Tracer在应用程序中启用 X-Ray 活动模式 每个 计算(X-Ray为每张账单) 追踪记录/检索.enabled: false编号Tracer只删除 那个 追踪器的选入; 如果有其它Tracer已经存在, X -Ray 仍然打开整个舰队.
何时使用 : 您需要追踪服务之间的请求流量,调试时空问题,或者可视化服务依赖性. 善于识别瓶颈,理解呼叫链, 并关联到整个建筑街区的失败.
不使用时 : 如果需要结构化的日志输出,请使用 Logging。如果随着时间的推移需要数字测量,请使用 Metrics。 。 。 .
设计与模拟等价细节 : 设计
安装
npm install @aws-blocks/bb-tracer
快速使用
import { Tracer } from '@aws-blocks/bb-tracer';
const tracer = new Tracer(scope, 'my-tracer');
// Wrap an operation in a traced segment
const user = await tracer.startSegment('fetchUser', async (segment) => {
segment.addAnnotation('userId', 'user-123');
const result = await db.get('user-123');
segment.setHttpStatus(200);
return result;
});
// Add root-level annotations (attached to the Lambda facade segment)
tracer.addAnnotation('endpoint', '/api/users');
// Get the current trace ID for log correlation
const traceId = tracer.getTraceId();
API 密码
const tracer = new Tracer(scope, id, options?)
| 方法 | 回返 | 说明 |
|---|---|---|
startSegment(name, fn) | Promise<T> | 在所追踪的子项中设置一个同步函数 。 当 fn 完成或抛出. |
addAnnotation(key, value) | void | 在根部分添加可搜索注释 . |
addMetadata(key, value) | void | 将不可搜索的元数据添加到根段 . |
getTraceId() | string | null | 获取当前日志关联的跟踪ID 。 回返 null 当残疾. |
方法
这个 segment 对象传递到 startSegment'召回:
| 方法 | 说明 |
|---|---|
addAnnotation(key, value) | 添加可搜索注释(字符串、数字或布尔). |
addMetadata(key, value) | 添加不可搜索的元数据( 任何 JSON 序列值) . |
addError(error) | 记录一个错误而不重投 . |
setHttpStatus(statusCode) | 记录 HTTP 响应状态代码 . |
选项
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
enabled | boolean | true | 启用或禁用追踪 。 何时 false, (中文(简体) ), startSegment 仍然执行被包裹的函数. |
samplingRate | number | 1.0 | 0至1之间的采样率. 只影响局部的模拟行为. |
logger | ChildLogger | —— 说 | 内部操作的可选日志。 省略时,会在错误级别创建默认 Logger . |
最佳做法
- 使用
startSegment以包装离散的工作单位( DB 调用、 HTTP 请求、 业务逻辑) - 保持片段名称简短和描述性(例如:,
'fetchUser', (中文(简体) ),'processPayment'(中文(简体) ) - 在 X-Ray 控制台对您想要过滤/搜索的值使用注释
- 使用元数据来获取您不需要搜索的大型或复杂的调试数据
- 保留注释基本值低(避免用户特定值作为注释密钥)
- 使用
AsyncJob为长期工作,而不是追踪巨大的跨度
地方发展
模拟数据持续到磁盘 .bb-data/{fullId}/traces.json 跨 Dev 服务器重启 。 被嵌入的片段被存储为树(子阵列). 擦拭为 rm -rf .bb-data。 。 。 .
模拟器以完整的时间,说明,元数据以及出错数据记录所有本地的痕迹——匹配X-Ray在制作中捕获的形状.
取样
- 当地( mock) : 受控制者控制
samplingRate选项。 价值为0.1意味着当地大约10%的痕迹被记录下来. 默认是1.0(记录一切). - 生产(AWS): 取样由AWS控制台所配置的X-Ray取样规则或通过CDK控制. 这个
samplingRatex-Ray的本土采样基础设施优先.
定价
- 自由等级 : 每月记录100 000个痕迹,每月扫描/取回100万个痕迹
- 超过自由级 : 记录每百万分之5.00分,每百万分之50分,检索或扫描
- Lambda 守护进程 : 没有附加电荷 — X- Ray 守护进程已建入 Lambda 运行时间
- 成本驱动器: 追溯引用数×采样率
- 成本优化: 配置 X-Ray 采样规则,以保持记录-跟踪量(和成本)在高通量函数(
samplingRate选项只影响本地模拟,而不是生产) - 残废( E)
enabled: false: 零X射线成本——没有记录或发送痕迹
另见
- 类型 - 共同类型定义(
Segment, (中文(简体) ),TracerOptions, (中文(简体) ),AnnotationValue(中文(简体) )