跳到内容 跳到主导航 跳到页脚

服务接入调用链

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-Sampledint1trace是否采样标志位,默认为1(1:采样 0:不采样)
X-B3-TraceIdstring194e025b78bfd2ad链路唯一识别id,64或128位16进制随机数
X-B3-Flagsint0是否为debug标志,默认为0(1:存储, 0:不存储)
X-B3-SpanIdstring04420d078b2faf33当前请求的SpanId,被调用的spanId, 64或128位16进制随机数
X-B3-ParentSpanIdstring09068171a94ffb10当前请求的ParentSpanId,调用方的spanId,被调用方的ParentSpanId, 64或128位16进制随机数

3 、数据上报补充说明

  1. 必须上报字段:traceId、id、timestamp、localEndpoint.serviceName、name、duration、sn、parentId(非根span)、tags.error(异常发生时)
  2. tags中若存在必须上报字段:clientId、enterprise_id、group_id、deviceid、model、error、warning
  3. 建议上报字段:localEndpoint.ip:建议上报,方便后期定位发生问题的机器
  4. tags字段说明:tags字段为自定义业务字段,各服务可根据业务需求自定义字段填充到该字段张
  5. error、warning字段说明:该字段值建议上报字段值以 类型:详细信息(如 timeouterror:查询ES超时) 的格式进行上报,方便依据异常类型进行相关数据分析
  6. 调用链单条数据统一以JSON数组的方式进行上报,非JSON数组的数据会被过滤
  7. localEndpoint.serviceName、name建议小写,且serviceName长度不超过50,span长度不超过120
  8. 日志文件切割不要过于频繁,建议每日切割一次
  9. 单条日志大小控制在1M以内
  10. 日志路径规范:
    1. 调用链日志路径建议:/data/logs/项目名/zipkin.log
    2. 调用链日志路径建议:/data/logs/项目名/stdlog.log
  11. NLP标准化日志额外说明:
  12. duration字段值上报为0的数据,仅在日志链路中展示(如下图左侧),调用链路中不可查(如下图右侧)
image.png

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等链路中断

原因:已周知,待服务端定位

image.png

f.同一个traceId前端展示结果不稳定,部分span存在偶尔丢失现象

image.png
image.png

原因:多个span上报了相同的spanId,前端展示时会随机展示其中一个span(多个span上报相同spanId是由于go在服务间调用时GRPC框架将client和server span的spanId修改为相同)

解决方式:服务端修改GRPC的日志上报逻辑为服务间调用时client和server span的spanId不同

这篇文章是否有帮助?

0