Skip to content
体验新版
项目
组织
正在加载...
登录
切换导航
打开侧边栏
润土的好友猹
SkyWalking
提交
d6a6fe10
S
SkyWalking
项目概览
润土的好友猹
/
SkyWalking
与 Fork 源项目一致
Fork自
apache / SkyWalking
通知
9
Star
0
Fork
0
代码
文件
提交
分支
Tags
贡献者
分支图
Diff
Issue
0
列表
看板
标记
里程碑
合并请求
0
Wiki
0
Wiki
分析
仓库
DevOps
项目成员
Pages
S
SkyWalking
项目概览
项目概览
详情
发布
仓库
仓库
文件
提交
分支
标签
贡献者
分支图
比较
Issue
0
Issue
0
列表
看板
标记
里程碑
合并请求
0
合并请求
0
Pages
分析
分析
仓库分析
DevOps
Wiki
0
Wiki
成员
成员
收起侧边栏
关闭侧边栏
动态
分支图
创建新Issue
提交
Issue看板
体验新版 GitCode,发现更多精彩内容 >>
提交
d6a6fe10
编写于
11月 06, 2017
作者:
wu-sheng
浏览文件
操作
浏览文件
下载
电子邮件补丁
差异文件
Finish cn documents
上级
b7293702
变更
13
显示空白变更内容
内联
并排
Showing
13 changed file
with
849 addition
and
16 deletion
+849
-16
docs/README_ZH.md
docs/README_ZH.md
+14
-16
docs/cn/Application-toolkit-CN.md
docs/cn/Application-toolkit-CN.md
+11
-0
docs/cn/Application-toolkit-log4j-1.x-CN.md
docs/cn/Application-toolkit-log4j-1.x-CN.md
+21
-0
docs/cn/Application-toolkit-log4j-2.x-CN.md
docs/cn/Application-toolkit-log4j-2.x-CN.md
+19
-0
docs/cn/Application-toolkit-logback-1.x-CN.md
docs/cn/Application-toolkit-logback-1.x-CN.md
+22
-0
docs/cn/Application-toolkit-trace-CN.md
docs/cn/Application-toolkit-trace-CN.md
+20
-0
docs/cn/FAQ/Too-many-gRPC-logs-CN.md
docs/cn/FAQ/Too-many-gRPC-logs-CN.md
+7
-0
docs/cn/FAQ/Why-have-traces-no-others-CN.md
docs/cn/FAQ/Why-have-traces-no-others-CN.md
+11
-0
docs/cn/How-to-build-CN.md
docs/cn/How-to-build-CN.md
+18
-0
docs/cn/How-to-communicate-with-the-collector-CN.md
docs/cn/How-to-communicate-with-the-collector-CN.md
+352
-0
docs/cn/Plugin-Development-Guide-CN.md
docs/cn/Plugin-Development-Guide-CN.md
+276
-0
docs/cn/Skywalking-3-Cross-Process-Propagation-Headers-Protocol-CN.md
...alking-3-Cross-Process-Propagation-Headers-Protocol-CN.md
+61
-0
docs/cn/skywalking-opentracing-CN.md
docs/cn/skywalking-opentracing-CN.md
+17
-0
未找到文件。
docs/README_ZH.md
浏览文件 @
d6a6fe10
...
...
@@ -2,7 +2,7 @@
[
![EN doc
](
https://img.shields.io/badge/document-English-blue.svg
)
](README.md)
*
[
项目简介
](
/README_ZH.md
)
*
[
快速入门
](
cn/Quick-start-
chn
.md
)
*
[
快速入门
](
cn/Quick-start-
CN
.md
)
*
[
部署单机collector
](
cn/Deploy-collector-in-standalone-mode-CN.md
)
*
[
部署集群collector
](
cn/Deploy-collector-in-cluster-mode-CN.md
)
*
[
部署探针Agent
](
cn/Deploy-skywalking-agent-CN.md
)
...
...
@@ -12,24 +12,22 @@
*
APM相关介绍资料
*
[
APM简介(百度百科)
](
http://baike.baidu.com/link?url=HizLjnUrwvXqPQ4fZH_MA81MA7R_sE-kpdEIfuUHf-yNHhPiEkA97_7FshVR6raiZL6pvbChTZSIgrC1lY6lhq.md
)
*
[
OpenTracing中文版
](
https://github.com/opentracing-contrib/opentracing-specification-zh.md
)
*
[
JVM内存管理与GC
](
cn/Memory-Usage-and-GC-info.md
)
*
Application Toolkit,应用程序工具包
*
[
概述
](
cn/
sky-walking-application-toolkit-chn
.md
)
*
[
OpenTracing Tracer
](
cn/skywalking-opentracing-
chn
.md
)
*
[
概述
](
cn/
Application-toolkit-CN
.md
)
*
[
OpenTracing Tracer
](
cn/skywalking-opentracing-
CN
.md
)
*
日志组件
*
[
log4j组件
](
cn/
sky-walking-application-toolkit-log4j-1.x-chn
.md
)
*
[
log4j2组件
](
cn/
sky-walking-application-toolkit-log4j-2.x-chn
.md
)
*
[
logback组件
](
cn/
sky-walking-application-toolkit-logback-1.x-chn
.md
)
*
[
Trace
](
cn/
sky-walking-application-toolkit-trace-chn
.md
)
*
[
log4j组件
](
cn/
Application-toolkit-log4j-1.x-CN
.md
)
*
[
log4j2组件
](
cn/
Application-toolkit-log4j-2.x-CN
.md
)
*
[
logback组件
](
cn/
Application-toolkit-logback-1.x-CN
.md
)
*
[
Trace
](
cn/
Application-toolkit-trace-CN
.md
)
*
测试用例
*
[
单插件测试用例
](
cn/Test-Cases-chn.md
)
*
[
测试应用集群
](
cn/2.0-Demo-Application-Cluster-chn.md
)
*
[
插件测试
](
https://github.com/SkywalkingTest/agent-integration-test-report
)
*
[
Java 探针性能测试
](
https://skywalkingtest.github.io/Agent-Benchmarks/
)
*
开发指南
*
[
工程编译指南
](
cn/How-to-build.md
)
*
[
插件开发指南
](
cn/Plugin-Development-Guide.md
)
*
[
工程编译指南
](
cn/How-to-build
-CN
.md
)
*
[
插件开发指南
](
cn/Plugin-Development-Guide
-CN
.md
)
*
[
跨进程追踪上下文传递协议
](
cn/Skywalking-3-Cross-Process-Propagation-Headers-Protocol-CN.md
)
*
[
探针与Collector间网络协议,v3.2+
](
cn/How-to-communicate-with-the-collector
%3F
.md
)
*
[
探针与Collector间网络协议,v3.2+
](
cn/How-to-communicate-with-the-collector
-CN
.md
)
*
FAQ
*
[
探针性能测试报告
](
https://skywalkingtest.github.io/Agent-Benchmarks/.md
)
*
[
Trace查询有数据,但是没有拓扑图和JVM数据?
](
cn/Trace%E6%9F%A5%E8%AF%A2%E6%9C%89%E6%95%B0%E6%8D%AE%EF%BC%8C%E4%BD%86%E6%98%AF%E6%B2%A1%E6%9C%89%E6%8B%93%E6%89%91%E5%9B%BE%E5%92%8CJVM%E6%95%B0%E6%8D%AE.md
)
*
[
加载探针,Console被GRPC日志刷屏
](
cn/加载探针,Console被GRPC日志刷屏.md
)
\ No newline at end of file
*
[
Trace查询有数据,但是没有拓扑图和JVM数据?
](
cn/FAQ/Why-have-traces-no-others-CN.md
)
*
[
加载探针,Console被GRPC日志刷屏
](
cn/FAQ/Too-many-gRPC-logs-CN.md
)
\ No newline at end of file
docs/cn/Application-toolkit-CN.md
0 → 100644
浏览文件 @
d6a6fe10
# 什么是sky-walking应用程序工具包?
Sky-walking应用程序工具包是一系列的类库,有skywalking团队提供。通过这些类库,你可以在你的应用程序内,访问sky-walking的一些内部信息.
_**最为重要的是**_
, 即使你移除skywalking的探针,或者不激活探针,这些类库也不会对应用程序有任何影响,也不会影响性能.
工具包提供以下核心能力
1.
将追踪信息和log组件集成,如log4j, log4j2 和 logback
1.
兼容CNCF OpenTracing标准的手动埋点
1.
使用Skywalking专有的标注和交互性API
_**注意**: 所有的应用程序工具包都托管在bitray.com/jcenter. 同时请确保你使用的开发工具包和skywalking的agent探针版本一致._
\ No newline at end of file
docs/cn/Application-toolkit-log4j-1.x-CN.md
0 → 100644
浏览文件 @
d6a6fe10
*
使用 maven 和 gradle 依赖相应的工具包
```
xml
<dependency>
<groupId>
org.skywalking
</groupId>
<artifactId>
apm-toolkit-log4j-1.x
</artifactId>
<version>
{project.release.version}
</version>
</dependency>
```
[
![Download
](
https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-1.x/images/download.svg
)
](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-1.x/_latestVersion)
*
配置layout
```
properties
log4j.appender.CONSOLE.layout
=
org.skywalking.apm.toolkit.log.log4j.v1.x.TraceIdPatternLayout
```
*
在
`layout.ConversionPattern`
中设置
`%T`
来展示traceid ( 在 2.0-2016版本中, 你应该设置为 %x,
[
为什么改变配置,请参考相关issue?
](
https://github.com/wu-sheng/sky-walking/issues/77
)
)
```
properties
log4j.appender.CONSOLE.layout.ConversionPattern
=
%d [%T] %-5p %c{1}:%L - %m%n
```
*
当你使用
`-javaagent`
参数激活sky-walking的探针, 如果当前上下文中存在traceid,log4j将在输出
**traceId**
。如果探针没有被激活,将输出
`TID: N/A`
.
\ No newline at end of file
docs/cn/Application-toolkit-log4j-2.x-CN.md
0 → 100644
浏览文件 @
d6a6fe10
*
使用 maven 和 gradle 依赖相应的工具包
```
xml
<dependency>
<groupId>
org.skywalking
</groupId>
<artifactId>
apm-toolkit-log4j-2.x
</artifactId>
<version>
{project.release.version}
</version>
</dependency>
```
[
![Download
](
https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-2.x/images/download.svg
)
](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-2.x/_latestVersion)
*
在log4j2.xml中的pattern 配置节,配置
`[%traceId]`
```
xml
<Appenders>
<Console
name=
"Console"
target=
"SYSTEM_OUT"
>
<PatternLayout
pattern=
"%d [%traceId] %-5p %c{1}:%L - %m%n"
/>
</Console>
</Appenders>
```
*
当你使用
`-javaagent`
参数激活sky-walking的探针, 如果当前上下文中存在traceid,log4j2将在输出
**traceId**
。如果探针没有被激活,将输出
`TID: N/A`
.
\ No newline at end of file
docs/cn/Application-toolkit-logback-1.x-CN.md
0 → 100644
浏览文件 @
d6a6fe10
*
使用 maven 和 gradle 依赖相应的工具包
```
xml
<dependency>
<groupId>
org.skywalking
</groupId>
<artifactId>
apm-toolkit-logback-1.x
</artifactId>
<version>
{project.release.version}
</version>
</dependency>
```
[
![Download
](
https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-2.x/images/download.svg
)
](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-log4j-2.x/_latestVersion)
*
在logback.xml中的
`Pattern`
配制节中,设置
`%tid`
```
xml
<appender
name=
"STDOUT"
class=
"ch.qos.logback.core.ConsoleAppender"
>
<encoder
class=
"ch.qos.logback.core.encoder.LayoutWrappingEncoder"
>
<layout
class=
"org.skywalking.apm.toolkit.log.logback.v1.x.TraceIdPatternLogbackLayout"
>
<Pattern>
%d{yyyy-MM-dd HH:mm:ss.SSS} [%tid] [%thread] %-5level %logger{36} -%msg%n
</Pattern>
</layout>
</encoder>
</appender>
```
*
当你使用
`-javaagent`
参数激活sky-walking的探针, 如果当前上下文中存在traceid,logback将在输出
**traceId**
。如果探针没有被激活,将输出
`TID: N/A`
.
\ No newline at end of file
docs/cn/Application-toolkit-trace-CN.md
0 → 100644
浏览文件 @
d6a6fe10
*
使用 maven 和 gradle 依赖相应的工具包
```
xml
<dependency>
<groupId>
org.skywalking
</groupId>
<artifactId>
apm-toolkit-trace
</artifactId>
<version>
${skywalking.version}
</version>
</dependency>
```
[
![Download
](
https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-trace/images/download.svg
)
](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-trace/_latestVersion)
*
随时使用
`TraceContext.traceId()`
API,在应用程序的任何地方获取traceId.
```
java
import
org.skywalking.apm.toolkit.trace.TraceContext
;
...
modelAndView
.
addObject
(
"traceId"
,
TraceContext
.
traceId
());
```
_示例代码,仅供参考_
*
对任何需要追踪的方法,使用@Trace标注,则此方法会被加入到追踪链中。
\ No newline at end of file
docs/cn/FAQ/Too-many-gRPC-logs-CN.md
0 → 100644
浏览文件 @
d6a6fe10
**现象**
:
1.
加载探针并启动应用
2.
Console中被GRPC日志刷屏
**原因**
:Skywalking采用了GRPC框架发送数据,GRPC框架读取log的配置文件进行日志输出。
**解决方法**
: 在log的配置文件中添加对
`org.skywalking.apm.dependencies`
包的过滤
docs/cn/FAQ/Why-have-traces-no-others-CN.md
0 → 100644
浏览文件 @
d6a6fe10
现象:
-
Agent和Collector正常工作,没有异常日志
-
已经对系统进行过访问,Trace查询有数据
-
UI除Trace查询页面外,其他页面无数据
-
**页面顶部时间轴和当前系统时间不一致**
原因:
被监控系统所在的操作系统,未设置为当前时区,导致统计数据汇集时间点偏差。
解决方法:
设置操作系统时间时区
\ No newline at end of file
docs/cn/How-to-build-CN.md
0 → 100644
浏览文件 @
d6a6fe10
## 工程编译指南
本文档用于指导开发者,在本地开发环境中编译工程。
### 前言
因为工程结构和代码依赖会随版本变化,如果读者熟悉travis-ci,则可直接参考
[
.travis.yml
](
https://github.com/wu-sheng/sky-walking/blob/master/.travis.yml
)
### 编译步骤
1.
准备环境,jdk8,Maven
1.
执行
`mvn clean package`
### 在IntelliJ IDEA中编译工程
上述步骤在命令行中,能够很好的编译工程,但导入到编译器中的工程依然会有一些报错,我们需要进行几步简单的操作。
1.
在IntelliJ Terminal中,执行
`mvn compile -Dmaven.test.skip=true`
进行编译
1.
设置gRPC的自动生成代码目录,为源码目录
-
**apm-network/target/generated--sources/protobuf**
目录下的
`grpc-java`
和
`java`
目录
-
**apm-collector/apm-collector-stream/target/protobuf**
目录下的
`grpc-java`
和
`java`
目录
注:从3.2开始,网络通讯协议引入GRPC,所以增加上述的步骤
docs/cn/How-to-communicate-with-the-collector-CN.md
0 → 100644
浏览文件 @
d6a6fe10
# 探针与Collector间通讯协议
## 前言
这篇文章主要介绍3.2版本的Collector对外提供的服务协议。一般情况下,使用者和开发者都无需了解此协议细节。但是在庞大的开源生态中,我们已经收到过多次有公司或个人的使用案例,使用自己的非Java探针(PHP,GO等)探针,接入我们的Collector进行数据分析和监控。
## 协议类型
Collector从3.2开始,对外同时提供gRPC和HTTP RESTFul两种类型的协议。从效率上,我们推荐使用gRPC
# gRPC服务
本章节,描述官方java探针使用的网络协议
## Collector服务发现协议
### 简介
**Collector服务发现协议是探针启动时,第一个调用的服务。**
通过服务,查找对应的gRPC服务地址与端口列表,并在由客户端选择其中任意一个作为服务端。此服务需周期性调用,确保探针本地的服务端口列表是准确有效的。
### 协议类型
HTTP GET
### 协议内容
-
请求
GET操作:http://collectorIp:port/agentstream/grpc 。 其中
`/agentstream/grpc`
是默认值,如需修改,需要参考collector相关配置。
-
返回
JSON数组,数组的每个元素,为一个有效的gRPC服务地址。
```
json
[
"ip address1:port1"
,
"ip address2:port2"
,
"ip address3:port3"
]
```
## 应用注册服务
### 简介
应用注册服务,是将手动设计的applicationCode,以及ip:port沟通的服务地址,转换成数字的服务。此服务会在后续的传输过程中,有效降低网络带宽需求。
### 协议类型
gRPC服务
### 协议内容
https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/ApplicationRegisterService.proto
```
proto
syntax
=
"proto3"
;
option
java_multiple_files
=
true
;
option
java_package
=
"org.skywalking.apm.network.proto"
;
import
"KeyWithIntegerValue.proto"
;
//register service for ApplicationCode, this service is called when service starts.
service
ApplicationRegisterService
{
rpc
register
(
Application
)
returns
(
ApplicationMapping
)
{
}
}
message
Application
{
repeated
string
applicationCode
=
1
;
}
message
ApplicationMapping
{
repeated
KeyWithIntegerValue
application
=
1
;
}
```
-
首次调用时,applicationCode为客户端设置的应用名(显示在拓扑图和应用列表上的名字)。之后随着追踪过程,会上报此应用相关的周边服务的
`ip:port`
地址列表
-
KeyWithIntegerValue 返回,key为上报的applicationCode和ip:port地址,value为对应的id。applicationCode对应的返回id,在后续协议中,被称为applicationId。
-
此服务按需调用,本地无法找到ip:port对应的id时,可异步发起调用。
-
获取applicationId的操作是必选。
-
获取ip:port对应的id是可选,但是完成id设置,会有效提高collector处理效率,降低网络消耗。
## 应用实例发现服务
### 简介
应用实例发现服务存在三个子服务,分别是实例注册服务,实例心跳服务,实例注册重连服务。这三个服务负责获取和保持应用实例在线的功能。
### 协议类型
gRPC服务
### 实例注册服务
https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L11-L12
```
proto
service
InstanceDiscoveryService
{
rpc
register
(
ApplicationInstance
)
returns
(
ApplicationInstanceMapping
)
{
}
}
message
ApplicationInstance
{
int32
applicationId
=
1
;
string
agentUUID
=
2
;
int64
registerTime
=
3
;
OSInfo
osinfo
=
4
;
}
message
OSInfo
{
string
osName
=
1
;
string
hostname
=
2
;
int32
processNo
=
3
;
repeated
string
ipv4s
=
4
;
}
message
ApplicationInstanceMapping
{
int32
applicationId
=
1
;
int32
applicationInstanceId
=
2
;
}
```
-
agentUUID 由探针生成,需保持唯一性,推荐使用UUID算法。并在应用重启前保持不变
-
applicationId 由
**应用注册服务**
获取。
-
服务端返回应用实例id,applicationInstanceId 。后续上报服务使用实例id标识。
### 实例心跳服务
https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L14-L15
```
proto
service
InstanceDiscoveryService
{
rpc
heartbeat
(
ApplicationInstanceHeartbeat
)
returns
(
Downstream
)
{
}
}
message
ApplicationInstanceHeartbeat
{
int32
applicationInstanceId
=
1
;
int64
heartbeatTime
=
2
;
}
```
-
心跳服务每分钟上报一次。
-
如一分钟内有segment数据上报,则可不必上报心跳。
### 实例注册重连服务
https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L17-L18
```
proto
service
InstanceDiscoveryService
{
rpc
registerRecover
(
ApplicationInstanceRecover
)
returns
(
Downstream
)
{
}
}
message
ApplicationInstanceRecover
{
int32
applicationId
=
1
;
int32
applicationInstanceId
=
2
;
int64
registerTime
=
3
;
OSInfo
osinfo
=
4
;
}
```
-
应用重连服务于
**应用注册服务**
类似,在gRPC发生重连,并再次连接成功后发送。需包含通过
**应用注册服务**
获取的applicationInstanceId。
## 服务名注册发现服务
### 简介
服务名注册发现服务,是将应用内的服务名(operationName)替换为id的服务。
### 协议类型
gRPC服务
### 协议内容
https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/DiscoveryService.proto#L53-L74
```
proto
//discovery service for ServiceName by Network address or application code
service
ServiceNameDiscoveryService
{
rpc
discovery
(
ServiceNameCollection
)
returns
(
ServiceNameMappingCollection
)
{
}
}
message
ServiceNameCollection
{
repeated
ServiceNameElement
elements
=
1
;
}
message
ServiceNameMappingCollection
{
repeated
ServiceNameMappingElement
elements
=
1
;
}
message
ServiceNameMappingElement
{
int32
serviceId
=
1
;
ServiceNameElement
element
=
2
;
}
message
ServiceNameElement
{
string
serviceName
=
1
;
int32
applicationId
=
2
;
}
```
-
可选服务,可有效降低网络消耗,推荐实现。注意,由于部分应用存在URI中夹带参数的情况,请注意限制探针内的缓存容量,防止内存溢出。
-
ServiceNameElement中,applicationId为当前applicationCode对应的id。serviceName一般为对应span的operationName
## JVM指标上报服务
### 简介
上报当前实例的JVM信息,每秒上报一次。
### 协议类型
gRPC服务
### 协议内容
https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/proto/JVMMetricsService.proto
```
proto
syntax
=
"proto3"
;
option
java_multiple_files
=
true
;
option
java_package
=
"org.skywalking.apm.network.proto"
;
import
"Downstream.proto"
;
service
JVMMetricsService
{
rpc
collect
(
JVMMetrics
)
returns
(
Downstream
)
{
}
}
message
JVMMetrics
{
repeated
JVMMetric
metrics
=
1
;
int64
applicationInstanceId
=
2
;
}
message
JVMMetric
{
int64
time
=
1
;
CPU
cpu
=
2
;
repeated
Memory
memory
=
3
;
repeated
MemoryPool
memoryPool
=
4
;
repeated
GC
gc
=
5
;
}
message
CPU
{
double
usagePercent
=
2
;
}
message
Memory
{
bool
isHeap
=
1
;
int64
init
=
2
;
int64
max
=
3
;
int64
used
=
4
;
int64
committed
=
5
;
}
message
MemoryPool
{
PoolType
type
=
1
;
bool
isHeap
=
2
;
int64
init
=
3
;
int64
max
=
4
;
int64
used
=
5
;
int64
commited
=
6
;
}
enum
PoolType
{
CODE_CACHE_USAGE
=
0
;
NEWGEN_USAGE
=
1
;
OLDGEN_USAGE
=
2
;
SURVIVOR_USAGE
=
3
;
PERMGEN_USAGE
=
4
;
METASPACE_USAGE
=
5
;
}
message
GC
{
GCPhrase
phrase
=
1
;
int64
count
=
2
;
int64
time
=
3
;
}
enum
GCPhrase
{
NEW
=
0
;
OLD
=
1
;
}
```
## TraceSegment上报服务
### 简介
上报调用链信息
### 协议类型
gRPC服务
### 协议内容
```
proto
syntax
=
"proto3"
;
option
java_multiple_files
=
true
;
option
java_package
=
"org.skywalking.apm.network.proto"
;
import
"Downstream.proto"
;
import
"KeyWithStringValue.proto"
;
service
TraceSegmentService
{
rpc
collect
(
stream
UpstreamSegment
)
returns
(
Downstream
)
{
}
}
message
UpstreamSegment
{
repeated
UniqueId
globalTraceIds
=
1
;
bytes
segment
=
2
;
// the byte array of TraceSegmentObject
}
message
UniqueId
{
repeated
int64
idParts
=
1
;
}
message
TraceSegmentObject
{
UniqueId
traceSegmentId
=
1
;
repeated
TraceSegmentReference
refs
=
2
;
repeated
SpanObject
spans
=
3
;
int32
applicationId
=
4
;
int32
applicationInstanceId
=
5
;
}
message
TraceSegmentReference
{
RefType
refType
=
1
;
UniqueId
parentTraceSegmentId
=
2
;
int32
parentSpanId
=
3
;
int32
parentApplicationInstanceId
=
4
;
string
networkAddress
=
5
;
int32
networkAddressId
=
6
;
string
entryServiceName
=
7
;
int32
entryServiceId
=
8
;
string
parentServiceName
=
9
;
int32
parentServiceId
=
10
;
}
message
SpanObject
{
int32
spanId
=
1
;
int32
parentSpanId
=
2
;
int64
startTime
=
3
;
int64
endTime
=
4
;
int32
operationNameId
=
5
;
string
operationName
=
6
;
int32
peerId
=
7
;
string
peer
=
8
;
SpanType
spanType
=
9
;
SpanLayer
spanLayer
=
10
;
int32
componentId
=
11
;
string
component
=
12
;
bool
isError
=
13
;
repeated
KeyWithStringValue
tags
=
14
;
repeated
LogMessage
logs
=
15
;
}
enum
RefType
{
CrossProcess
=
0
;
CrossThread
=
1
;
}
enum
SpanType
{
Entry
=
0
;
Exit
=
1
;
Local
=
2
;
}
enum
SpanLayer
{
Database
=
0
;
RPCFramework
=
1
;
Http
=
2
;
MQ
=
3
;
}
message
LogMessage
{
int64
time
=
1
;
repeated
KeyWithStringValue
data
=
2
;
}
```
-
UniqueId为segment或者globalTraceId的数字表示。由3个long组成,1)applicationInstanceId,2)当前线程id,3)当前时间戳
*
10000 + seq(0-10000自循环)
-
Span的数据,请参考
[
插件开发规范
](
https://github.com/OpenSkywalking/skywalking/wiki/Plugin-Development-Guide
)
-
以下id和名称根据注册返回结果,优先上报id,无法获取id时,再上传name。参考之前的应用和服务注册章节。
-
operationNameId/operationName
-
networkAddress/networkAddressId
-
entryServiceName/entryServiceId
-
parentServiceName/parentServiceId
-
peerId/peer
-
componentId为默认支持的插件id,非官方支持,需传输名称或修改服务端源代码。
[
官方组件列表
](
https://github.com/OpenSkywalking/skywalking/blob/master/apm-network/src/main/java/org/skywalking/apm/network/trace/component/ComponentsDefine.java
)
docs/cn/Plugin-Development-Guide-CN.md
0 → 100644
浏览文件 @
d6a6fe10
## 插件开发指南
本文档描述
[
v3.2+
](
https://github.com/OpenTracing/skywalking/releases
)
插件开发方法、使用的API,以及注意事项。3.2版本将在2017 CNUTCon之前发布。
### 核心概念
#### 一. Span
Span是追踪系统中的通用概念(有时候被翻译成埋点),关于Span的定义,请参考
[
OpenTracing 中文版
](
https://github.com/opentracing-contrib/opentracing-specification-zh/blob/master/specification.md#opentracing数据模型
)
。
sky-walking作为OpenTracing的支持者,在核心实现中,与标准有较高的相似度。
我们将span分为三类:
1.
1 EntrySpan
EntrySpan代表一个服务的提供方,即,服务端的入口点。它是每个Java对外服务的入口点。如:Web服务入口就是一个EntrySpan。
1.
2 LocalSpan
LocalSpan代表一个普通的Span,代表任意一个本地逻辑块(或方法)
1.
3 ExitSpan
ExitSpan也可以称为LeafSpan(sky-walking的早期版本中的称呼),代表了一个远程服务的客户端调用。如:一次JDBC调用。
#### 二. ContextCarrier
分布式追踪要解决的一个重要问题,就是跨进程的问题,ContextCarrier的概念就是为了解决这种场景。
当发生一次
**A->B**
的网络调用时:
1.
需要在客户端生成(inject操作)ContextCarrier,并序列化成String
1.
将这个String加入RPC调用的正文(或HEAD)中,传递到服务端
1.
服务端收到后,转换为新的ContextCarrier
1.
通过提取操作(extract操作)建立关联
以HTTPComponent调用Tomcat为例:
1.
客户端(HTTPComponent端)
```
java
span
=
ContextManager
.
createExitSpan
(
"/span/operation/name"
,
contextCarrier
,
"ip:port"
);
CarrierItem
next
=
contextCarrier
.
items
();
while
(
next
.
hasNext
())
{
next
=
next
.
next
();
//向HTTP或者其他RPC HEAD中设置上下文
heads
.
put
(
next
.
getHeadKey
(),
next
.
getHeadValue
());
}
```
2.
服务端(Tomcat端)
```
java
ContextCarrier
contextCarrier
=
new
ContextCarrier
();
CarrierItem
next
=
contextCarrier
.
items
();
while
(
next
.
hasNext
())
{
next
=
next
.
next
();
//从HTTP或者其他RPC HEAD中,根据指定的KEY,提取上下文
next
.
setHeadValue
(
heads
.
get
(
next
.
getHeadKey
()));
}
span
=
ContextManager
.
createEntrySpan
(
“
/
span
/
operation
/
name
”
,
contextCarrier
);
```
#### 三. ContextSnapshot
除了跨进程的RPC调用,另外一种追踪的常见场景是跨线程。跨线程和跨进程有很高的相似度,都是需要完成上下文的传递工作。所以ContextSnapshot具有和ContextCarrier十分类似的API风格。
当发生一次
**A->B**
的跨线程调用时:
1.
需要在A线程中通过ContextManager#capture操作生成ContextSnapshot对象实例
1.
将这个ContextSnapshot对象传递到B线程中
1.
B线程通过ContextManager#continued操作完成上下文传递
### 核心API
#### 一. ContextManager
ContextManager提供了追踪相关操作的主入口
1.
创建EntrySpan
```
java
public
static
AbstractSpan
createEntrySpan
(
String
operationName
,
ContextCarrier
carrier
)
```
通过服务名、跨进程传递的ContextCarrier,创建EntrySpan。
2.
创建LocalSpan
```
java
public
static
AbstractSpan
createLocalSpan
(
String
operationName
)
```
根据服务名(或方法名),创建LocalSpan
3.
创建ExitSpan
```
java
public
static
AbstractSpan
createExitSpan
(
String
operationName
,
ContextCarrier
carrier
,
String
remotePeer
)
```
根据服务名,跨进程传递的ContextCarrier(空容器)和远端服务地址(IP、主机名、域名 + 端口),创建ExitSpan
#### 二. AbstractSpan
AbstractSpan提供了Span内部,进行操作的各项API
```
java
/**
* Set the component id, which defines in {@link org.skywalking.apm.network.trace.component.ComponentsDefine}
*
* @param component
* @return the span for chaining.
*/
AbstractSpan
setComponent
(
Component
component
);
/**
* Only use this method in explicit instrumentation, like opentracing-skywalking-bridge.
* It it higher recommend don't use this for performance consideration.
*
* @param componentName
* @return the span for chaining.
*/
AbstractSpan
setComponent
(
String
componentName
);
AbstractSpan
setLayer
(
SpanLayer
layer
);
/**
* Set a key:value tag on the Span.
*
* @return this Span instance, for chaining
*/
AbstractSpan
tag
(
String
key
,
String
value
);
/**
* Record an exception event of the current walltime timestamp.
*
* @param t any subclass of {@link Throwable}, which occurs in this span.
* @return the Span, for chaining
*/
AbstractSpan
log
(
Throwable
t
);
AbstractSpan
errorOccurred
();
/**
* Record an event at a specific timestamp.
*
* @param timestamp The explicit timestamp for the log record.
* @param event the events
* @return the Span, for chaining
*/
AbstractSpan
log
(
long
timestamp
,
Map
<
String
,
?>
event
);
/**
* Sets the string name for the logical operation this span represents.
*
* @return this Span instance, for chaining
*/
AbstractSpan
setOperationName
(
String
operationName
);
```
Span的操作语义和OpenTracing类似。
SpanLayer为我们的特有概念,如果是远程调用类的服务,请设置此属性,包括4个属性值
1.
DB
1.
RPC_FRAMEWORK,非HTTP类型的RPC框架,如:原生的DUBBO,MOTAN
1.
HTTP
1.
MQ
### 开发插件
#### 一. 简介
因为所有的程序调用都是基于方法的,所以插件实际上就是基于方法的拦截,类似面向切面编程的AOP技术。sky-walking底层已经完成相关的技术封装,所以插件开发者只需要定位需要拦截的类、方法,然后结合上文中的追踪API,即可完成插件的开发。
#### 二. 拦截类型
根据Java方法,共有三种拦截类型
1.
拦截构造函数
1.
拦截实例方法
1.
拦截静态方法
我们将这三类拦截,分为两类,即:
1.
实例方法增强插件,继承ClassInstanceMethodsEnhancePluginDefine
1.
静态方法增强插件,继承ClassStaticMethodsEnhancePluginDefine
当然,也可以同时支持实例和静态方法,直接继承ClassEnhancePluginDefine。但是,这种情况很少。
#### 三. 实现自己的插件定义
我们以继承ClassInstanceMethodsEnhancePluginDefine为例(ClassStaticMethodsEnhancePluginDefine十分类似,不再重复描述),描述定义插件的全过程
1.
定义目标类名称
```
java
protected
abstract
ClassMatch
enhanceClass
();
```
ClassMatch反应类的匹配方式,目前提供三种:
*
byName, 通过类名完整匹配
*
byClassAnnotationMatch, 通过类标注进行匹配
*
byMethodAnnotationMatch, 通过方法的标注来匹配类
*
byHierarchyMatch, 通过父类或者接口匹配
注意实现:
*
所有类、接口、标注名称,请使用字符串,不要使用
`*.class.getName()`
(用户环境可能会引起ClassLoader问题)。
*
by
*
AnnotationMatch不支持继承的标注
*
byHierarchyMatch,如果存在接口、抽象类、类间的多层继承关系,如果方法复写,则可能造成多层埋点。
如:
```
java
@Override
protected
ClassMatch
enhanceClassName
()
{
return
byName
(
"org.apache.catalina.core.StandardEngineValve"
);
}
```
2.
定义构造函数拦截点
```
java
protected
InstanceMethodsInterceptPoint
[]
getInstanceMethodsInterceptPoints
();
public
interface
InstanceMethodsInterceptPoint
{
/**
* class instance methods matcher.
*
* @return methods matcher
*/
ElementMatcher
<
MethodDescription
>
getMethodsMatcher
();
/**
* @return represents a class name, the class instance must instanceof InstanceMethodsAroundInterceptor.
*/
String
getMethodsInterceptor
();
boolean
isOverrideArgs
();
}
```
返回拦截方法的匹配器,以及对应的拦截类,同样由于潜在的ClassLoader问题,不要使用
`*.class.getName()`
。如何构建拦截器,请章节"四. 实现拦截器逻辑"。
3.
定义skywalking-plugin.def文件
```
properties
tomcat-7.x/
8.x
=
org.skywalking.apm.plugin.tomcat78x.define.TomcatInstrumentation
```
*
插件名称,要求全局唯一,命名规范:目标组件+版本号
*
插件定义类全名
#### 四. 实现拦截器逻辑
我们继续以实现实例方法拦截为例,拦截器需要实现org.skywalking.apm.agent.core.plugin.interceptor.enhance.InstanceMethodsAroundInterceptor。
```
java
/**
* A interceptor, which intercept method's invocation. The target methods will be defined in {@link
* ClassEnhancePluginDefine}'s subclass, most likely in {@link ClassInstanceMethodsEnhancePluginDefine}
*
* @author wusheng
*/
public
interface
InstanceMethodsAroundInterceptor
{
/**
* called before target method invocation.
*
* @param result change this result, if you want to truncate the method.
* @throws Throwable
*/
void
beforeMethod
(
EnhancedInstance
objInst
,
Method
method
,
Object
[]
allArguments
,
Class
<?>[]
argumentsTypes
,
MethodInterceptResult
result
)
throws
Throwable
;
/**
* called after target method invocation. Even method's invocation triggers an exception.
*
* @param ret the method's original return value.
* @return the method's actual return value.
* @throws Throwable
*/
Object
afterMethod
(
EnhancedInstance
objInst
,
Method
method
,
Object
[]
allArguments
,
Class
<?>[]
argumentsTypes
,
Object
ret
)
throws
Throwable
;
/**
* called when occur exception.
*
* @param t the exception occur.
*/
void
handleMethodException
(
EnhancedInstance
objInst
,
Method
method
,
Object
[]
allArguments
,
Class
<?>[]
argumentsTypes
,
Throwable
t
);
}
```
可以在方法执行前、执行后、执行异常三个点,进行拦截,设置修改方法参数(执行前),并调用核心API,设置追踪逻辑。
### 贡献插件到主仓库
我们鼓励大家共同贡献支持各个类库的插件。
大家需支持以下步骤执行:
1.
在issue页面提出插件扩展需求,对应的版本。
1.
Fork wu-sheng/sky-walking到本地
1.
在apm-sniffer/apm-sdk-plugin下新建自己的插件模块,模块名为:支持类库名称+版本号
1.
按照规范开发插件
1.
完善注释和测试用例
1.
在本地打包进行集成测试
1.
提交Pull Request到 wu-sheng/sky-walking,提供插件追踪的截图(拓扑和Trace明细),可独立运行的被追踪程序、docker镜像或docker-compose。
1.
sky-walking PMC( Project Management Committee) 成员完成插件审核,确定发布版本,并合并到主仓库。
\ No newline at end of file
docs/cn/Skywalking-3-Cross-Process-Propagation-Headers-Protocol-CN.md
0 → 100644
浏览文件 @
d6a6fe10
# Skywalking 3 Cross Process Propagation Headers Protocol
*
Version 1.0
这是Skywalking3跨进程传输头协议第一个公开版本。Skywalking是一个偏向APM的分布式追踪系统,所以,为了提供服务端处理性能。头信息会比其他的追踪系统要更复杂一些。你会发现,这个头信息,更像一个商业APM系统,并且,一些商业APM系统的头信息,比我们的要复杂的多。所以,如果你希望开发或者贡献其他语言探针、或者JAVA探针的其他市县模式,请耐心阅读,并理解此协议内容。
# Header Item
*
Header Name:
`sw3`
*
Header Value: 使用
`|`
分隔,包含以下内容
## Values
*
Trace Segment Id
Trace segment,即分布式调用链片段。这个ID为此调用链片段全局唯一ID。此ID由一次分布式调用链的一个线程执行过程独享(在Java模型中)。ID由三个Long型组成,如:
`"1.2343.234234234`
1) 第一部分代表应用的实例ID(
`application instance id`
),此ID通过注册接口由Collector分配。一般取值范围为整形,利于protobuf传输。
2) 第二部分为线程号,Java模型中,一般也是整形。
3) 第三部分又由两部分组成
1) 时间戳,单位毫秒
2) 线程内的自增序列。0到9999之间。
如果你使用其他语言实现探针,你只需要保证你的ID由三个Long型构成,并全局唯一,不必完全遵守Java的ID生成规则。
*
Span Id
一个整数,在trace segment内唯一,从0开始自增。
*
Parent Application Instance
父级应用节点的应用实例ID。如:在一个RPC调用中,HEAD中是客户端的应用实例ID。
*
Entry Application Instance
入口应用节点的应用实例ID。如:在一个分布式链路
`A->B->C`
中,此字段为
`A`
应用的实例ID。
*
Peer Host
服务端的Peer Host或Peer Id。如:客户端使用
`182.14.39.1:9080`
服务端,则这个就是对应的Peer Host。
_此值可以通过Collector服务获得对应的ID。如果非ID,则使用`#`开头,如果使用ID,则为整数类型。_
*
Entry Span Operation Name of First Trace Segment
调用链入口节点的应用实例下,入口Span的operation name或id。
_此值可以通过Collector服务获得对应的ID。如果非ID,则使用`#`开头,如果使用ID,则为整数类型。_
*
Entry Span Operation Name of Parent Trace Segment
调用链父级节点的应用实例下,入口Span的operation name或id。
_此值可以通过Collector服务获得对应的ID。如果非ID,则使用`#`开头,如果使用ID,则为整数类型。_
*
Distributed Trace Id
分布式链路ID一般是整个调用链的全局唯一ID。如果针对批量消费情况,这个ID是批量中,第一个生产者的trace ID。此ID生成规则和
`Trace Segment Id`
一致,由三个Long型数字构成。
### Sample value
value值示例:
1.
`1.2343.234234234|1|1|1|#127.0.0.1:8080|#/portal/|#/testEntrySpan|1.2343.234234234`
1.
`1.2343.234234234|1|1|1|#127.0.0.1:8080|#/portal/|1038|1.2343.234234234`
\ No newline at end of file
docs/cn/skywalking-opentracing-CN.md
0 → 100644
浏览文件 @
d6a6fe10
*
使用 maven 和 gradle 依赖相应的工具包
```
xml
<dependency>
<groupId>
org.skywalking
</groupId>
<artifactId>
apm-toolkit-opentracing
</artifactId>
<version>
{project.release.version}
</version>
</dependency>
```
[
![Download
](
https://api.bintray.com/packages/wu-sheng/skywalking/org.skywalking.apm-toolkit-opentracing/images/download.svg
)
](https://bintray.com/wu-sheng/skywalking/org.skywalking.apm-toolkit-opentracing/_latestVersion)
*
使用OpenTracing的标准API和桥接器,使用手动埋点
```
java
Tracer
tracer
=
new
org
.
skywalking
.
apm
.
toolkit
.
opentracing
.
SkyWalkingTracer
();
Tracer
.
SpanBuilder
spanBuilder
=
tracer
.
buildSpan
(
"/yourApplication/yourService"
);
```
\ No newline at end of file
编辑
预览
Markdown
is supported
0%
请重试
或
添加新附件
.
添加附件
取消
You are about to add
0
people
to the discussion. Proceed with caution.
先完成此消息的编辑!
取消
想要评论请
注册
或
登录