服务接入调用链
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不同