服务接入调用链
1、span上报数据规范
[ { "traceId": "248e23702f488ae0", # 本次请求生成的唯一ID,必须 "id": "248e23702f488ae0", # span id,必须 "name": "nlp_manager", # span名称,必须且长度不得超过120 "parentId":"dd5c414a7b05a07c", # 父span id,若存在必须上报 "timestamp": 1582805450715530, # 开始时间戳(16位),单位us, 必须 "duration": 66251, # 服务耗时,单位us, 必须 "localEndpoint": { # 服务上报节点相关信息 "serviceName": "nlp_manager", # 服务名,必须且长度不得超过50 "ipv4":"127.0.0.1", # 数据上报机器ip "port":5000 # 远程节点服务端口号 }, "remoteEndpoint": { # 服务请求的远程节点相关信息 "serviceName": "nlp_manager", # 远程节点服务名 "ipv4":"127.0.0.1", # 远程节点机器ip "port":5000 # 远程节点服务端口号 }, "kind": "CLIENT", # 表示请求开始与结束的核心注解,调用其他span时建议设置为CLIENT "share": true, # 是否服务间调用的标志位 "debug": true, # 是否在覆盖抽样时保存span标志位 "tags": { # 自定义业务字段 "sn": "579bfb69-40cd-41b3-9c8e-ebefee9e0ce2", #必填,端到端唯一识别sid "client_id": "orion.ovs.client.1514259512471", #必填,设备,业务线区分字段 "enterprise_id": "orion.ovs.entprise.4780726715", #必填,企业id "error": "error_type:error msg", # 必填,异常信息,请严格按照格式上报、type和msg用“:“分割。若存在必须上报 "requestBody": "", # 必填,请求体,json字符串 "responseBody": "" # 必填,响应体,json字符串 # 以下考虑选择上报 "waring": "warning_type:warning msg", # 告警信息 "group_id": "ovs.group.155608592193547", # 行业id "deviceid": "D4A0D013320801U01B", # 设备id "model": "CM-GB01D", # 机器人型号 "proc_id": 8812, # 进程号 "version": "v1.411.0.4", # 服务版本号 "status": "200", # 大小写敏感的字符串,状态 "appName": "keyboard", # 应用名称 "data": "业务信息", # 数据信息,字符串。如数据库sql等关键信息 } } ]
注意
- “client_id”(业务线)在调用链功能中非常重要,建议必传,否则平台统计数据、调用链异常预警功能无法使用;
- “enterprise_id”(企业)字段,在调用链功能中非常重要,建议必传,否则企业筛选功能无法使用;
- “error”(异常信息)字段,在调用链功能中非常重要,若存在异常时建议必传,否则平台统计数据、调用链异常预警功能无法使用;
- “error“字段,请严格按照格式上报**”error_type:error msg”、type和msg用“:“分割,若错位类型为“超时“,请将“error_type“上报为“TimeoutError“,平台将进行解析处理。
2 、服务间数据规范
名称 | 类型 | 示例 | 描述 |
---|---|---|---|
X-B3-Sampled | int | 1 | trace是否采样标志位,默认为1(1:采样 0:不采样) |
X-B3-TraceId | string | 194e025b78bfd2ad | 链路唯一识别id,64或128位16进制随机数 |
X-B3-Flags | int | 0 | 是否为debug标志,默认为0(1:存储, 0:不存储) |
X-B3-SpanId | string | 04420d078b2faf33 | 当前请求的SpanId,被调用的spanId, 64或128位16进制随机数 |
X-B3-ParentSpanId | string | 09068171a94ffb10 | 当前请求的ParentSpanId,调用方的spanId,被调用方的ParentSpanId, 64或128位16进制随机数 |
3 、数据上报补充说明
- 必须上报字段:traceId、id、timestamp、localEndpoint.serviceName、name、duration、sn、parentId(非根span)、tags.error(异常发生时)
- tags中若存在必须上报字段:clientId、enterprise_id、group_id、deviceid、model、error、warning
- 建议上报字段:localEndpoint.ip:建议上报,方便后期定位发生问题的机器
- tags字段说明:tags字段为自定义业务字段,各服务可根据业务需求自定义字段填充到该字段张
- error、warning字段说明:该字段值建议上报字段值以 类型:详细信息(如 timeouterror:查询ES超时) 的格式进行上报,方便依据异常类型进行相关数据分析
- 调用链单条数据统一以JSON数组的方式进行上报,非JSON数组的数据会被过滤
- localEndpoint.serviceName、name建议小写,且serviceName长度不超过50,span长度不超过120
- 日志文件切割不要过于频繁,建议每日切割一次
- 单条日志大小控制在1M以内
- 日志路径规范:
- 调用链日志路径建议:/data/logs/项目名/zipkin.log
- 调用链日志路径建议:/data/logs/项目名/stdlog.log
- NLP标准化日志额外说明:
- duration字段值上报为0的数据,仅在日志链路中展示(如下图左侧),调用链路中不可查(如下图右侧)
4 、数据上报实际样例
[ { "traceId": "272fb415a2babb7c", "name": "orion nlu", "timestamp": 1591685781693110, "duration": 225455, "id": "dd5c414a7b05a07c", "parentId": "7fcc2ef8903b6e12", "localEndpoint": { "ipv4": "10.8.0.49", "serviceName": "orion-ui" }, "remoteEndpoint": { "serviceName": "http://172.16.10.17:10000/" }, "tags": { "client_id": "orion.ovs.client.1542176414891", "deviceid": "L4A0D011319H29U6A7", "enterprise_id": "orion.ovs.entprise.8286818582", "model": "CM-GB01D", "req_src": "ts_src_voice", "requestBody": "小豹小豹", "responseBody": "[{\"sn\": \"579bfb69-40cd-41b3-9c8e-ebefee9e0ce2\", \"query\": \"小豹小豹\", \"asrText\": \"小豹小豹\", \"english_domain\": \"chat\", \"domain\": \"其它\", \"intent\": \"chat\", \"slots\": {}, \"source\": \"mustn\u0027t\", \"skill_response\": {\"response\": {\"outSpeech\": {\"type\": \"text\", \"text\": \"请说吧。\"}}}, \"feed\": {}, \"parameters\": null, \"moduleInfo\": {\"len(ner)\": 52, \"ner\": {\"groupner\": [{\"text\": \"小豹\", \"value\": \"小豹\", \"tag\": \"group_mall_greet_call_word\"}, {\"text\": \"小豹\", \"value\": \"小豹\", \"tag\": \"group_mall_invalid_word\"}, {\"text\": \"小豹小豹\", \"value\": \"小豹小豹\", \"tag\": \"group_mall_greet_call_word\"}]}, \"entity\": {\"groupner\": [{\"text\": \"小豹\", \"value\": \"小豹\", \"tag\": \"group_mall_greet_call_word\"}, {\"text\": \"小豹\", \"value\": \"小豹\", \"tag\": \"group_mall_invalid_word\"}, {\"text\": \"小豹小豹\", \"value\": \"小豹小豹\", \"tag\": \"group_mall_greet_call_word\"}]}}, \"node\": {}, \"current_time\": \"2020-06-09 14:56:21\", \"semantics_flag\": 1, \"skill_nlu\": true}]", "sn": "579bfb69-40cd-41b3-9c8e-ebefee9e0ce2", "status": "200", "type": "Logic" } } ]
5 、Q&A
(1)新chat、新qa等服务数据未写入hive
原因:原调用链数据输出到hive对未上报ip、serviceName、duration、traceId的数据进行了过滤,新chat、新qa等服务因为未上报ip被过滤
解决方式:去除对ip的过滤,保留serviceName、duration、traceId过滤条件(已解决)
(2)调用链前端展示异常
a.新文法k8s测试环境标准化日志数据未被解析到ES
原因:调用链数据要求以JSON数组的方式进行上报,新文法标准化数据因为非JSON数组被过滤
解决方式:已经修改为JSON数组上报,在调用链日志链路中可查(已解决)
b.同一个sid在调用链中对应两个traceId
原因:服务间调用时traceId参数未正确传递或接收
解决方式:服务间调用时正确传递traceId
c.nlp-qa服务同一个链路中span父子关系断层,数据未被解析到ES
原因:未保证数据正常写入ES,解析时过滤了单个span数据长度大于32766字节的数据
解决方式:数据组写es的过滤条件从单个span的大小控制细化到字段级别,对name、localEndpoint.serviceName、remoteEndpoint.serviceName长度超过120的进行截断(已解决)
d.mini业务线部分服务暂时无法上报clientId字段,后期将无法在OB中展示业务线相关的统计结果
e.mini业务线nlp-gateway服务缺失导致nlp-qa、chat等链路中断
原因:已周知,待服务端定位
f.同一个traceId前端展示结果不稳定,部分span存在偶尔丢失现象
原因:多个span上报了相同的spanId,前端展示时会随机展示其中一个span(多个span上报相同spanId是由于go在服务间调用时GRPC框架将client和server span的spanId修改为相同)
解决方式:服务端修改GRPC的日志上报逻辑为服务间调用时client和server span的spanId不同