diff --git a/docs/others/cn/guides/Component-library-settings.md b/docs/others/cn/guides/Component-library-settings.md new file mode 100644 index 0000000000000000000000000000000000000000..16806b0677e9c6ed195b25f17134c50cc3cf42c1 --- /dev/null +++ b/docs/others/cn/guides/Component-library-settings.md @@ -0,0 +1,62 @@ +# 组件库设置 +组件库设置与受监视应用程序中使用的您自己或第三方库有关。 + +在 agent 或 SDK 中, 无论将库名称收集为ID或String(简单地说,例如SpringMVC),收集器格式化ID中的数据,以获得更好的性能和更少的存储要。 + +此外,收集器根据组件库推测远程服务,例如: +组件库是MySQL驱动程序库,那么远程服务应该是MySQL Server。 + +出于这两个原因,收集器需要此文件中的两部分设置: + +1.组件库ID,名称和语言。 +1.远程服务器映射,基于本地库。 + +**必须在此文件中定义所有组件名称和ID。** + +## 组件库ID +定义受监视应用程序中使用的所有组件库的名称和ID。 +这是双向映射,agent或SDK可以value(ID)来表示上行链路数据中的组件名称。 + +- Name:agent和UI中使用的组件名称 +- id:唯一ID。 一旦发布,所有ID都会被保留。 +- languages:程序语言可以使用此组件。 多语言应该用`,`分隔 + +### ID 规则 +- Java and 多语言共享: (0, 3000] +- .NET 平台使用: (3000, 4000] +- Node.js 平台使用: (4000, 5000] +- Go 平台使用: (5000, 6000] +- PHP 平台使用: (6000, 7000] +- Python 使用: (7000, 8000] + +实例 +```yaml +Tomcat: + id: 1 + languages: Java +HttpClient: + id: 2 + languages: Java,C#,Node.js +Dubbo: + id: 3 + languages: Java +H2: + id: 4 + languages: Java +``` + +## 远端服务映射 +远端服务器根据本地组件推断而出,映射基于组件库名称. + +- Key: 客户端组件库名称 +- Value: 服务组件名称 + +```yaml +Component-Server-Mappings: + Jedis: Redis + StackExchange.Redis: Redis + SqlClient: SqlServer + Npgsql: PostgreSQL + MySqlConnector: Mysql + EntityFrameworkCore.InMemory: InMemoryDatabase +``` \ No newline at end of file diff --git a/docs/others/cn/guides/How-to-build.md b/docs/others/cn/guides/How-to-build.md new file mode 100644 index 0000000000000000000000000000000000000000..65cb6e043f9506c0e8bc0d90d2d4c46093369736 --- /dev/null +++ b/docs/others/cn/guides/How-to-build.md @@ -0,0 +1,106 @@ +# 编译指南 +本文档会介绍Skywalking在maven和您使用的IDE下如何进行编译和构建. + +## 项目构建 +**因为我们使用了`Git submodule`,所以我们建议不要使用`GitHub`标签或发布页面来下载用于编译的源代码。** + +### 从GitHub代码构建 +1. 准备git、JDK8和maven3。 +1. `git clone https://github.com/apache/incubator-skywalking.git` +1. `cd incubator-skywalking/` +1. 使用`git checkout [tagname]`切换对应的标签代码版本(可选项,如果要从源代码构建版本,则切换) +1. `git submodule init` +1. `git submodule update` +1. 运行 `./mvnw clean package -DskipTests` +1. 打包后的代码在`/dist`文件夹中(Linux系统使用.tar.gz文件 and Windows使用.zip文件)。 + +### 从Apache源代码发行版本构建 +- 什么是 `Apache源代码发行版本`? + +对于每个正式的Apache发行版本,都有一个完整且独立的源代码tar包,其中包含所有源代码。您可以从[SkyWalking Apache 下载页面](http://skywalking.apache.org/downloads/)下载它。 编译时不需要与git相关的东西。 只需按照以下步骤操作 + +1. 准备JDK8和maven3 +1. 运行 `./mvnw clean package -DskipTests` +1. 打包后的代码在`/dist`文件夹中(Linux系统使用.tar.gz文件 and Windows使用.zip文件)。 + +## 设置IntelliJ IDEA +1. 将项目按照maven项目的形式导入进来。 +1. 运行 `./mvnw compile -Dmaven.test.skip=true`编译项目并生成源代码。 因为Skywalking使用gRPC和protobuf。 +1. 所以还需要设置 **Generated Source Codes** 文件夹. + * **apm-protocol/apm-network/target/generated-sources/protobuf** 文件夹下的`grpc-java` 和 `java` + * **oap-server/server-core/target/generated-sources/protobuf** 文件夹下的`grpc-java` 和 `java` + * **oap-server/server-receiver-plugin/skywalking-istio-telemetry-receiver-plugin/target/generated-sources/protobuf** 文件夹下的`grpc-java` 和 `java` + * **oap-server/generate-tool/target/generated-sources** 文件夹下的 `antlr4` + * **oap-server/generated-analysis/target/generated-sources** 文件夹下的 `oal` + +## 设置Eclipse IDE +1. 将项目按照maven项目的形式导入进来。 +2. 要支持多个源目录,需要添加以下配置 `incubator-skywalking/pom.xml`: + +``` + + org.codehaus.mojo + build-helper-maven-plugin + 1.8 + + + add-source + generate-sources + + add-source + + + + src/java/main + apm-protocol/apm-network/target/generated-sources/protobuf + apm-collector/apm-collector-remote/collector-remote-grpc-provider/target/generated-sources/protobuf + + + + + +``` +3. 添加以下配置,让eclipse的M2e插件支持执行的解决方案配置 + +``` + + + + + org.eclipse.m2e + lifecycle-mapping + 1.0.0 + + + + + + org.codehaus.mojo + build-helper-maven-plugin + [1.8,) + + add-source + + + + + + + + + +``` +4. 将Google guava依赖项添加到 **apm-collector-remote/collector-remote-grpc-provider/pom.xml**文件中 + +``` + + com.google.guava + guava + 24.0-jre + +``` +5. 运行 `./mvnw compile -Dmaven.test.skip=true` +6. 运行 `maven update`. update命令前不能有clean(这将清除complie生成的proto转换Java文件) +7. 运行 `./mvnw compile` 编译 collector-remote-grpc-provider 和 apm-protocol +8. 刷新项目 diff --git a/docs/others/cn/guides/How-to-release.md b/docs/others/cn/guides/How-to-release.md new file mode 100644 index 0000000000000000000000000000000000000000..1f332d6055a637cb97addee3e72e41c44fcd16ab --- /dev/null +++ b/docs/others/cn/guides/How-to-release.md @@ -0,0 +1,377 @@ +Apache SkyWalking 发布指南 +-------------------- +本文档指导每个提交者在Apache Way中发布SkyWalking,并且还帮助提交者检查发布的投票。 + + +## 设置您的开发环境 +按照 [Apache maven部署环境文档](http://www.apache.org/dev/publishing-maven-artifacts.html#dev-env)设置gpg工具和加密密码 + +使用以下代码块作为模板并将其放入 ~/.m2/settings.xml + +``` + +... + + + + apache.snapshots.https + + + + + + apache.releases.https + + + + ... + + +``` + +## 添加您的GPG公钥 +1. 将您的GPG公钥添加到 [SkyWalking GPG KEYS](https://dist.apache.org/repos/dist/release/incubator/skywalking/KEYS) 文件中, +只有你是一个提交者,使用你的Apache id和密码登录这个svn,并更新文件。 **不要覆盖现有文件** +1. 将您的GPG公钥上传到公共GPG站点。 如[MIT's 站点](http://pgp.mit.edu:11371/). 这个网站应该在Apache maven staging repository检查列表 + +## 测试你的配置 +此步骤仅用于测试,如果您的env设置正确,则不需要每次都检查。 +``` +./mvnw clean install -Papache-release (这将构建工件,来源和标志) +``` + +## 准备发布 +``` +./mvnw release:clean +./mvnw release:prepare -DautoVersionSubmodules=true -Pauto-submodule +``` +_你可以在发布之前做一个GPG标志,如果你需要输入密码进行签名,而且maven没有给出机会, +但只是失败。 运行`gpg --sign xxx`到任何文件都可以记住密码有足够的时间来发布._ + +## 发布阶段 +``` +./mvnw release:perform -DskipTests -Pauto-submodule +``` +1.将版本号设置为x.y.z,标记为** v ** x.y.z(版本标记必须以** v **开头,您将在下一步中找到目的。) +1.该版本将自动插入临时存储库中。 + +## 构建并签署源代码包 +```shell +export RELEASE_VERSION=x.y.z (example: RELEASE_VERSION=5.0.0-alpha) +cd tools/releasing +sh create_source_release.sh +``` + +**注意**, `create_source_release.sh` 只适合MacOS。 欢迎任何人贡献Windows bat和Linux shell。 + +这个脚本应该做以下事情 +1. 使用 `v` + `RELEASE_VERSION` 作为标记来克隆代码。 +1. 完成 `git submodule init/update` . +1. 排除目标源tar中的所有不必要的文件,例如.git,.github,.gitmodules。 有关详细信息,请参阅脚本。 +1. 执行 `gpg` 和 `shasum 512`. + + +应该在`tools/releasing`文件夹中找到`apache-skywalking-apm-incubating-x.y.z-src.tgz`和.asc, .sha512结尾的文件 + +## 在Apache Nexus Staging存储库中查找和下载分发 +1. 使用ApacheId登录 `https://repository.apache.org/`。 +1. 跳转到 `https://repository.apache.org/#stagingRepositories`。 +1. 搜索 `skywalking` 并找到您的暂存存储库。 +1. 关闭存储库并等待所有检查通过。 在此步骤中,将检查您的GPG KEYS。参考[设置PGP文档](#add-your-gpg-public-key),如果你以前没有这样做过。 +1. 跳转到 `{REPO_URL}/org/apache/skywalking/apache-skywalking-apm-incubating/x.y.z` +1. 下载 `.tar.gz` 和 `.zip` 且有 .asc 和 .sha1 结尾的文件 + + +## 上传到Apache svn +1. 使用ApacheId登录 `https://dist.apache.org/repos/dist/dev/incubator/skywalking/`。 +1. 创建文件夹,按发行版本和圆形命名,例如:x.y.z。 +1. 将源代码包上传到包含.asc,.sha512的文件夹 + * 包名:apache-skywalking-incubating-x.y.z-src.tar.gz + * 有关详细信息,请参见“构建和签署源代码包”一节 +1. 使用.asc,.sha512将分发包上载到该文件夹 + * 包名:apache-skywalking-incubating-x.y.z.tar.gz, apache-skywalking-incubating-x.y.z.zip + * 有关详细信息,请参见“在Apache Nexus Staging存储库中查找和下载分发”一节 + * 创建.sha512包: `shasum -a 512 file > file.sha512` + +## 发表内部公告 +在开发邮件列表中发送公告邮件。 + +``` +邮件标题: [ANNOUNCE] SkyWalking x.y.z test build available + +邮件内容: +The test build of x.y.z is available. + +This is our Apache Incubator release. +We welcome any comments you may have, and will take all feedback into +account if a quality vote is called for this build. + +Release notes: + + * https://github.com/apache/incubator-skywalking/blob/master/CHANGES.md + +Release Candidate: + + * https://dist.apache.org/repos/dist/dev/incubator/skywalking/xxxx + * sha512 checksums + - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x-src.tgz + - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.tar.gz + - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.zip + +Maven 2 staging repository: + + * https://repository.apache.org/content/repositories/xxxx/org/apache/skywalking/ + +Release Tag : + + * (Git Tag) x.y.z + +Release CommitID : + + * https://github.com/apache/incubator-skywalking/tree/(Git Commit ID) + * Git submodule + * skywalking-ui: https://github.com/apache/incubator-skywalking-ui/tree/(Git Commit ID) + * apm-protocol/apm-network/src/main/proto: https://github.com/apache/incubator-skywalking-data-collect-protocol/tree/(Git Commit ID) + * oap-server/server-query-plugin/query-graphql-plugin/src/main/resources/query-protocol https://github.com/apache/incubator-skywalking-query-protocol/tree/(Git Commit ID) + +Keys to verify the Release Candidate : + + * http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x2EF5026E70A55777 corresponding to pengys@apache.org + +Guide to build the release from source : + + * https://github.com/apache/incubator-skywalking/blob/x.y.z/docs/en/guides/How-to-build.md + +A vote regarding the quality of this test build will be initiated +within the next couple of days. +``` + +## 等待至少48小时的测试响应 +任何PPMC,提交者或贡献者都可以测试发布和反馈的功能。 +基于此,PPMC将决定是否开始投票。 + +## 在dev群组中投票 +在`dev @ skywalking.apache.org`中投票 + +``` +邮件标题: [VOTE] Release Apache SkyWalking (incubating) version x.y.z + +邮件内容: +Hi All, +This is a call for vote to release Apache SkyWalking (Incubating) version x.y.z. + +Release notes: + + * https://github.com/apache/incubator-skywalking/blob/x.y.z/CHANGES.md + +Release Candidate: + + * https://dist.apache.org/repos/dist/dev/incubator/skywalking/xxxx + * sha512 checksums + - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x-src.tgz + - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.tar.gz + - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.zip + +Maven 2 staging repository: + + * https://repository.apache.org/content/repositories/xxxx/org/apache/skywalking/ + +Release Tag : + + * (Git Tag) x.y.z + +Release CommitID : + + * https://github.com/apache/incubator-skywalking/tree/(Git Commit ID) + * Git submodule + * skywalking-ui: https://github.com/apache/incubator-skywalking-ui/tree/(Git Commit ID) + * apm-protocol/apm-network/src/main/proto: https://github.com/apache/incubator-skywalking-data-collect-protocol/tree/(Git Commit ID) + * oap-server/server-query-plugin/query-graphql-plugin/src/main/resources/query-protocol https://github.com/apache/incubator-skywalking-query-protocol/tree/(Git Commit ID) + +Keys to verify the Release Candidate : + + * http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x2EF5026E70A55777 corresponding to pengys@apache.org + +Guide to build the release from source : + + * https://github.com/apache/incubator-skywalking/blob/x.y.z/docs/en/guides/How-to-build.md + +Voting will start now (xxxx date) and will remain open for at least 72 hours, Request all PPMC members to give their vote. +[ ] +1 Release this package. +[ ] +0 No opinion. +[ ] -1 Do not release this package because.... +``` + +## 投票检查 +所有PPMC成员和提交者都应在投票+1之前检查这些。 + +1. 功能测试。 +1. staging repository中的所有工件都使用.asc,.md5,* sha1文件发布 +1. 源代码和下发包 (apache-skywalking-incubating-x.y.z-src.tar.gz, apache-skywalking-incubating-x.y.z.tar.gz, apache-skywalking-incubating-x.y.z.zip) +都应该在 `https://dist.apache.org/repos/dist/dev/incubator/skywalking/x.y.z` 且包含 .asc, .sha512 +1. `LICENSE` 和 `NOTICE` 文件在源代码和分发包中。 +1. 检查 `shasum -c apache-skywalking-apm-incubating-x.y.z-src.tgz.sha512` +1. 构建发布源代码包 (apache-skywalking-incubating-x.y.z-src.tar.gz) by following this [文档](https://github.com/apache/incubator-skywalking/blob/master/docs/en/How-to-build.md#build-from-apache-source-codes). +1. Apache RAT检查。运行`./mvnw apache-rat:check`. (源代码中没有二进制文件) +1. 需要有免责声明 + +投票结果应遵循这些。 +1.PPMC投票是+1绑定,所有其他投票是+1没有约束力。 +1.在72小时内,你得到至少3(+1绑定),并且+1比-1更多。投票通过。 + +## 要求在Apache IPMC中投票 +在`general @ incubator.apache.org`中投票 + +``` +邮件标题: [VOTE] Release Apache SkyWalking (incubating) version x.y.z + +邮件内容: +Hi All, +This is a call for vote to release Apache SkyWalking (Incubating) version x.y.z. + +The Apache SkyWalking community has tested, voted and approved the proposed +release of Apache SkyWalking (Incubating) x.y.z + +We now kindly request the Incubator PMC members review and vote on this +incubator release. + +SkyWalking: APM (application performance monitor) tool for distributed systems, +especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures. +Underlying technology is a distributed tracing system. + +Vote Thread: + + * From `list.apache.org` + +Result Thread: + + * From the vote thread. + +Release notes: + + * https://github.com/apache/incubator-skywalking/blob/x.y.z/CHANGES.md + +Release Candidate: + + * https://dist.apache.org/repos/dist/dev/incubator/skywalking/xxxx + * sha512 checksums + - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x-src.tgz + - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.tar.gz + - sha512xxxxyyyzzz apache-skywalking-apm-incubating-x.x.x.zip + +Maven 2 staging repository: + + * https://repository.apache.org/content/repositories/xxxx/org/apache/skywalking/ + +Release Tag : + + * (Git Tag) x.y.z + +Release CommitID : + + * https://github.com/apache/incubator-skywalking/tree/(Git Commit ID) + * Git submodule + * skywalking-ui: https://github.com/apache/incubator-skywalking-ui/tree/(Git Commit ID) + * apm-protocol/apm-network/src/main/proto: https://github.com/apache/incubator-skywalking-data-collect-protocol/tree/(Git Commit ID) + * oap-server/server-query-plugin/query-graphql-plugin/src/main/resources/query-protocol https://github.com/apache/incubator-skywalking-query-protocol/tree/(Git Commit ID) + +Keys to verify the Release Candidate : + + * http://pgp.mit.edu:11371/pks/lookup?op=get&search=0x2EF5026E70A55777 corresponding to pengys@apache.org + +Guide to build the release from source : + + * https://github.com/apache/incubator-skywalking/blob/x.y.z/docs/en/guides/How-to-build.md + +Voting will start now (xxxx date) and will remain open for at least 72 hours, Request IPMC to give their vote. +[ ] +1 Release this package. +[ ] +0 No opinion. +[ ] -1 Do not release this package because.... +``` + +## 投票结果邮件 +关闭投票,如果: +1. I在72小时内,你得到至少3(+1绑定),并且+1比-1更多。 投票通过。 在IPMC投票中,只有孵化器项目PMC +投票将被视为+1绑定。 +1. 一些评论者在这个版本中发现了一些严重的错误,团队可以决定取消投票并准备一个新的RC。 + +发送邮件到 `general@incubator.apache.org` 涉及投票结果和状态. +``` +邮件标题: [Result][VOTE] Release Apache SkyWalking (incubating) version x.y.z + +邮件内容: +Hi all, + +The vote for releasing Apache SkyWalking x.y.z (incubating) is closed, now. + +Vote result: +x (+1 binding) (Names of voters) +y -1. + +Thank you everyone for taking the time to review the release and help us. + +I will process to publish the release and send ANNOUNCE. +``` + +## 发版 +1. 将源代码tar球和发行版移动到 `https://dist.apache.org/repos/dist/release/incubator/skywalking/`. + +``` +> export SVN_EDITOR=vim +> svn mv https://dist.apache.org/repos/dist/dev/incubator/skywalking/x.y.z https://dist.apache.org/repos/dist/release/incubator/skywalking +.... +enter your apache password +.... + +``` +2. 在nexus staging repo中发布. +3. 公共下载源和下发 tar/zip 位于 `http://www.apache.org/dyn/closer.cgi/incubator/skywalking/x.y.z/xxx`. +我们只发布Apache镜像路径作为发布信息。 +4. 公共asc和sha512位于 `https://www.apache.org/dist/incubator/skywalking/x.y.z/xxx` +5. 公共密钥指向 `https://www.apache.org/dist/incubator/skywalking/KEYS` +6. 将ANNOUNCE邮件发送到 `general@incubator.apache.org` 和 `dev@skywalking.apache.org`. + +``` +邮件标题: [ANNOUNCE] Release Apache SkyWalking (incubating) version x.y.z + +邮件内容: +Hi all, + +Apache SkyWalking (incubating) Team is glad to announce the first release of Apache SkyWalking Incubating x.y.z. + +SkyWalking: APM (application performance monitor) tool for distributed systems, +especially designed for microservices, cloud native and container-based (Docker, Kubernetes, Mesos) architectures. +Underlying technology is a distributed tracing system. + +Vote Thread: + +Download Links : http://skywalking.apache.org/downloads/ + +Release Notes : https://github.com/apache/incubator-skywalking/blob/x.y.z/CHANGES.md + +Website: http://skywalking.apache.org/ + +SkyWalking Resources: +- Issue: https://github.com/apache/incubator-skywalking/issues +- Mailing list: dev@skywalkiing.incubator.apache.org +- Documents: https://github.com/apache/incubator-skywalking/blob/x.y.z/docs/README.md + + +- Apache SkyWalking (incubating) Team + +===== +*Disclaimer* + +Apache SkyWalking (incubating) is an effort undergoing incubation at The +Apache Software Foundation (ASF), sponsored by the name of Apache +Incubator PMC. Incubation is required of all newly accepted +projects until a further review indicates that the +infrastructure, communications, and decision making process have +stabilized in a manner consistent with other successful ASF +projects. While incubation status is not necessarily a reflection +of the completeness or stability of the code, it does indicate +that the project has yet to be fully endorsed by the ASF. +``` + +7. 更新网站下载页面。 http://skywalking.apache.org/downloads/ 。 包括新的下载源,分发,sha512,asc和文档,链接。 可通过遵循上述规则(3) - (6)找到链接。 +8. 在网站主页甚至页面上添加发布活动。 通过更改日志或主要功能宣布公开发布。 diff --git a/docs/others/cn/guides/Java-Plugin-Development-Guide.md b/docs/others/cn/guides/Java-Plugin-Development-Guide.md new file mode 100644 index 0000000000000000000000000000000000000000..615e13afea6219b5d715d46e849961472f1b7385 --- /dev/null +++ b/docs/others/cn/guides/Java-Plugin-Development-Guide.md @@ -0,0 +1,299 @@ +# 插件开发指南 +本文档描述了如何理解,开发和贡献插件。 + +## 概念 +### Span +Span是分布式跟踪系统中一个重要且通用的概念。 +可从[Google Dapper Paper](https://research.google.com/pubs/pub36356.html) 和 +[OpenTracing](http://opentracing.io)学习**Span**相关知识 + +SkyWalking从2017年开始支持OpenTracing和OpenTracing-Java API,我们的Span概念与论文和OpenTracing类似。我们也扩展了Span。 + +Span有三种类型 + +1.1 EntrySpan +EntrySpan代表服务提供者,也是服务器端的端点。 作为一个APM系统,我们的目标是 +应用服务器。 所以几乎所有的服务和MQ-comsumer都是EntrySpan。 + +1.2 LocalSpan +LocalSpan表示普通的Java方法,它与远程服务无关,也不是MQ生产者/消费者 +也不是服务(例如HTTP服务)提供者/消费者。 + +1.3 ExitSpan +ExitSpan代表一个服务客户端或MQ的生产者,在SkyWalking的早期命名为“LeafSpan”。 +例如 通过JDBC访问DB,读取Redis / Memcached被编目为ExitSpan。 + +### ContextCarrier +为了实现分布式跟踪,需要绑定跨进程的跟踪,并且应该传播上下文 +整个过程。 这就是ContextCarrier的职责。 + +以下是有关如何在`A -> B`分布式调用中使用**ContextCarrier**的步骤。 + +1. 在客户端,创建一个新的空的`ContextCarrier`。 +1. 通过 `ContextManager#createExitSpan` 创建一个 ExitSpan 或者 使用 `ContextManager#inject` 来初始化 `ContextCarrier`. +1. 将`ContextCarrier`所有信息放到heads(例如HTTP HEAD)、attachments(例如Dubbo RPC framework) 或者messages(例如Kafka) +1. 通过服务调用,将`ContextCarrier`传递到服务端。 +1. 在服务端,在对应组件的heads、attachments或messages获取`ContextCarrier`所有消息。 +1. `ContestManager#createEntrySpan`创建EntrySpan 或者使用 `ContextManager#extract` 将服务端和客户端的绑定。 + +让我们通过Apache HTTPComponent client插件 和Tomcat 7服务器插件演示,步骤如下: + +1. 客户端Apache HTTPComponent client插件 + +```java + span = ContextManager.createExitSpan("/span/operation/name", contextCarrier, "ip:port"); + CarrierItem next = contextCarrier.items(); + while (next.hasNext()) { + next = next.next(); + httpRequest.setHeader(next.getHeadKey(), next.getHeadValue()); + } +``` + +2. 服务端Tomcat 7服务器插件 + +```java + ContextCarrier contextCarrier = new ContextCarrier(); + CarrierItem next = contextCarrier.items(); + while (next.hasNext()) { + next = next.next(); + next.setHeadValue(request.getHeader(next.getHeadKey())); + } + + span = ContextManager.createEntrySpan(“/span/operation/name”, contextCarrier); +``` + +### ContextSnapshot +除了跨进程,跨线程也是需要支持的,例如异步线程(内存中的消息队列)和批处理在java中很常见,跨进程和跨线程十分相似,因为都是需要传播 +上下文。 唯一的区别是,不需要跨线程序列化。 + +以下是有关跨线程传播的三个步骤: +1. 使用`ContextManager#capture`获取ContextSnapshot对象。 +2. 让子线程以任何方式,通过方法参数或由现有参数携带来访问ContextSnapshot +3. 在子线程中使用`ContextManager#continies`。 + +## 核心 API +### ContextManager +ContextManager提供所有主要API。 + +1. Create EntrySpan + +```java +public static AbstractSpan createEntrySpan(String endpointName, ContextCarrier carrier) +``` +按操作名称创建 EntrySpan (例如服务名称, uri) 和 **ContextCarrier**. + +2. Create LocalSpan + +```java +public static AbstractSpan createLocalSpan(String endpointName) +``` +按操作名称创建 LocalSpan (例如完整的方法结构) + +3. Create ExitSpan + +```java +public static AbstractSpan createExitSpan(String endpointName, ContextCarrier carrier, String remotePeer) +``` +按操作名称创建 ExitSpan (例如服务名称, uri) 和 **ContextCarrier** 和 对端地址 (例如ip+port或hostname+port) + +### AbstractSpan +```java + /** + * Set the component id, which defines in {@link 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 event); + + /** + * Sets the string name for the logical operation this span represents. + * + * @return this Span instance, for chaining + */ + AbstractSpan setOperationName(String endpointName); +``` +除了设置操作名称,标签信息和日志外,还要设置两个属性,即component(组件)和layer(层),特别是对于EntrySpan和ExitSpan。 + +SpanLayer 是span的编目. 有五个值: +1. UNKNOWN (默认) +1. DB +1. RPC_FRAMEWORK, (为了RPC框架,非普通的HTTP调用)for a RPC framework, not an ordinary HTTP +1. HTTP +1. MQ + +组件ID由SkyWalking项目定义和保留,对于组件的名称或ID的扩展,请遵循[组件库的定义与扩展](Component-library-settings.md) + +## 开发插件 +### Abstract(抽象) +跟踪的基本方法是拦截Java方法,使用字节码操作技术和AOP概念。 +SkyWalking包装了字节码操作技术并跟踪上下文的传播, +所以你只需要定义拦截点(换句话说就是Spring的切面) + +### Intercept(拦截) +SkyWalking提供两类通用的定义去拦截构造器,实例方法和类方法。 +* Extend `ClassInstanceMethodsEnhancePluginDefine` defines `Contructor` intercept points and `instance method` intercept points. +* 继承 `ClassInstanceMethodsEnhancePluginDefine` 定义 `Contructor`(构造器)拦截点和 `instance method`(实例化方法)拦截点. +* 继承 `ClassStaticMethodsEnhancePluginDefine` 定义 `class method`(类方法)拦截点. + +当然,您也可以集成`ClassEnhancePluginDefine`去设置所有的拦截点,担着不常用。 + +### Implement plugin(实现插件) +下文,我将通过扩展`ClassInstanceMethodsEnhancePluginDefine`来演示如何实现一个插件 + +1. 定义目标类的名称 + +```java +protected abstract ClassMatch enhanceClass(); +``` + +ClassMatch 以下有四种方法表示如何去匹配目标类: +* byName, 通过完整的类名(package name + `.` + class name)(包名+类名)。 +* 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 getMethodsMatcher(); + + /** + * @return represents a class name, the class instance must instanceof InstanceMethodsAroundInterceptor. + */ + String getMethodsInterceptor(); + + boolean isOverrideArgs(); +} +``` + +也可以使用`Matcher`来设置目标方法。 如果要更改参数,请在`isOverrideArgs`中返回** true ** 参考拦截器。 + +以下部分将告诉您如何实现拦截器。 + +3. Add plugin define into skywalking-plugin.def file +```properties +tomcat-7.x/8.x=TomcatInstrumentation +``` + + +### 实现一个拦截器 +作为一个实例方法的拦截器,需要实现 +`org.apache.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); +} +``` +在before,after和exception处理阶段使用核心API。 + + +### 将插件贡献到Apache SkyWalking 仓库中 +我们欢迎大家贡献插件。 + +请按照以下步骤操作: + +1. 提交有关您要贡献哪些插件的问题,包括支持的版本。 +1. 在`apm-sniffer / apm-sdk-plugin`或`apm-sniffer / optional-plugins`下创建子模块,名称应包含支持的库名和版本 +1. Create sub modules under `apm-sniffer/apm-sdk-plugin` or `apm-sniffer/optional-plugins`, and the name should include supported library name and versions +1. 按照本指南进行开发。 确保提供评论和测试用例。 +1. 开发并测试。 +1. 发送拉取请求并要求审核。 +1. 提供自动测试用例。 +所有测试用例都托管在[SkywalkingTest/skywalking-agent-testcases repository](https://github.com/SkywalkingTest/skywalking-agent-testcases). +关于如何编写测试用例,请按照[如何编写](https://github.com/SkywalkingTest/skywalking-agent-testcases/blob/master/docs/how-to-write-a-plugin-testcase.md) 文档来实现. +1. 在提供自动测试用例并在CI中递交测试后,插件提交者会批准您的插件。 +1. SkyWalking接受的插件。 diff --git a/docs/others/cn/guides/README.md b/docs/others/cn/guides/README.md index a05f9ea4f0f05f78c0b524d08359b9ca8cea331f..390e3db44a89b36fb4ea7072ecc7e6c9dc0f0674 100644 --- a/docs/others/cn/guides/README.md +++ b/docs/others/cn/guides/README.md @@ -1,2 +1,43 @@ -# 指南 -TODO +# 贡献指南 +你可以通过以下方式,为SkyWalking社区做成贡献。 + +- 审阅SkyWalking的文档,指出或修复文档不准确的地方,也可以将SkyWalking文档翻译成其他语言。 +- 下载我们的[发布版本](http://skywalking.apache.org/downloads/),尝试用其监控你的应用程序,并向我们反馈您的想法、疑问或使用案例。 +- 阅读我们的源码,带着细节信息向我们提问。 +- 发现bug时,可在这里[提交问题](https://github.com/apache/incubator-skywalking/issues), 并且您也可以尝试修复它。 +- 你可以从完成[社区需要的帮助](https://github.com/apache/incubator-skywalking/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22), +着手做起. +- 提交问题或讨论在[GitHub问题处](https://github.com/apache/incubator-skywalking/issues/new). +- 通过[网页邮件列表](https://lists.apache.org/list.html?dev@skywalking.apache.org)查看所有邮件的讨论,如果您是SkyWalking项目的committer,可在浏览器模式下登录并使用邮件列表。否则,根据按照下面进行订阅。 +- 问题的报告和讨论也可在 `dev@skywalking.apache.org`进行, +发送邮件到`dev-subscribe@skywalking.apache.org`,按照回复订阅邮件列表。 + + +## 与我们联系 +以下所有渠道均向社区开放,您可以选择自己喜欢的方式。 + +* 提交[问题](https://github.com/apache/incubator-skywalking/issues) +* 邮件列表: **dev@skywalking.apache.org**. 发送邮件到 `dev-subscribe@skywalking.apache.org`,按照回复订阅邮件列表。 +* [Gitter](https://gitter.im/openskywalking/Lobby) +* QQ群: 392443393 + +## 对于代码开发者 +作为开发者,首先阅读[编译指南](How-to-build.md). 它会告诉你如何在本地构建。 + +### 项目扩展 +SkyWalking项目支持许多扩展现有功能的方法。 如果你对这些方式感兴趣, +阅读以下指南。 + +- [Java agent 插件开发指南](Java-Plugin-Development-Guide.md). +本指南将帮助您开发SkyWalking Java agent插件以支持更多框架或组件。 无论是进行开源插件或私有插件的开发都需要阅读这个指南。 +- 如果您想开发其他语言的探针或组件,请阅读[组件库定义和扩展](Component-library-settings.md) 文档. +- [数据存储扩展开发指南](storage-extention.md). 除了官方已经支持的存储实现外,可帮助钱在的贡献者实现新的数据存储的实现。 +- [通过oal脚本自定义分析](write-oal.md). 指导您使用oal脚本来提供自己所需的指标。 +### UI开发者 +Skywalking UI 由静态页面和Web容器构成。 + +- **静态页面** 是建立在 [Ant Design Pro](https://pro.ant.design/)之上,Skywalking UI源码托管在[Skywalking UI](https://github.com/apache/incubator-skywalking-ui)。 +- **Web容器** 源代码在`apm-webapp`模块中。这是一个简单的zuul代理,用于托管静态资源并使用GraphQL想后端发送查询请求。 + +## 发布 +[Apache发布指南](How-to-release.md)向提交者团队介绍了正式的Apache版本发布流程,以避免破坏任何Apache规则。如果您在重新分发中保留我们的许可和通知,则Apache许可允许每个人重新分发。 \ No newline at end of file diff --git a/docs/others/cn/guides/backend-oal-scripts.md b/docs/others/cn/guides/backend-oal-scripts.md new file mode 100644 index 0000000000000000000000000000000000000000..cba020cd8c284d5c56df3e7ffe1f1c54db38c3a5 --- /dev/null +++ b/docs/others/cn/guides/backend-oal-scripts.md @@ -0,0 +1,11 @@ +# 官方 OAL(可观测性分析语言) 脚本 +首先请阅读[OAL 介绍](../../../en/concepts-and-designs/oal.md). + +发行版本中官方脚本:`generated-analysis-x.y.z.jar/official_analysis.oal`,并且源代码库在模块`server-core`中**src/main/resources/official_analysis.oal**。 +**注意**, 这个文件虽然包含在发行版本中,但是在项目运行期间不会起任何作用。您需要使用OAL工具器去真实的分析代码。所生成的代码在`server-core`模块**org.apache.skywalking.oap.server.core.analysis.generated**中 + +此脚本中命名的所有度量标准都可用于警报和UI查询。 当然,你可以改变这个 +脚本并重新生成分析过程和度量标准,例如添加过滤条件。 + +如果您尝试添加或删除某些指标,UI项目可能出现问题,我们建议您在计划时执行此操作是 +基于自定义分析核心构建自己的UI。 \ No newline at end of file diff --git a/docs/others/cn/guides/storage-extention.md b/docs/others/cn/guides/storage-extention.md new file mode 100644 index 0000000000000000000000000000000000000000..0996b7760576f806d24591d2cd44338977b2afba --- /dev/null +++ b/docs/others/cn/guides/storage-extention.md @@ -0,0 +1,41 @@ +# 数据存储扩展 +SkyWalking g已经提供了多种存储解决方案。在本文档中,您可以 +学习如何轻松实现新存储。 + +## 定义您的数据存储提供实现 +1. 定义一个类扩展 `org.apache.skywalking.oap.server.library.module.ModuleProvider`. +2. 将此数据存储提供实现继承存储模块。 +```java +@Override +public Class module() { + return StorageModule.class; +} +``` + +## 实现所有DAO接口 +下面是所有数据存储所需实现的DAO接口 + +1. IServiceInventoryCacheDAO +1. IServiceInstanceInventoryCacheDAO +1. H2EndpointInventoryCacheDAO +1. H2NetworkAddressInventoryCacheDAO +1. IBatchDAO +1. StorageDAO +1. IRegisterLockDAO +1. H2TopologyQueryDAO +1. IMetricQueryDAO +1. ITraceQueryDAO +1. IMetadataQueryDAO +1. IAggregationQueryDAO +1. IAlarmQueryDAO +1. IHistoryDeleteDAO + +## 注册所有的service实现 +在 `public void prepare()`, 使用 `this#registerServiceImplementation` 方法去注册绑定您的接口实现。 + +## 实例 +`org.apache.skywalking.oap.server.storage.plugin.elasticsearch.StorageModuleElasticsearchProvider` +或 `org.apache.skywalking.oap.server.storage.plugin.jdbc.mysql.MySQLStorageProvider` 就是一个很好的例子。 + +## 重新发布新的数据存储实现 +您不必为了实现数据存储而克隆主托管库,您可以轻松地依赖我们的Apache版本。看一下 [OpenSkywalking/SkyWalking-With-Es5x-Storage](https://github.com/OpenSkywalking/SkyWalking-With-Es5x-Storage) 仓库, SkyWalking v6 重新发布 ElasticSearch 5 TCP 链接数据存储的实现。 \ No newline at end of file diff --git a/docs/others/cn/guides/write-oal.md b/docs/others/cn/guides/write-oal.md new file mode 100644 index 0000000000000000000000000000000000000000..e62d81af90c702dee42a720f795f73f1f87decc8 --- /dev/null +++ b/docs/others/cn/guides/write-oal.md @@ -0,0 +1,15 @@ +# 编写 OAL(可观测性分析语言) 脚本 +阅读 [OAL 概述](../../../en/concepts-and-designs/oal.md) 以了解oal脚本。 + +## 在源代码中查找oal脚本 +官方official_analysis.oal在[这里](../../../../oap-server/generated-analysis/src/main/resources/official_analysis.oal). + +## 生成工具 +`oap-server/generate-tool` 模块包含编译工具的源代码。 该工具已经集成在 +maven编译阶段。 所以,除非您想要更改工具源代码,否则无需进行任何设置。 + +运行 `./mvnw compile` 或 `./mvnw package`, 生成的oal脚本代码位于`oap-server/generate-tool/target/generated-sources/oal/*`. + +## 编写并重新编译 +您可以更改`official_analysis.oal`脚本, 然后重新编译代码. +生成的代码位于 **oap-server/generated-analysis/target/generated-sources/oal**. \ No newline at end of file