OpenTelemetry Exporter

# 1. 功能

通过转换标准 OTLP 协议后,将 DeepFlow 的 Span 数据输送至外部平台,可供外部团队补充和完善自己的可观测性平台。

# 2. Span 简介

在 DeepFlow 内,关于 Span 可以分类为:

  • 应用 Span:使用进程级别的 Trace 框架(Agent/SDK)产生的应用级别的 Span 数据,包括 应用自定义 Span,中间件 Client 埋点 Span,通讯框架等。 这里的 Trace 框架包括但不仅限于:Apache SkyWalking Agent,OpenTelemetry Java Agent 以及其他。
  • 系统 Span:DeepFlow 通过 eBPF 零侵入采集的 Span,覆盖系统调用、应用函数(如 HTTPS)、API Gateway、服务网格 Sidecar。
  • 网络 Span:DeepFlow 通过 BPF 从网络流量中采集的 Span,覆盖 iptables/ipvs/OvS/LinuxBridge 等容器网络组件。

# 3. OTel 相关

关于 OTLP Proto (opens new window) 可以在这里找到,其中关于 Trace 语义约定 (opens new window) 在这里可以看到,Trace 内部 Resource 语义约定 (opens new window)可以在这里看到。

# 4. 配置相关

ingester:
  exporters:
  - protocol: opentelemetry
    enabled: true
    endpoints: [127.0.0.1:4317]  # only support protocol grpc
    data-sources:
    - flow_log.l7_flow_log # only support 'flow_log.l7_flow_log'
    queue-count: 4
    queue-size: 100000
    batch-size: 32
    flush-timeout: 10
    tag-filters:
    export-fields:
    - $tag
    - $metrics
    - $k8s.label
    extra-headers:
      key1: value1
      key2: value2
    export-empty-tag: false
    export-empty-metrics_disabled: false
    enum-translate-to-name-disabled: false
    universal-tag-translate-to-name-disabled: false
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 5. 详细参数说明

字段 类型 必选 描述
protocol string 固定值 opentelemetry
data-sources strings 仅支持 flow_log.l7_flow_log
endpoints strings 远端接收地址, 仅支持 gRPC 协议, 随机选择一个可发送成功的
batch-size int 批次大小,当达到这个数值,成批的发送。默认值: 32
extra-headers map 远端 gRPC 请求的头部字段,比如有效验需求的,可以在这里补充 token 等信息
export-fields strings 建议配置: [$tag, $metrics, $k8s.label]

详细配置参考

# 6. 通用字段对等转换

在 Flow_log 中有套内部逻辑将所有数据按照层级进行分类,在这里的对等转换即为 将分层的 Flow_Log 通用字段转换到标准的 OTel 格式数据。

# 6.1.1 Tracing Info

隶属 OTel 的 Span 相关数据原封不动,其他字段则计入 span.attributes 内。

原始字段名 映射后的位置 映射后的名称 备注说明
x_request_id span.attributes df.span.x_request_id
syscall_trace_id_request span.attributes df.span.syscall_trace_id_request
syscall_trace_id_response span.attributes df.span.syscall_thread_0
syscall_thread_0 span.attributes df.span.syscall_thread_0
syscall_thread_1 span.attributes df.span.syscall_thread_1
syscall_cap_seq_0 span.attributes df.span.syscall_cap_seq_0
syscall_cap_seq_1 span.attributes df.span.syscall_cap_seq_1 备注:

# 6.1.2 Service Info

Service 应用级别信息,全部计入 resource.attributes 内,这里包括应用相关和进程以及线程相关,关于进程及线程相关若有特殊需求,请使用 OTel Processor 进行转换。

原始字段名 映射后的位置 映射后的名称 备注说明
auto_service resource.attributes service.name 标准字段
auto_instance resource.attributes service.instance.id 标准
process_id resource.attributes process.pid 备注:
process_kname resource.attributes thread.name 备注:

# 6.1.3 Flow Info

包括字段: _id,time,flow_id,start_time,end_time,close_type,status,is_new_flow。

原始字段名 映射后的位置 映射后的名称 备注说明
_id resource.attributes df.flow_info.id
time resource.attributes df.flow_info.time
flow_id resource.attributes df.flow_info.flow_id
start_time span.start_time_unix_nano span.start_time_unix_nano 注意时间格式转换,会转换为符合 OTel 的时间
end_time span.end_time_unix_nano span.end_time_unix_nano 注意时间格式转换,会转换为符合 OTel 的时间

# 6.1.4 Capture Info

包括字段:signal_source,agent,nat_source,capture_nic,capture_nic_name,capture_nic_type,observation_point,l2_end,l3_end,has_pcap,nat_real_ip,nat_real_port

原始字段名 映射后的位置 映射后的名称 备注说明
signal_source resource.attributes df.capture_info.signal_source
agent resource.attributes df.capture_info.agent
nat_source resource.attributes df.capture_info.nat_source
capture_nic resource.attributes df.capture_info.capture_nic
capture_nic_name resource.attributes df.capture_info.capture_nic_name
capture_nic_type resource.attributes df.capture_info.capture_nic_type
observation_point resource.attributes df.capture_info.observation_point

# 6.1.5 Universal Tag

包括字段:region,az,host,chost,vpc,l2_vpc,subnet,router,dhcpgw,lb,lb_listener,natgw,pod_cluster,pod_ns,pod_node,pod_ingress,pod_service,pod_group,pod,service,auto_servic,auto_service_type,auto_instance,auto_instance_type

如有需要,请使用 OTel Processor 进行格式转换即可。

原始字段名 映射后的位置 映射后的名称 备注说明
region resource.attributes df.universal_tag.region
az resource.attributes df.universal_tag.az
host resource.attributes df.universal_tag.host
chost resource.attributes df.universal_tag.chost
vpc resource.attributes df.universal_tag.vpc
l2_vpc resource.attributes df.universal_tag.l2_vpc
subnet resource.attributes df.universal_tag.subnet
router resource.attributes df.universal_tag.router
dhcpgw resource.attributes df.universal_tag.dhcpgw
lb resource.attributes df.universal_tag.lb
lb_listener resource.attributes df.universal_tag.lb_listener
natgw resource.attributes df.universal_tag.natgw
pod_cluster resource.attributes df.universal_tag.pod_cluster 按照官方文档定义,这里本应是 k8s.pod_cluster,如有需要可自行转换
pod_ns resource.attributes df.universal_tag.pod_ns 按照官方文档定义,这里本应是 k8s.pod_ns,如有需要可自行转换
pod_node resource.attributes df.universal_tag.pod_node 按照官方文档定义,这里本应是 k8s.pod_node,如有需要可自行转换
pod_ingress resource.attributes df.universal_tag.pod_ingress 按照官方文档定义,这里本应是 k8s.pod_ingress,如有需要可自行转换
pod_service resource.attributes df.universal_tag.pod_service 按照官方文档定义,这里本应是 k8s.pod_service,如有需要可自行转换
pod_group resource.attributes df.universal_tag.pod_group 按照官方文档定义,这里本应是 k8s.pod_group,如有需要可自行转换
pod resource.attributes df.universal_tag.pod 按照官方文档定义,这里本应是 k8s.pod.xxx 语义未明,如有需要可自行转换
pod_cluster resource.attributes df.universal_tag.pod_cluster 按照官方文档定义,这里本应是 k8s.pod_cluster,如有需要可自行转换
service resource.attributes df.universal_tag.service
auto_service resource.attributes df.universal_tag.auto_service
auto_service_type resource.attributes df.universal_tag.auto_service_type
auto_instance resource.attributes df.universal_tag.auto_instance
auto_instance_type resource.attributes df.universal_tag.auto_instance_type

# 6.1.6 Custom Tag

原始字段名 映射后的位置 映射后的名称 备注说明
k8s.labels.xxx resource.attributes df.custom_tag.k8s.labels.xxx 备注:

# 6.1.7 Network Layer

原始字段名 映射后的位置 映射后的名称 备注说明
ip resource.attributes df.network.ip
is_ipv4 resource.attributes df.network.is_ipv4
is_internet resource.attributes df.network.is_internet
protocol resource.attributes. net.transport = ip_(小写后的${protocol}) 标准字段

# 6.1.8 Transport Layer

原始字段名 映射后的位置 映射后的名称 备注说明
client_port resource.attributes df.transport.client_port
server_port resource.attributes df.transport.server_port
tcp_flags_bit resource.attributes df.transport.tcp_flags_bit
syn_seq resource.attributes df.transport.syn_seq
syn_ack_seq resource.attributes df.transport.syn_ack_seq
last_keepalive_seq resource.attributes df.transport.last_keepalive_seq
last_keepalive_ack resource.attributes df.transport.last_keepalive_ack 备注:
req_tcp_seq resource.attributes df.transport.req_tcp_seq
resp_tcp_seq resource.attributes df.transport.resp_tcp_seq

# 6.1.9 Application Layer

原始字段名 映射后的位置 映射后的名称 备注说明
l7_protocol resource.attributes df.application.l7_protocol 字段映射详细说明

# 7. 协议字段对等转换

这里对每种协议特殊字段映射到 OTLP 标准字段内做特殊补充(通用字段请从上面查找):

# 7.1 应用协议附加字段

以下字段针对于各个应用层协议均适用:

原始字段名 映射后的位置 映射后的名称 备注说明
resource.attributes telemetry.sdk.name=deepflow 自定义
resource.attributes telemetry.sdk.version=${当前版本} 自定义
chost_0/pod_node_0 span.attributes net.host.name 标准,先获取chost_x,如果不存在再尝试获取 pod_node_x
chost_1/pod_node_1 span.attributes net.peer.name 标准,先获取chost_x,如果不存在再尝试获取 pod_node_x
client_port span.attributes net.host.port 标准
server_port span.attributes net.peer.port 标准
ip_0 span.attributes net.sock.host.addr 标准
ip_1 span.attributes net.sock.peer.addr 标准
response_status span.status span.status 0:正常 -> Ok 1;服务端异常,客户端异常 -> Error; 不存在->Unset

# 7.2 HTTP 协议簇

# 7.2.1 HTTP

原始字段名 映射后的位置 映射后的名称 备注说明
version span.attributes http.flavor 标准字段
request_type span.attributes http.method 标准字段
request_domain span.attributes net.peer.name 标准字段
request_resource span.attributes df.http.path 自定义
request_id span.attributes df.global.request_id 自定义
response_code span.attributes http.status_code 标准字段
response_exception span.event event.name 标准字段
http_proxy_client span.attributes df.http.proxy_client 自定义
span.name span.name= ${request_type} + ${request_source} 标准字段 中间空格

# 7.2.2 HTTP2

TODO

# 7.3 RPC 协议簇

# 7.3.1 Dubbo

原始字段名 映射后的位置 映射后的名称 备注说明
span.attributes rpc.system=apache_dubbo 标准字段
span.attributes rpc.service=${request_resource} 标准字段
span.attributes rpc.method=${request_type} 标准字段
span.attributes span.name= ${request_source} + "/" + ${request_type} == ${endpoint} 标准字段 优先拼接
response_exception span.event event.name 标准字段
request_domain span.attributes df.dubbo.request_domain 不可获取为 neet.peer.name 作为额外字段即可
version span.attributes df.dubbo.version 自定义
request_id span.attributes df.global.request_id 自定义
response_code span.attributes df.response_code 自定义

# 7.3.2 gRPC

原始字段名 映射后的位置 映射后的名称 备注说明
span.attributes rpc.system=grpc 标准字段
span.attributes rpc.system=${request_resource} 标准字段
span.attributes rpc.system=${request_type} 标准字段
span.attributes span.name= ${request_source} + "/" + ${request_type} == ${endpoint} 标准字段
response_exception span.event event.name 标准字段
version span.attributes http.flavor 标准字段
request_domain span.attributes df.grpc.request_domain 不可获取为 neet.peer.name 作为额外字段即可
request_id span.attributes df.global.request_id 自定义

# 7.3.3 SOFARPC

TODO

# 7.3.4 FastCGI

TODO

# 7.4 SQL 协议簇

# 7.4.1 MySQL

原始字段名 映射后的位置 映射后的名称 备注说明
span.attributes db.system==mysql 标准
span.attributes db.operation=${C/R/U/D} 标准字段
span.attributes db.statement=${request_resource} 标准字段
request_type span.attributes df.mysql.request_type 自定义: db.operation 定义的为 SQL 关键字
response_exception span.event event.name 标准字段
span.name span.name=${C/R/U/D} + ${db} + ${table} 标准字段

# 7.4.2 PostgreSQL

原始字段名 映射后的位置 映射后的名称 备注说明
span.attributes db.system==postgresql 标准
span.attributes db.operation=${C/R/U/D} 标准字段
span.attributes db.statement=${request_resource} 标准字段
request_type span.attributes df.postgresql.request_type 自定义: db.operation 定义的为 SQL 关键字
response_exception span.event event.name 标准字段
span.name span.name=${C/R/U/D} + ${db} + ${table} 标准字段

# 7.5 NoSQL 协议簇

# 7.5.1 Redis

原始字段名 映射后的位置 映射后的名称 备注说明
span.attributes db.system==redis 自定义
span.attributes db.operation=${request_type} 标准字段
span.attributes db.statement=${request_resource} 标准字段
response_exception span.event event.name 标准字段
span.name span.name=${request_type} 标准字段

# 7.5.2 MongoDB

原始字段名 映射后的位置 映射后的名称 备注说明
span.attributes db.system==mongodb 自定义
span.attributes db.operation=${request_type} 标准字段
span.attributes db.statement=${request_resource} 标准字段
response_exception span.event event.name 标准字段
span.name span.name=${request_type} 标准字段

# 7.6 消息队列协议簇

# 7.6.1 Kafka

原始字段名 映射后的位置 映射后的名称 备注说明
span.attributes messaging.system=kafka 标准
span.name span.name=${request_type} 非标准
request_type span.attributes df.kafka.request_type 自定义
request_id span.attributes df.global.request_id 自定义
request_resource span.attributes df.global.request_resource 自定义
request_domain span.attributes df.kafka.request_domain 自定义
response_code span.attributes df.kafka.response_code 自定义
response_exception span.event event.name 标准字段

# 7.6.2 MQTT

原始字段名 映射后的位置 映射后的名称 备注说明
span.attributes messaging.system=mqtt 标准
span.attributes messaging.operation=${request_type} 标准 其中:PUBLISH -> publish, SUBSCRIBE -> process, 其余过滤丢弃
span.name span.name=${request_resource} + " " + ${messaging.operation} 标准。
request_type span.attributes df.mqtt.request_type 自定义
request_resource span.attributes df.mqtt.request_resource 自定义
request_domain span.attributes df.mqtt.request_domain 自定义
response_code span.attributes df.mqtt.response_code 自定义
response_exception span.event event.name 标准字段

# 7.7 网络协议簇

# 7.7.1 DNS

原始字段名 映射后的位置 映射后的名称 备注说明
request_type span.attributes df.dns.request_type 自定义
request_resource span.attributes df.dns.request_resource 自定义
request_id span.attributes df.global.request_id 自定义
response_code span.attributes df.dns.response_code 自定义
response_exception span.event event.name 标准字段
response_result span.attributes df.dns.response_result 自定义