diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index c8191542d4..0000000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,124 +0,0 @@ -# Contributing to Sermant - -Welcome to Sermant! This document is a guideline about how to contribute to Sermant. - -If you find something incorrect or missing, please leave comments / suggestions. - -## Before You Get Started - -### Code of Conduct - -Please make sure to read and observe our [Code of Conduct](./CODE_OF_CONDUCT.md). - -## Contributing - -Sermant welcome new participants of any role, including user, contributor, committer and PMC. - -![](docs/binary-docs/contributor_definition.png) - - -We encourage new comers actively join in Sermant projects and involving from user role to committer role, and even PMC role. In order to accomplish this, new comers needs to actively contribute in Sermant project. The following paragraph introduce how to contribute in Sermant way. - -#### Open / Pickup An Issue for Preparation - -If you find a typo in document, find a bug in code, or want new features, or want to give suggestions, you can [open an issue on GitHub](https://github.com/huaweicloud/Sermant/issues/new) to report it. - -If you just want to contribute directly you can choose the issue below. - -- [Contribution Welcome](https://github.com/huaweicloud/Sermant/labels/contribution%20welcome): Heavily needed issue, but currently short of hand. - -- [good first issue](https://github.com/huaweicloud/Sermant/labels/good%20first%20issue): Good for newcomers, new comer can pickup one for warm-up. - - -We strongly value documentation and integration with other projects such as Spring Cloud, Kubernetes, Dubbo, etc. We are very glad to work on any issue for these aspects. - -Please note that any PR must be associated with a valid issue. Otherwise the PR will be rejected. - -#### Begin Your Contribute - -Now if you want to contribute, please create a new pull request. - -We use the `develop` branch as the development branch, which indicates that this is a unstable branch. - -Further more, our branching model complies to [A successful Git branching model](https://nvie.com/posts/a-successful-git-branching-model/). We strongly suggest new comers walk through the above article before creating PR. - -Now, if you are ready to create PR, here is the workflow for contributors: - -1. Fork to your own - -2. Clone fork to local repository - -3. Create a new branch and work on it - -4. Keep your branch in sync - -5. Commit your changes (make sure your commit message concise) - -6. Push your commits to your forked repository - -7. Create a pull request to **develop** branch. - - -When creating pull request: - -1. Please follow [the pull request template](.github/PULL_REQUEST_TEMPLATE.md). - -2. Please create the request to **develop** branch. - -3. Please make sure the PR has a corresponding issue. - -4. If your PR contains large changes, e.g. component refactor or new components, please write detailed documents about its design and usage. - -5. Note that a single PR should not be too large. If heavy changes are required, it's better to separate the changes to a few individual PRs. - -6. After creating a PR, one or more reviewers will be assigned to the pull request. - -7. Before merging a PR, squash any fix review feedback, typo, merged, and rebased sorts of commits. The final commit message should be clear and concise. - - -If your PR contains large changes, e.g. component refactor or new components, please write detailed documents about its design and usage. - -### Code Review Guidance - -Committers will rotate reviewing the code to make sure all the PR will be reviewed timely and by at least one committer before merge. If we aren't doing our job (sometimes we drop things). And as always, we welcome volunteers for code review. - -Some principles: - -- Readability - Important code should be well-documented. API should have Javadoc. Code style should be complied with the existing one. - -- Elegance - New functions, classes or components should be well designed. - -- Testability - 80% of the new code should be covered by unit test cases. - -- Maintainability - to be done. - - -### Now How About Try Become A Committer? - -Generally speaking, contribute 8 non-trivial patches and get at least three different people to review them (you'll need three people to support you). Then ask someone to nominate you. You're demonstrating your: - -- at least 8 PR and the associated issues to the project, - -- ability to collaborate with the team, - -- understanding of the projects' code base and coding style, and - -- ability to write good code (last but certainly not least) - - -A current committer nominates you by slacking the team on the Sermant issue with label "nomination" - -- your first and last name - -- a link to your Git profile - -- an explanation of why you should be a committer, - -- Elaborate the top 3 PR and the associated issues the nominator has worked with you that can demonstrate your ability. - - -Two other committer need to second your nomination. If no one objects in 5 working days (China), you're a committer. If anyone objects or wants more information, the committers discuss and usually come to a consensus (within the 5 working days). If issues cannot be resolved, there's a vote among current committers. - -![](docs\binary-docs\contribute.png) - -In the worst case, this can drag out for two weeks. Keep contributing! Even in the rare cases where a nomination fails, the objection is usually something easy to address like "more patches" or "not enough people are familiar with this person's work." diff --git a/README-zh.md b/README-zh.md index cc2169d46d..185cc2e522 100644 --- a/README-zh.md +++ b/README-zh.md @@ -51,19 +51,7 @@ mvn clean package -Dmaven.test.skip -Pexample ### 启动Sermant -启动 **Sermant** backend, **准备zookeeper**。 - -```shell -# Run under Linux -java -jar sermant-agent-x.x.x/server/sermant/sermant-backend-x.x.x.jar -``` - -```shell -# Run under Windows -java -jar sermant-agent-x.x.x\server\sermant\sermant-backend-x.x.x.jar -``` - -启动 **Sermant** demo 应用: +准备和启动zookeeper,启动 **Sermant** demo 应用: ```shell # Run under Linux @@ -83,23 +71,9 @@ java -cp sermant-example\demo-application\target\demo-application.jar ^ ![pic](docs/binary-docs/backend_sermant_info.png) -#### 有关详细信息,请参阅 [服务注册和发现快速开始说明](docs/QuickStart.md)。 - -## 插件功能列表 -| 功能名称 | 阶段 | 微服务框架组件支持列表 | -|:-----|:-----|:-----| -| [限流降级](docs/user-guide/flowcontrol/flowcontrol-zh.md) | Beta | SpringBoot 1.2.x - 2.6.x
SpringWebMvc 4.1.3.RELEASE - 5.3.x
Dubbo 2.6.x-2.7.x | -| [服务注册](docs/user-guide/registry/document-zh.md) | GC | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x | -| [服务双注册迁移](docs/user-guide/registry/spring-cloud-registry-migiration-zh.md) | GC | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x | -| [负载均衡](docs/user-guide/loadbalancer/document-zh.md) | Beta | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0 | -| [标签路由](docs/user-guide/router/document-zh.md) | Beta | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x | -| [优雅上下线](docs/user-guide/graceful/document-zh.md) | Beta | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0 | -| [动态配置](docs/user-guide/dynamic-config/document-zh.md) | Beta | SpringBoot 1.5.x - 2.6.2
spring-cloud-starter-alibaba-nacos-config 1.5.0.RELEASE+
spring-cloud-starter-zookeeper-config 1.2.0.RELEASE+ | -| [服务监控](docs/user-guide/server-monitor/document-zh.md) | Alpha | All | - ## 更多文档 -请参阅 [Sermant 开发和使用介绍](docs/README.md) +请参阅 [Sermant文档](https://sermant.io/zh/document/) ## License @@ -107,7 +81,7 @@ Sermant 采用 [Apache 2.0 License.](/LICENSE) ## 贡献指南 -请阅读[贡献指南](CONTRIBUTING.md)以了解如何贡献项目。 +请阅读[贡献指南](https://sermant.io/zh/document/CONTRIBUTING.html)以了解如何贡献项目。 ## 声明 diff --git a/README.md b/README.md index b77b7a4151..a90fd31dae 100644 --- a/README.md +++ b/README.md @@ -51,19 +51,7 @@ mvn clean package -Dmaven.test.skip -Pexample ### Start Sermant -Start **Sermant** backend, **Prepare zookeeper**. - -```shell -# Run under Linux -java -jar sermant-agent-x.x.x/server/sermant/sermant-backend-x.x.x.jar -``` - -```shell -# Run under Windows -java -jar sermant-agent-x.x.x\server\sermant\sermant-backend-x.x.x.jar -``` - -Start **Sermant** demo project: +Prepare and start zookeeper, start **Sermant** demo project: ```shell # Run under Linux @@ -82,24 +70,9 @@ Check running status of Sermant. In this example, open the browser and navigate ![pic](docs/binary-docs/backend_sermant_info.png) -#### Please refer to the [Service Register & Discovery Plugin QuickStart](docs/QuickStart.md) for details. - -## Plugin Features - -| Feature | Phase | Microservice Framework Supported | -|:---- | :---- |:----| -| [FlowControl](docs/user-guide/flowcontrol/flowcontrol.md) | Beta | SpringBoot 1.2.x - 2.6.x
SpringWebMvc 4.1.3.RELEASE - 5.3.x
Dubbo 2.6.x-2.7.x | -| [Service Registration](docs/user-guide/registry/document.md) | GC | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x | -| [Service Dual Registration and Migration](docs/user-guide/registry/spring-cloud-registry-migiration.md) | GC | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x | -| [Loadbalancer](docs/user-guide/loadbalancer/document.md) | Beta | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0 | -| [Tag Router](docs/user-guide/router/document.md) | Beta | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x | -| [Graceful Online/Offline](docs/user-guide/graceful/document.md) | Beta | SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0 | -| [Dynamic Configuration](docs/user-guide/dynamic-config/document.md) | Beta | SpringBoot 1.5.x - 2.6.2
spring-cloud-starter-alibaba-nacos-config 1.5.0.RELEASE+
spring-cloud-starter-zookeeper-config 1.2.0.RELEASE+ | -| [Server Monitor](docs/user-guide/server-monitor/document.md) | Alpha | All | - ## More Documents to Follow -Please refer to the [Development Guide](docs/README.md) +Please refer to the [Sermant Document](https://sermant.io/en/document/) ## License @@ -107,7 +80,7 @@ Sermant adopts [Apache 2.0 License.](/LICENSE) ## How to Contribute -Please read [Contribute Guide](CONTRIBUTING.md) to refer how to join the contribution. +Please read [Contribute Guide](https://sermant.io/en/document/CONTRIBUTING.html) to refer how to join the contribution. ## Declaration diff --git a/docs/FAQ-zh.md b/docs/FAQ-zh.md deleted file mode 100644 index 367d601449..0000000000 --- a/docs/FAQ-zh.md +++ /dev/null @@ -1,33 +0,0 @@ -# Frequently Asked Questions - -[简体中文](FAQ-zh.md) | [English](FAQ.md) - -## Sermant 框架功能 - -#### [启动参数appName是什么参数?](./user-guide/FAQ-zh.md#启动参数appName是什么参数) -#### [Sermant 提供哪些方面的服务治理插件?](./user-guide/FAQ-zh.md#Sermant提供哪些方面的服务治理插件) - -## 插件 - -### 限流降级 - -#### [关于业务场景的apiPath是如何定义的?](./user-guide/flowcontrol/FAQ-zh.md#关于业务场景的apiPath是如何定义的) -#### [如何确定配置规则生效](./user-guide/flowcontrol/FAQ-zh.md#如何确定配置规则生效) -#### [熔断策略未生效的可能原因](./user-guide/flowcontrol/FAQ-zh.md#熔断策略未生效的可能原因) -#### [隔离仓规则未生效的可能原因](./user-guide/flowcontrol/FAQ-zh.md#隔离仓规则未生效的可能原因) -#### [重试规则未生效的可能原因](./user-guide/flowcontrol/FAQ-zh.md#重试规则未生效的可能原因) -#### [启动报HttpHostConnectException异常的可能原因](./user-guide/flowcontrol/FAQ-zh.md#启动报HttpHostConnectException异常的可能原因) - -### 服务注册 - -#### [报错:No such extension org.apache.dubbo.registry.RegistryFactory by name sc](./user-guide/registry/FAQ-zh.md#报错No-such-extension-orgapachedubboregistryRegistryFactory-by-name-sc) -#### [报错:/sermant/master/v1/register error](./user-guide/registry/FAQ-zh.md#报错sermantmasterv1register-error) -#### [报错:Connection reset](./user-guide/registry/FAQ-zh.md#报错Connection-reset) -#### [报错:https protocol is not supported](./user-guide/registry/FAQ-zh.md#报错https-protocol-is-not-supported) -#### [报错:No such extension org.apache.dubbo.metadata.report.MetadataReportFactory by name sc](./user-guide/registry/FAQ-zh.md#报错No-such-extension-orgapachedubbometadatareportMetadataReportFactory-by-name-sc) -#### [报错:No registry config found or it's not a valid config](./user-guide/registry/FAQ-zh.md#报错No-registry-config-found-or-its-not-a-valid-config) -#### [插件配置中,enableSpringRegister/enableDubboRegister与openMigration之间的关系是什么?](./user-guide/registry/FAQ-zh.md#插件配置中enableSpringRegisterenableDubboRegister与openMigration之间的关系是什么) - -[返回**QuickStart**说明文档](./QuickStart-zh.md) - -[返回**Sermant**说明文档](./README-zh.md) \ No newline at end of file diff --git a/docs/FAQ.md b/docs/FAQ.md deleted file mode 100644 index 19cf58579d..0000000000 --- a/docs/FAQ.md +++ /dev/null @@ -1,33 +0,0 @@ -# Frequently Asked Questions - -[简体中文](FAQ-zh.md) | [English](FAQ.md) - -## About Sermant Framework - -#### [What does the input parameter “appName” mean?](./user-guide/FAQ.md#What-does-the-input-parameter-appName-mean) -#### [What kind of service governance plugins does Sermant provide?](./user-guide/FAQ.md#What-kind-of-service-governance-plugins-does-Sermant-provide) - -## About Sermant Plugins - -### Flow Control and Degradation - -#### [How to define "apiPath" for a business scenario?](./user-guide/flowcontrol/FAQ.md#How-Is-The-APIPath-Defined-In-The-Service-Scenario) -#### [How to ensure that a configuration rule takes effect?](./user-guide/flowcontrol/FAQ.md#How-Do-I-Determine-Whether-a-Configuration-Rule-Takes-Effect) -#### [Possible reasons for why the circuit breaker policy did not take effect.](./user-guide/flowcontrol/FAQ.md#Possible-Causes-For-The-Failure-Of-The-Circuit-Breaker-Policy-To-Take-Effect) -#### [Possible reasons for why isolation cabin rules did not take effect.](./user-guide/flowcontrol/FAQ.md#Possible-Reasons-Why-The-Quarantine-Rule-Does-Not-Take-Effect) -#### [Possible reasons for why the retry rules did not work.](./user-guide/flowcontrol/FAQ.md#Possible-Causes-For-The-Retry-Rule-Does-Not-Take-Effect) -#### [Possible causes of HttpHostConnectException on startup.](./user-guide/flowcontrol/FAQ.md#Possible-Causes-Of-The-HttpHostConnectException-Error-Reported-During-Startup) - -### Service Registration - -#### [Exception: No such extension org.apache.dubbo.registry.RegistryFactory by name sc](./user-guide/registry/FAQ.md#Exception-No-such-extension-orgapachedubboregistryRegistryFactory-by-name-sc) -#### [Exception: /sermant/master/v1/register error](./user-guide/registry/FAQ.md#Exception-sermantmasterv1register-error) -#### [Exception: Connection reset](./user-guide/registry/FAQ.md#Exception-Connection-reset) -#### [Exception: https protocol is not supported](./user-guide/registry/FAQ.md#Exception-https-protocol-is-not-supported) -#### [Exception: No such extension org.apache.dubbo.metadata.report.MetadataReportFactory by name sc](./user-guide/registry/FAQ.md#Exception-No-such-extension-orgapachedubbometadatareportMetadataReportFactory-by-name-sc) -#### [Exception: No registry config found or it's not a valid config](./user-guide/registry/FAQ.md#Exception-No-registry-config-found-or-its-not-a-valid-config) -#### [What is the relationship between "enableSpringRegister"/"enableDubboRegister" and "openMigration" in the plugin configuration?](./user-guide/registry/FAQ.md#What-Is-The-Relationship-Between-Plugin-Configuration-enableSpringRegisterenableDubboRegister-And-openMigration) - -[Back to **QuickStart**](./QuickStart.md) - -[Back to README of **Sermant**](./README.md) \ No newline at end of file diff --git a/docs/QuickStart-zh.md b/docs/QuickStart-zh.md deleted file mode 100644 index e8703b0b1a..0000000000 --- a/docs/QuickStart-zh.md +++ /dev/null @@ -1,76 +0,0 @@ -# 服务注册和发现快速开始说明 - -[简体中文](QuickStart-zh.md) | [English](QuickStart.md) - -本文档基于宿主应用更改注册中心的场景,我们将使用Sermant框架的注册插件,完整的展示了如何使用Sermant插件非侵入式地扩展宿主应用的功能。 -另外,更新的插件功能请参见[插件列表](user-guide/feature-list-zh.md)后自行选择。 - -## 使用Sermant前 -如下图所示: 文档中演示使用的应用示例在未使用Sermant时, 会将应用注册到Zookeeper中。 - - -## 使用Sermant后 -如下图所示: 文档中演示使用的应用示例在使用Sermant时, Sermant会将原本注册到Zookeeper的应用信息注册到ServiceCenter中; Sermant采用zookeeper作为默认的配置中心,向插件提供了动态配置管理的能力。 - - - -# 获取编译结果 - -## 下载release包 -点击 [here](https://github.com/huaweicloud/Sermant/releases) 下载release包 - -## 源码编译 -- 编译机器需具备[git](https://git-scm.com/downloads) , [jdk 8或11](https://www.oracle.com/java/technologies/downloads/) , [maven](https://maven.apache.org/download.cgi) 环境 -- 执行`git clone -b main https://github.com/huaweicloud/Sermant-examples.git` 克隆最新源码 -- 执行`cd sermant-template`进入源码目录 -- 执行`mvn clean package` 编译示例项目, 将在`sermant-template`目录下生成`agent`文件夹,包含sermant示例组件 - -# 启动 -- 运行环境需要具备[ServiceCenter](https://github.com/apache/servicecomb-service-center/releases) ,[zookeeper](https://zookeeper.apache.org/releases.html) 分别作为注册中心和配置中心。 - -- 进入编译后可执行文件根目录(例如:**sermant-agent-1.0.0**) - -- 执行以下命令启动backend,详细的后端模块介绍以及更多的配置修改,请参考[backend模块](user-guide/backend-zh.md) - ```bash - # windows - java -jar server\sermant\sermant-backend-x.x.x.jar - - # mac, linux - java -jar server/sermant/sermant-backend-x.x.x.jar - ``` - -- 执行以下命令启动注册插件provider示例应用(请自行下载[示例应用源码](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-register/resttemplate-provider)) - - ```bash - # windows - java -javaagent:agent\sermant-agent.jar=appName=provider -jar resttemplate-provider.jar - # mac linux - java -javaagent:agent/sermant-agent.jar=appName=provider -jar resttemplate-provider.jar - ``` - -- 执行以下命令启动注册插件consumer示例应用(请自行下载[示例应用源码](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-register/resttemplate-consumer)) - ```bash - # windows - java -javaagent:agent\sermant-agent.jar=appName=consumer -jar resttemplate-consumer.jar - # mac linux - java -javaagent:agent/sermant-agent.jar=appName=consumer -jar resttemplate-consumer.jar - ``` - -- 浏览器访问:[http://localhost:8900](http://localhost:8900) 查看框架和启用插件的运行状态。 - ![pic](binary-docs/backend_sermant_info.png) - -- 浏览器访问:[http://localhost:30103](http://localhost:30103) 查看应用注册状态。 - ![pic](binary-docs/register-application.PNG) - -- 浏览器访问:[http://localhost:8005/hello](http://localhost:8005/hello) 验证provider和consumer注册和订阅成功。 - - - -## 查看日志 -Sermant和Backend日志的存放目录分别位于sermant运行环境下`./logs/sermant/core`和`./logs/sermant/backend` - -## 相关文档 - -插件开发, 请参考 [插件开发相关文档](./README-zh.md)。 - -常见问题说明与解决指导,请参考[FAQ](./FAQ-zh.md)。 \ No newline at end of file diff --git a/docs/QuickStart.md b/docs/QuickStart.md deleted file mode 100644 index c16234b59b..0000000000 --- a/docs/QuickStart.md +++ /dev/null @@ -1,76 +0,0 @@ -# Quick Start Instructions for Service Registration and Discovery - -[简体中文](QuickStart-zh.md) | [English](QuickStart.md) - -Based on the scenario where the host application changes the registration center, we will use the registration plugin of the Sermant framework, and fully show how to use the Sermant plugin to non-invasively extend the functionality of the host application. - -In addition, refer to [List of Plugin Functions](user-guide/feature-list.md) to get more plugin functions. - -## Before Adopting Sermant -The following figure shows the example application demonstrated in this documentation is registered with Zookeeper when Sermant is not used. - - -## After Adopting Sermant -This figure shows When using a Sermant, the Sermant registers the application information which originally registered with Zookeeper to ServiceCenter. Sermant adopts ZooKeeper as the default configuration center to provide dynamic configuration management capabilities to the plugins. - - - -# Get Compiled Products - -## Download the release package -Click [here](https://github.com/huaweicloud/Sermant/releases) to download the release package - -## Compile Source Code -- Prepare [git](https://git-scm.com/downloads) , [jdk 8 or 11](https://www.oracle.com/java/technologies/downloads/) , [maven](https://maven.apache.org/download.cgi) for your machine -- execute `git clone -b main https://github.com/huaweicloud/Sermant-examples.git` to clone the source code -- execute `cd sermant-template`to entry into Sermant directory -- execute `mvn clean package` to compile source code of Sermant, which genetates `agent` in `sermant-template` that contains example package. - -# Startup -- Runtime environment requires [ServiceCenter](https://github.com/apache/servicecomb-service-center/releases), and [zookeeper](https://zookeeper.apache.org/releases.html) as the registration center and configuration center respectively. - -- entry into the root directory of the compiled executable file(e.g. **sermant-agent-1.0.0**). - -- To start Backend, run the following command. For a detailed description of the backend module and more configuration modifications, please refer to [Backend Module](user-guide/backend.md). - ```bash - # windows - java -jar server\sermant\sermant-backend-x.x.x.jar - - # mac, linux - java -jar server/sermant/sermant-backend-x.x.x.jar - ``` - -- Execute the following command to launch the sample provider application that mounts the register plugin.(Download [source code of demo](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-register/resttemplate-provider)) - ```bash - # windows - java -javaagent:agent\sermant-agent.jar=appName=provider -jar resttemplate-provider.jar - # mac linux - java -javaagent:agent/sermant-agent.jar=appName=provider -jar resttemplate-provider.jar - ``` - -- Execute the following command to launch the sample consumer application that mounts the register plugin.(Download [source code of demo](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-register/resttemplate-consumer)) - ```bash - # windows - java -javaagent:agent\sermant-agent.jar=appName=consumer -jar resttemplate-consumer.jar - # mac linux - java -javaagent:agent/sermant-agent.jar=appName=consumer -jar resttemplate-consumer.jar - ``` - -- Open a browser to access: http://localhost:8900 to check the running state of Sermant and the enabled plugin. - ![pic](binary-docs/backend_sermant_info.png) - -- Open a browser to access:[http://localhost:30103](http://localhost:30103) to check the application registration status. - ![pic](binary-docs/register-application.PNG) - -- Open a browser to access:[http://localhost:8005/hello](http://localhost:8005/hello) to check if the provider and consumer registered and subscribed successfully - - - -## Check Logs -The log directories for Sermant and Backend are located in `./logs/sermant/core ` and `./logs/sermant/backend` respectively in the environment of host application. - -## Related Documents - -For plugin development, please refer to [Introduction to Sermant Development and Usage](./README.md). - -Frequently asked questions and solution guidance, please refer to [FAQ](./FAQ.md). \ No newline at end of file diff --git a/docs/README-zh.md b/docs/README-zh.md deleted file mode 100644 index 6fa9560c2d..0000000000 --- a/docs/README-zh.md +++ /dev/null @@ -1,95 +0,0 @@ -# Sermant 开发和使用介绍 - -[简体中文](README-zh.md) | [English](README.md) - -Sermant 是基于Java Agent的字节码增强技术,通过 Java Agent 对宿主应用进行非侵入式增强,以解决Java应用的微服务治理问题。Sermant的初衷是建立一个面向微服务治理的对开发态无侵入的解决方案生态,降低服务治理开发和使用的难度,通过抽象接口、功能整合、插件隔离等手段,达到简化开发、功能即插即用的效果。 - -本文档对如何开发和使用 Sermant 做详细介绍。 - -## 运行环境 - -- [HuaweiJDK 1.8](https://gitee.com/openeuler/bishengjdk-8) / [OpenJDK 1.8](https://github.com/openjdk/jdk) / [OracleJDK 1.8](https://www.oracle.com/java/technologies/downloads/) -- [Apache Maven 3](https://maven.apache.org/download.cgi) - -## 模块说明 - -**Sermant**包含以下模块: - -- [sermant-agentcore](../sermant-agentcore): *Java Agent*相关内容 - - [sermant-agentcore-core](../sermant-agentcore/sermant-agentcore-core): 核心功能模块 - - [sermant-agentcore-premain](../sermant-agentcore/sermant-agentcore-premain): *Java Agent*入口模块 - - [sermant-agentcore-config](../sermant-agentcore/sermant-agentcore-config): 配置模块 -- [sermant-backend](../sermant-backend): 消息发送模块服务端 -- [sermant-package](../sermant-package): 打包模块 -- [sermant-plugins](../sermant-plugins): 插件根模块,内含各种功能的插件及相关附加件 -- [sermant-injector](../sermant-injector): sermant-agent容器化部署Admission Webhook组件 - -## 打包流程 - -**Sermant**的打包流程大致分为以下步骤: - -- *agent*: 编译、打包核心功能和插件 -- *example*: 编译、打包核心功能和示例模块(默认不开启) -- *backend*: 编译、打包**Sermant**后端模块 -- *ext*: 编译、打包插件附带的后端、前端和其他附加件 -- *package*: 将以上的打包结果归档为产品包 -- *release*: 发布构建产物到中央仓库 -- *all*: 执行以上全部步骤(默认不开启) - -执行以下*maven*命令,对**Sermant**工程进行默认打包: - -```shell -mvn clean package -Dmaven.test.skip -``` - -命令执行完毕后,工程目录下将生成一个形如`sermant-agent-x.x.x`的文件夹和形如`sermant-agent-x.x.x.tar.gz`的压缩文件,后者为**Sermant**的产品包,前者则为产品包解压后的内容。 - -## 产品目录说明 - -- *agent*: Java Agent相关内容 - - *config*: 配置文件目录 - - *bootstrap.properties*: 启动配置 - - *config.properties*: 核心功能配置 - - *plugins.yaml*: 插件配置,配置着需要被加载的插件功能 - - *core/sermant-agentcore-core-x.x.x.jar*: **Sermant**的核心功能包 - - *pluginPackage*: 插件包目录,插件按功能名称分类 - - *xxx*: 任意插件功能 - - *config/config.yaml*: 插件配置文件 - - *plugin*: 插件包目录 - - *service*: 插件服务包目录 - - *sermant-agent.jar*: JavaAgent入口包 -- *server*: 服务器目录,含**Sermant**的服务端,插件的服务端和客户端 - -## 容器化部署说明 -k8s环境下,Sermant支持通过sermant-injector组件实现宿主应用自动挂载sermant-agent包的快速部署方式。如何部署sermant-injector与宿主应用可以参考[容器化部署指导手册](user-guide/injector-zh.md) - -## 插件开发 - -如何新增一个插件可以参考[插件模块开发手册](dev-guide/dev_plugin_module-zh.md),其中涉及添加插件、插件服务及附加件的详细流程。 - -如何编写一个插件的内容可以参考[插件代码开发手册](dev-guide/dev_plugin_code-zh.md),其中涉及大部分开发插件过程中可能遇到场景。 - -## 相关文档 - -|文档名称|文档类型| -|---|---| -|[第三方版权说明手册](dev-guide/third_party_copyright-zh.md)|开发手册| -|[版本管理手册](dev-guide/version_manage-zh.md)|开发手册| -|[插件模块开发手册](dev-guide/dev_plugin_module-zh.md)|开发手册| -|[插件代码开发手册](dev-guide/dev_plugin_code-zh.md)|开发手册| -|[插件去源码开发指导](dev-guide/dev_plugin_introduce-zh.md)|开发手册| -|[动态配置服务介绍](dev-guide/service_dynamicconfig-zh.md)|开发手册| -|[心跳服务介绍](dev-guide/service_heartbeat-zh.md)|开发手册| -|[网关服务介绍](dev-guide/service_send-zh.md)|开发手册| -|[核心模块介绍](user-guide/agentcore-zh.md)|使用手册| -|[入口模块介绍](user-guide/entrance-zh.md)|使用手册| -|[后端模块介绍](user-guide/backend-zh.md)|使用手册| -|[容器化部署指导手册](user-guide/injector-zh.md) |使用手册| -|[限流降级功能介绍](user-guide/flowcontrol/flowcontrol-zh.md)|使用手册| -|[负载均衡功能介绍](user-guide/loadbalancer/document-zh.md)|使用手册| -|[动态配置功能介绍](user-guide/dynamic-config/document-zh.md)|使用手册| -|[服务注册功能介绍](user-guide/registry/document-zh.md)|使用手册| -|[优雅上下线功能介绍](user-guide/graceful/document-zh.md)|使用手册| -|[标签路由功能介绍](user-guide/router/document-zh.md)|使用手册| -|[当前插件功能汇总列表](user-guide/feature-list-zh.md)|使用手册| -|[常见问题说明指导](./FAQ-zh.md)|使用手册| \ No newline at end of file diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 3ebbb96799..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,96 +0,0 @@ -# Introduction to Sermant Development and Usage - -[简体中文](README-zh.md) | [English](README.md) - -Sermant is a bytecode enhancement technology based on Java Agent. It uses Java Agent to enhance the host application in a non-intrusive way to solve the microservice governance problem of Java applications. The original intention of Sermant is to establish a solution ecosystem for micro-service governance that is non-intrusive to the development state, reduce the difficulty of service governance development and use, and achieve the effect of simplified development and plug-and-play by means of abstract interface, function integration and plugin isolation. - -This document describes how to develop and use Sermant in detail. - -## Runtime Environment - -- [HuaweiJDK 1.8](https://gitee.com/openeuler/bishengjdk-8) / [OpenJDK 1.8](https://github.com/openjdk/jdk) / [OracleJDK 1.8](https://www.oracle.com/java/technologies/downloads/) -- [Apache Maven 3](https://maven.apache.org/download.cgi) - -## Project Modules - -**Sermant** contains the following modules: - -- [sermant-agentcore](../sermant-agentcore): *Java Agent* related content - - [sermant-agentcore-core](../sermant-agentcore/sermant-agentcore-core): Core functional module of the framework - - [sermant-agentcore-premain](../sermant-agentcore/sermant-agentcore-premain): *Java Agent* entry module - - [sermant-agentcore-config](../sermant-agentcore/sermant-agentcore-config): Configuration module of the framework -- [sermant-backend](../sermant-backend): Server side of message sending module -- [sermant-package](../sermant-package): Packaging module -- [sermant-plugins](../sermant-plugins): Root module of plugins, contains a variety of functional plugins and related add-ons -- [sermant-injector](../sermant-injector): Admission webhook module for deployment of sermant-agent via containers - -## Packaging Steps - -The packaging process of **Sermant** is roughly divided into the following steps: - -- *agent*: Compile or package core function and plugins -- *example*: Compile or package core function and demo modules(disabled by default) -- *backend*: Compile or package **Sermant** backend module -- *ext*: Compile and package the backend, frontend, and other add-ons that come with plugins -- *package*: Archive the above packaging results as a product package -- *release*: Publish built artifacts to Maven Central Repository -- *all*: Perform all the preceding steps (disabled by default) - -Execute the following *maven* command package the **Sermant** project by default: - -```shell -mvn clean package -Dmaven.test.skip -``` - -After the command is executed, a folder such as `sermant-agent-x.x.x` and a compressed file such as `sermant-agent-x.x.x.tar.gz` will be generated in the project directory. The latter is the product package of **sermant** and the former is the decompressed content of the product package. - -## Product Directory - -- *agent*: Java Agent related product - - *config*: Configuration file directory - - *bootstrap.properties*: Startup configuration - - *config.properties*: Core function configuration - - *plugins.yaml*: Plugin configuration, which config the plugin functionality that needs to be loaded - - *core/sermant-agentcore-core-x.x.x.jar*: Core package of **Sermant** framework - - *pluginPackage*: Plugin package directory, where plugins are classified by feature name - - *xxx*: Any plugin functionality - - *config/config.yaml*: Plugin configuration file - - *plugin*: Plugin package directory - - *service*: plugin service's package directory - - *sermant-agent.jar*: Java Agent entry package -- *server*: Server directory, which contains server with **Sermant**, plugin server and client - -## Containerized Deployment -In K8S environment, Sermant supports quickly deployment by using Sermant-Injector module to automatically mount Sermant-Agent package for host application. To know more about deploying Sermant-Injector and host applications, you can refer to [Containerized Deployment Guide](user-guide/injector.md). - -## Plugin Development - -How to develop a new plugin module?You can refer to the [Plugin Module Development Guide](dev-guide/dev_plugin_module.md) for details on adding plugins, plugin services, and add-ons. - -How to write a plugin can be found in the [Plugin Code Development Guide](dev-guide/dev_plugin_code.md), which covers most of the possible scenarios in developing a plugin. - -## Other Related Documents - -|Document Name|Type of Document| -|---|---| -|[Third Party Copyright Declaration](dev-guide/third_party_copyright.md)|Development Guide| -|[Version Management Guide](dev-guide/version_manage.md)|Development Guide| -|[Plugin Module Development Guide](dev-guide/dev_plugin_module.md)|Development Guide| -|[Plugin Code Development Guide](dev-guide/dev_plugin_code.md)|Development Guide| -|[Plugin without Source Code Development Guide](dev-guide/dev_plugin_introduce.md)|Development Guide| -|[Introduction to Dynamic Configuration Service](dev-guide/service_dynamicconfig.md)|Development Guide| -|[Introduction to Heartbeat Service](dev-guide/service_heartbeat.md)|Development Guide| -|[Introduction to Gateway Service](dev-guide/service_send.md)|Development Guide| -|[Introduction to Core Modules](user-guide/agentcore.md)|User Guide| -|[Introduction to Sermant Entrance Module](user-guide/entrance.md)|User Guide| -|[Introduction to Backend Module](user-guide/backend.md)|User Guide| -|[Containerized Deployment Guide](user-guide/injector.md) |User Guide| -|[Introduction to Flow Control and Degradation](user-guide/flowcontrol/flowcontrol.md)|User Guide| -|[Introduction to Loadbalancer](user-guide/loadbalancer/document.md)|User Guide| -|[Introduction to Dynamic Configuration](user-guide/dynamic-config/document.md)|User Guide| -|[Introduction to Service Registration](user-guide/registry/document.md)|User Guide| -|[Introduction to Tag Router](user-guide/router/document.md)|User Guide| -|[Introduction to Graceful online/offline](user-guide/graceful/document.md)|User Guide| -|[Summary List of Current Plugin Features](user-guide/feature-list.md)|User Guide| -|[FAQ](./FAQ.md)|User Guide| - diff --git a/docs/binary-docs/add_archetype.png b/docs/binary-docs/add_archetype.png deleted file mode 100644 index c2b591aa8f..0000000000 Binary files a/docs/binary-docs/add_archetype.png and /dev/null differ diff --git a/docs/binary-docs/after_use_agent.png b/docs/binary-docs/after_use_agent.png deleted file mode 100644 index 738658847a..0000000000 Binary files a/docs/binary-docs/after_use_agent.png and /dev/null differ diff --git a/docs/binary-docs/archetype_info.png b/docs/binary-docs/archetype_info.png deleted file mode 100644 index 8b17bed8d4..0000000000 Binary files a/docs/binary-docs/archetype_info.png and /dev/null differ diff --git a/docs/binary-docs/before_use_agent.png b/docs/binary-docs/before_use_agent.png deleted file mode 100644 index 3b729bd940..0000000000 Binary files a/docs/binary-docs/before_use_agent.png and /dev/null differ diff --git a/docs/binary-docs/check_application.png b/docs/binary-docs/check_application.png deleted file mode 100644 index 6b974abc2e..0000000000 Binary files a/docs/binary-docs/check_application.png and /dev/null differ diff --git a/docs/binary-docs/contribute.png b/docs/binary-docs/contribute.png deleted file mode 100644 index 3b6bca1f90..0000000000 Binary files a/docs/binary-docs/contribute.png and /dev/null differ diff --git a/docs/binary-docs/contributor_definition.png b/docs/binary-docs/contributor_definition.png deleted file mode 100644 index 7610295ba6..0000000000 Binary files a/docs/binary-docs/contributor_definition.png and /dev/null differ diff --git a/docs/binary-docs/create_project_by_template.png b/docs/binary-docs/create_project_by_template.png deleted file mode 100644 index 8f67004337..0000000000 Binary files a/docs/binary-docs/create_project_by_template.png and /dev/null differ diff --git a/docs/binary-docs/create_project_by_template_result.png b/docs/binary-docs/create_project_by_template_result.png deleted file mode 100644 index 3310187a4f..0000000000 Binary files a/docs/binary-docs/create_project_by_template_result.png and /dev/null differ diff --git a/docs/binary-docs/idea_new_project.png b/docs/binary-docs/idea_new_project.png deleted file mode 100644 index 9add4d8bb2..0000000000 Binary files a/docs/binary-docs/idea_new_project.png and /dev/null differ diff --git a/docs/binary-docs/register-application.PNG b/docs/binary-docs/register-application.PNG deleted file mode 100644 index f402ba08ef..0000000000 Binary files a/docs/binary-docs/register-application.PNG and /dev/null differ diff --git a/docs/binary-docs/registry-faq-1.png b/docs/binary-docs/registry-faq-1.png deleted file mode 100644 index 06098d8dda..0000000000 Binary files a/docs/binary-docs/registry-faq-1.png and /dev/null differ diff --git a/docs/binary-docs/registry-faq-2.png b/docs/binary-docs/registry-faq-2.png deleted file mode 100644 index ecbc339ba0..0000000000 Binary files a/docs/binary-docs/registry-faq-2.png and /dev/null differ diff --git a/docs/binary-docs/registry-faq-3.png b/docs/binary-docs/registry-faq-3.png deleted file mode 100644 index 743a927e01..0000000000 Binary files a/docs/binary-docs/registry-faq-3.png and /dev/null differ diff --git a/docs/binary-docs/registry-faq-4.png b/docs/binary-docs/registry-faq-4.png deleted file mode 100644 index 5a4d0ca1e2..0000000000 Binary files a/docs/binary-docs/registry-faq-4.png and /dev/null differ diff --git a/docs/binary-docs/registry-faq-5.png b/docs/binary-docs/registry-faq-5.png deleted file mode 100644 index 4ca03e934e..0000000000 Binary files a/docs/binary-docs/registry-faq-5.png and /dev/null differ diff --git a/docs/binary-docs/registry-faq-6.png b/docs/binary-docs/registry-faq-6.png deleted file mode 100644 index 544fca0840..0000000000 Binary files a/docs/binary-docs/registry-faq-6.png and /dev/null differ diff --git a/docs/binary-docs/registry-faq-7.png b/docs/binary-docs/registry-faq-7.png deleted file mode 100644 index c2b3b94117..0000000000 Binary files a/docs/binary-docs/registry-faq-7.png and /dev/null differ diff --git a/docs/binary-docs/registry-faq-8.png b/docs/binary-docs/registry-faq-8.png deleted file mode 100644 index 68025d5d65..0000000000 Binary files a/docs/binary-docs/registry-faq-8.png and /dev/null differ diff --git a/docs/binary-docs/sermant-classloader-arch.png b/docs/binary-docs/sermant-classloader-arch.png deleted file mode 100644 index 464bad464d..0000000000 Binary files a/docs/binary-docs/sermant-classloader-arch.png and /dev/null differ diff --git a/docs/binary-docs/sermant-register-migration-en.png b/docs/binary-docs/sermant-register-migration-en.png deleted file mode 100644 index 68f3d6d987..0000000000 Binary files a/docs/binary-docs/sermant-register-migration-en.png and /dev/null differ diff --git a/docs/binary-docs/sermant-register-migration.png b/docs/binary-docs/sermant-register-migration.png deleted file mode 100644 index 44e6ce8266..0000000000 Binary files a/docs/binary-docs/sermant-register-migration.png and /dev/null differ diff --git a/docs/dev-guide/dev_plugin_code-zh.md b/docs/dev-guide/dev_plugin_code-zh.md deleted file mode 100644 index 96c567e8df..0000000000 --- a/docs/dev-guide/dev_plugin_code-zh.md +++ /dev/null @@ -1,582 +0,0 @@ -# 插件代码开发手册 - -[简体中文](dev_plugin_code-zh.md) | [English](dev_plugin_code.md) - -本文档主要针对**Sermant**的[示例模块](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template),介绍插件开发过程中常见的一些场景。 - -- [组成部分](#组成部分) -- [插件模块](#插件模块) - - [增强定义](#增强定义) - - [原生类增强](#原生类增强) - - [拦截器](#拦截器) - - [插件配置](#插件配置) - - [插件服务](#插件服务) - - [简单插件服务](#简单插件服务) - - [复杂插件服务](#复杂插件服务) - - [日志功能](#日志功能) - - [心跳功能](#心跳功能) - - [链路功能](#链路功能) - - [动态配置功能](#动态配置功能) -- [插件服务模块](#插件服务模块) - -## 组成部分 - -由[插件模块开发手册](dev_plugin_module-zh.md)可知,一个`插件主模块(main)`中可能包含以下5种内容: - -- `插件模块(plugin)`,该模块主要用于声明对宿主应用的增强逻辑 -- `服务模块(service)`,用于为插件包提供服务实现 -- `后端模块(server)`,用于接收插件数据的服务端 -- `前端模块(webapp)`,用于对服务端数据作前端展示 -- `其他模块(other)`,特殊附加件,一般用作调试 - -考虑到后三者随实际业务场景不同有较大变化,因此赋予他们的开发自由度较高,对他们仅有模块目录和输出目录的限制。出于这点考虑,`示例模块`将不对他们做参考案例。`示例模块`中包含以下模块: - -- [template-plugin](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin): 示例插件 -- [template-service](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service): 示例插件服务 -- [demo-application](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-application): 示例宿主应用 - -## 插件模块 - -示例插件模块`template-plugin`中,主要用于向插件开发者展示在插件开发过程中可能遇到的一些场景以及可能使用到的一些功能。 - -开始之前,必须约定的就是,`插件模块(plugin)`中,开发者只能使用*Java*原生API和[**Sermant**核心功能模块](../../sermant-agentcore/sermant-agentcore-core)中的API,不能依赖或使用任何`byte-buddy`与`slf4j`以外的第三方依赖。如果应业务要求,需要使用其他第三方依赖的话,只能在`插件模块(plugin)`中定义接口,在`服务模块(service)`中编写实现。更多相关内容详见[插件模块开发手册](dev_plugin_module-zh.md#添加插件模块)。 - -### 增强定义 - -**Sermant**的核心能力是对宿主应用做非侵入式的字节码增强,而这些增强规则则是插件化的。在每个**Sermant**的`插件主模块(main)`中,都可以定义一些增强定义,针对宿主应用的某些特定方法进行字节码增强,从而实现某种功能。因此`插件主模块(main)`如何告知**Sermant**该增强哪些类,是一个重要的课题。 - -插件的增强定义需要实现[PluginDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/PluginDeclarer.java)接口,其中包含两个接口方法: - -- `getClassMatcher`方法用于获取被增强类的匹配器[ClassMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/ClassMatcher.java)。 -- `getInterceptDeclarers`方法用于获取被增强类的拦截点方法,以及嵌入其中的拦截器,他们封装于方法拦截点[InterceptDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/InterceptDeclarer.java)中。 -- `getSuperTpeDecarers`方法用于获取插件的超类声明[SuperTypeDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/SuperTypeDeclarer.java) - -对匹配器 [ClassMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/ClassMatcher.java),在核心模块中提供了两种类型的匹配器: - -[ClassTypeMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/ClassTypeMatcher.java)(类的类型匹配器) - -- 完全通过名称匹配,也是最常见的定位方式,通过以下方法获取: - ```java - ClassMatcher.nameEquals("${class reference}"); - ``` - 其中`${class reference}`为被增强类的全限定名。 - - -- 通过名称匹配多个类,属于`nameEquals`的复数版,可通过以下方法获取: - ```java - ClassMatcher.nameContains("${class reference array}"); - ``` - 其中`${class reference array}`为被增强类的全限定名可变数组。 - -[ClassFuzzyMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/ClassFuzzyMatcher.java)(类的模糊匹配器) - -- 通过全限定名前缀定位到被增强类,可通过以下方法获取: - ```java - ClassMatcher.namePrefixedWith("${prefix}"); - ``` - 其中`${prefix}`为全限定名前缀。 - - -- 通过全限定名后缀定位到被增强类,可以通过一下方法获取: - ```java - ClassMatcher.nameSuffixedWith("${suffix}") - ``` - 其中`${suffix}`为全限定名后缀。 - - -- 通过全限定名内缀定位到被增强类,可以通过以下方法获取: - ```java - ClassMatcher.nameinfixedWith("${infix}") - ``` - 其中`${infix}`为全限定名内缀。 - - -- 通过正则表达式匹配全限定名定位到被增强类,可以通过以下方法获取: - ```java - ClassMatcher.nameMatches("${pattern}") - ``` - 其中`${pattern}`为正则表达式。 - - -- 通过注解定位到被该注解修饰的类,可通过以下方法获取: - ```java - ClassMatcher.isAnnotationWith("${annotation reference array}"); - ``` - 其中`${annotation reference array}`为注解的全限定名可变数组。 - - -- 通过超类定位到该类的子类,可通过以下方法获取: - ```java - ClassMatcher.isExtendedFrom("${super class array}"); - ``` - 其中`${super class array}`为超类可变数组。考虑到Java的继承规则,该数组只能有一个`Class`,其余必须全为`Interface`。 - - -- 匹配的逻辑操作,匹配器全部不匹配时为真: - ```java - ClassMatcher.not("${class matcher array}") - ``` - 其中`${class matcher array}`为匹配器可变长数组 - - -- 匹配的逻辑操作,匹配器全部都匹配时为真: - ```java - ClassMatcher.and("${class matcher array}") - ``` - 其中`${class matcher array}`为匹配器可变长数组 - - -- 匹配的逻辑操作,匹配器其中一个匹配时为真: - ```java - ClassMatcher.or("${class matcher array}") - ``` - 其中`${class matcher array}`为匹配器可变长数组 - -对于方法拦截点[MethodMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/MethodMatcher.java),提供了多种匹配方法: - -- 全数匹配: - ```java - MethodMatcher.any(); - ``` -- 名称匹配: - ```java - MethodMatcher.nameEquals("${method name}"); - ``` - 其中`${method name}`为方法名称。 - - -- 匹配静态方法: - ```java - MethodMatcher.isStaticMethod(); - ``` -- 匹配构造函数: - ```java - MethodMatcher.isConstructor(); - ``` -- 匹配多个方法: - ```java - MethodMatcher.nameContains("${method name array}"); - ``` - 其中`${method name array}`为方法名称数组。 - - -- 根据方法名称前缀匹配: - ```java - MethodMatcher.namePrefixedWith("${method name prefix}"); - ``` - 其中`${method name prefix}`为方法名称前缀。 - - -- 根据方法名称后缀匹配: - ```java - MethodMatcher.nameSuffixedWith("${method name suffix}"); - ``` - 其中`${method name suffix}`为方法名称后缀。 - - -- 根据方法名称内缀匹配: - ```java - MethodMatcher.nameinfixedWith("${method name infix}"); - ``` - 其中`${method name infix}`为方法名称内缀。 - - -- 根据正则表达式匹配: - ```java - MethodMatcher.nameMatches("${pattern}"); - ``` - 其中`${pattern}`为正则表达式。 - - -- 匹配被传入注解修饰的方法: - ```java - MethodMatcher.isAnnotatedWith("${annotations array}"); - ``` - 其中`${annotations array}`为注解集。 - - -- 匹配指定入参数量的方法: - ```java - MethodMatcher.paramCountEquals("${param count}"); - ``` - 其中`${param count}`为入参数量。 - - -- 匹配指定入参类型的方法: - ```java - MethodMatcher.paramTypeEquals("${param type array}"); - ``` - 其中`${param type array}`为入参类型集。 - - -- 匹配指定返回值类型的方法: - ```java - MethodMatcher.resultTypeEquals("${result type}"); - ``` - 其中`${result type}`返回值类型。 - - -- 逻辑操作,方法匹配器集全不匹配时则结果为真 - ```java - MethodMatcher.not("${element matcher array}"); - ``` - 其中`${element matcher array}`为方法匹配器集。 - - -- 逻辑操作,方法匹配器集全匹配时则结果为真 - ```java - MethodMatcher.and("${element matcher array}"); - ``` - 其中`${element matcher array}`为方法匹配器集。 - - -- 逻辑操作,方法匹配器集其中一个匹配时则结果为真 - ```java - MethodMatcher.or("${element matcher array}"); - ``` - 其中`${element matcher array}`为方法匹配器集。 - -更多方法匹配方式可以参考[byte-buddy](https://javadoc.io/doc/net.bytebuddy/byte-buddy/latest/net/bytebuddy/matcher/ElementMatchers.html)中含`MethodDescription`泛型的方法。 - -开发到最后,不要忘记添加`PluginDeclarer`接口的*SPI*配置文件: - -- 在资源目录`resources`下添加`META-INF/services`文件夹。 -- 在`META-INF/services`中添加`com.huaweicloud.sermant.core.plugin.agent.declarer.PluginDeclarer`配置文件。 -- 在上述文件中,以换行为分隔,键入插件包中所有的增强定义`PluginDeclarer`实现。 - -**Sermant**的`示例模块`中包含以下`PluginDeclarer`接口的实现示例: - -- [DemoAnnotationDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoAnnotationDeclarer.java): 通过注解定位被修饰类的普通增强定义 -- [DemoNameDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoNameDeclarer.java): 通过名称定位到被增强类的普通增强定义 -- [DemoSuperTypeDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoSuperTypeDeclarer.java): 通过超类定位到被增强子类的普通增强定义 -- [DemoBootstrapDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoBootstrapDeclarer.java): 对启动类加载器进行增强的定义,详见[原生类增强](#原生类增强)一节 -- [DemoTraceDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoTraceDeclarer.java): 对示例应用使用链路功能的增强定义,详见[链路功能](#链路功能)一节 - -在各插件开发者在编写插件增强定义的时候,可以以以上示例为参考,开发符合自身需要的增强定义。 - -#### 原生类增强 - -对于`java.lang.Thread`等*Java*原生类,他们由启动类加载器`BootStrapClassLoader`加载,对他们进行增强的话,主要会面临两个困难: - -- 原生类被启动类加载器加载,那么如果对他们做增强的话,就需要将被增强后的字节码重新覆盖回启动类加载器中。考虑到增强后的嵌入代码主要是在**拦截器**中编写的,而这些内容主要由系统类加载器`AppClassLoader`加载,启动类加载器无法访问。得益于[**Advice模板类**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/template)中使用反射调用拦截器的方法,使得原生类在增强时,编写的拦截器不受拘束。 - -- 鉴于*Java*重定义*Class*的限制,我们无法修改这些原生类的元信息,那么就无法使用byte-buddy委派的方式对他们进行增强(原理是添加委派属性和静态代码块)。所幸我们可以使用[**Advice模板类**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/template)配合[**byte-buddy advice**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/transformer/BootstrapTransformer.java)技术进行增强,而现在**核心模块**就是这么做的。 - -结合上述内容,其实增强原生类和增强普通类在增强定义和拦截器编写上没有什么区别,但是还是希望插件开发者尽量少地对原生类进行增强,原因有三: - -- 对原生类的增强往往是发散的,对他们增强很可能会对其他插件或宿主功能造成影响。 -- 对原生类的增强逻辑,将使用反射的方式调用系统类加载器中的拦截器方法。由于*Java*重定义*Class*的限制,每次调用被增强方法的时候,都会进行反射处理的逻辑,这将极大限制该方法的*TPS*上限。 -- 对原生类的增强过程中,涉及到使用**Advice模板类**生成动态拦截类。对于每个被增强的原生类方法,都会动态生成一个,他们将被系统类加载器加载。如果不加限制的增强原生类,加载动态类也会成为启动过程中不小的负担。 - -综上,[**Sermant**核心功能模块](../../sermant-agentcore/sermant-agentcore-core)中提供对*Java*原生类增强的能力,但是,不建议不加限制地对他们进行增强,如果有多个增强点可选,优先考虑增强普通类。 - -**Sermant**的`示例模块`中,[DemoBootstrapDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoBootstrapDeclarer.java)对`java.lang.Thread`做了增强,可以启动示例应用[DemoApplication](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-application/src/main/java/com/huawei/example/demo/DemoApplication.java)观察`java.lang.Thread`是否被正常增强。 - -### 拦截器 - -新版插件的开发中在拦截器层面不再对静态方法、构造函数和实例方法作区分,降低插件开发的复杂度。 -对于方法拦截点`MethodInterceptPoint`,有静态方法、构造函数和实例方法三种获取类型,对应的拦截器也有三种类型: - -- [interceptor](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/interceptor/Interceptor.java): 拦截器接口,其中包含三个方法: - - `before`,前置方法,该方法在拦截点之前执行。ExecuteContext参数为插件执行的上下文,里面封装拦截器运作所需的所有参数,通过skip方法可跳过主要流程,并设置最终方法结果,注意,增强构造函数时,不能跳过主要流程。 - - `after`,后置方法,无论被拦截方法是否正常执行,最后都会进入后置方法中。后置方法可以通过返回值覆盖被拦截方法的返回值,因此这里开发者需要注意不要轻易返回null。 - - `onThrow`,处理异常的方法,当被拦截方法执行异常时触发。这里处理异常并不会影响异常的正常抛出。 - -**Sermant**的`示例模块`中包含以下拦截器示例: - -- [DemoStaticInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoStaticInterceptor.java): 普通的静态方法拦截器 -- [DemoConstInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoConstInterceptor.java): 普通的构造函数拦截器 -- [DemoMemberInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoMemberInterceptor.java): 普通的实例方法拦截器 -- [DemoConfigInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoConfigInterceptor.java): 插件配置使用示例拦截器,详见[插件配置](#插件配置)一节 -- [DemoServiceInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoServiceInterceptor.java): 插件服务使用示例拦截器,详见[插件服务](#插件服务)一节 - -在各插件开发者在编写自定义拦截器的时候,可以以以上示例为参考,开发满足自身功能需要的拦截器。 - -### 插件配置 - -**插件配置**指的是在插件包和插件服务包使用的配置系统,主要由三部分组成: - -- [PluginConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config/PluginConfig.java)插件配置接口: 所有普通的插件配置都要实现该接口。 - -- [PluginConfigManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config/PluginConfigManager.java)插件配置管理器: 提供获取插件配置`PluginConfig`的接口: - - ```java - // ${plugin config class}为插件配置的Class - PluginConfigManager.getPluginConfig(${plugin config class}); - ``` - `PluginConfigManager`是统一配置管理器[ConfigManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/ConfigManager.java)的特例,插件端可以直接使用后者的接口获取插件配置和统一配置: - - ```java - // ${base config class}为统一配置或插件配置的Class - ConfigManager.getConfig(${base config class}); - ``` - -从**Sermant**的`示例模块`的插件配置文件[config.yaml](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/config/config.yaml)可以看出,该配置文件是一个*yaml*文件,一个`插件主模块(main)`的`插件模块(plugin)`和`服务模块(service)`中的插件配置对应的配置信息都封装在这唯一的`config.yaml`中。 - -相较于传统的*yaml*格式配置文件对应一个*Java Pojo*对象,这里的`config.yaml`可以封装多个*Java Pojo*,他们由全限定名或别名进行区分,形成类似*Map*的结构,其中`demo.test`键对应的是**示例插件包**中的[DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java)对象,`com.huawei.example.demo.config.DemoServiceConfig`键对应的是**示例插件服务包**中的[DemoServiceConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service/src/main/java/com/huawei/example/demo/config/DemoServiceConfig.java)对象。 - -[DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java)相较于`DemoServiceConfig`,前者被[ConfigTypeKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigTypeKey.java)注解修饰,因此设定了`demo.test`的别名。如果没有被`ConfigTypeKey`注解修饰,则直接使用全限定名做索引。 - -[DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java)中的`map`属性被[ConfigFieldKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigFieldKey.java)注解修饰,将其属性名修改为`str2DemoSimplePojoMap`。不过需要注意的是,使用该注解的**Java Pojo**如果被数组、*List*或*Map*包装了一层,该注解的语义无效,因此,目前该注解只能用于修饰当前**插件配置类**或直接使用的**Java Pojo**。 - -从[DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java)中可以看出,插件配置现在支持的数据类型包括: - -- 布尔、数值类的基础类型及包装类型 -- 字符串类型 -- 枚举类型 -- 复杂对象类型 -- 上述类型构成的数组 -- 前四种类型构成的*List* -- 前四种类型构成的*Map* - -*yaml*格式配置文件目前还有一些其他规则: - -- 对于数组、List和Map中涉及的复杂对象,不支持`ConfigFieldKey`修正属性名 -- 对于数组、List和Map中的字符串,不支持`${}`转换,**插件配置类**的字符串属性和复杂类型属性内部的字符串属性支持 -- 仅在字符串做`${}`转换时使用入参,不支持使用入参直接设置属性值 -- 配置类的字段名一般为小驼峰命名,可用[ConfigFieldKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigFieldKey.java)注解修饰为中划线风格定义别名。添加注解后,在*yaml*中即可用中划线或小驼峰皆可解析,参考[DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java)的`intField`属性 -- 配置生效的优先级为:启动参数 > 环境变量 > 系统变量(-D参数) > *yaml*文件配置 -- 配置类的属性在按照生效的优先级获取参考值(启动参数,环境变量和系统变量(-D参数))时,小驼峰和中划线都可以被分割成单词来进行查找匹配。例如对于[DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java)的`intField`属性,key将被转化为如下多种形式按顺序来查找: - - demo.test.intField - - demo_test_intField - - demo-test-intField - - DEMO.TEST.INTFIELD - - DEMO_TEST_INTFIELD - - DEMO-TEST-INTFIELD - - demo.test.intfield - - demo_test_intfield - - demo-test-intfield - - demo.test.int.field - - demo_test_int_field - - demo-test-int-field - - DEMO.TEST.INT.FIELD - - DEMO_TEST_INT_FIELD - - DEMO-TEST-INT-FIELD -- 若*yaml*配置中基本数据类型/数组/map/list/set(不支持包含复杂对象)的key未定义,将按照配置生效的优先级:启动参数 > 环境变量 > 系统变量(-D参数) 来获取参考值。从上述数据源获取参考值时,需注意: - - 数组/list/set需配置为`yaml`字符串格式,例如:DEMO_TEST_LIST_NAME=[elem1,elem2] - - map需配置为`yaml`字符串格式,例如:DEMO_TEST_MAP_NAME={key1: value1, key2: value2} - -[DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java)中已经包含了大部分可能的配置场景,插件开发者可以参考并编写符合自身业务需求的插件配置类。 - -最后,不要忘记添加插件配置的*SPI*配置文件: - -- 在资源目录`resources`下添加`META-INF/services`文件夹。 -- 在`META-INF/services`中添加`com.huaweicloud.sermant.core.plugin.config.PluginConfig`配置文件。 -- 在上述文件中,以换行为分隔,键入插件包中所有的插件配置`PluginConfig`实现。 - -### 插件服务 - -**插件服务**指的是在插件包和插件服务包使用的服务系统,主要由两部分组成: - -- [PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java)插件服务接口。 -- [PluginServiceManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginServiceManager.java)插件服务管理器,其中提供获取`PluginService`的接口: - ```java - // ${plugin service class}为插件服务的Class - PluginServiceManager.getPluginService(${plugin service class}); - ``` - `PluginServiceManager`其实只是[ServiceManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/ServiceManager.java)的一个特例,可以直接使用后者的接口获取核心服务和插件服务: - - ```java - // ${base service class}为核心服务或插件服务的Class - ServiceManager.getService(${base service class}); - ``` - - 从[插件模块开发手册](dev_plugin_module-zh.md#添加插件模块)可知,插件有**简单插件**和**复杂插件**之分,这主要和他们所定义服务的复杂程度有关: - - - **简单插件**中定义的服务只能使用*Java*原生*API*、[**Sermant**核心功能模块](../../sermant-agentcore/sermant-agentcore-core)中自研的*API*(`com.huawei`开头),以及`byte-buddy`和`slf4j`的*API*。 - - **复杂插件**中的服务除了能使用上述*API*,还有权使用其他第三方依赖的*API*。这些服务需要分离出**插件服务接口**和**插件服务实现**:前者编写于`插件模块(plugin)`中,供拦截器调用;后者编写于`服务模块(service)`中,由自定义*ClassLoader*加载,以实现类加载器级别的依赖隔离。 - -#### 简单插件服务 - -对于**简单插件服务**,实现[PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java)接口即可,如[DemoSimpleService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoSimpleService.java)示例,在实现`start`方法和`stop`方法的基础上,可以添加其他所需的方法,如`activeFunc`方法,通过以下代码获得`DemoSimpleService`的示例并调用`activeFunc`方法: -```java -DemoSimpleService simpleService = PluginServiceManager.getPluginService(DemoSimpleService.class); -simpleService.activeFunc(); -``` - -对于**简单插件服务**来说,唯一的限制就是只能使用*Java*原生*API*,[**Sermant**核心功能模块](../../sermant-agentcore/sermant-agentcore-core)中自研的*API*(`com.huawei`开头),以及`byte-buddy`和`slf4j`的*API*。 - -插件开发者可以参照[DemoSimpleService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoSimpleService.java),按需编写自身业务所需的**简单插件服务**。 - -最后不要忘记添加[PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java)的*SPI*配置文件: - -- 在资源目录`resources`下添加`META-INF/services`文件夹。 -- 在`META-INF/services`中添加`com.huaweicloud.sermant.core.plugin.service.PluginService`配置文件。 -- 在上述文件中,以换行为分隔,键入插件包中所有的插件服务`PluginService`实现。 - -特别需要注意的是,不要尝试在`PluginService`的`start`方法中获取其他**插件服务**的实例,由于**插件服务**仍在初始化当中,可能无法正确获取这些**插件服务**实例。 - -#### 复杂插件服务 - -**复杂插件服务**比起**简单插件服务**,只有两点区别: - -- **复杂插件服务**在`插件模块(plugin)`中编写接口,在[`服务模块(service)`](#插件服务模块)中编写实现,而**简单插件服务**不需要编写接口,直接在`插件模块(plugin)`中实现。 -- **复杂插件服务**的实现可以按需使用任意第三方依赖。 - -[DemoComplexService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoComplexService.java)是**复杂插件服务**示例接口,其中可以按需添加接口,如`activeFunc`方法,[DemoComplexServiceImpl](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service/src/main/java/com/huawei/example/demo/service/DemoComplexServiceImpl.java)是对应的实现。我们可以通过以下代码调用`activeFunc`方法: - -```java -DemoComplexService complexService = PluginServiceManager.getPluginService(DemoComplexService.class); -complexService.activeFunc(); -``` - -添加*SPI*配置及其他注意事项和**简单插件服务**没有区别,这里不做赘述。开发者可以参照`DemoComplexService`接口和`DemoComplexServiceImpl`实现编写符合自身业务要求的**复杂插件服务**。 - -#### 日志功能 - -考虑到依赖隔离的问题,[**Sermant**核心功能模块](../../sermant-agentcore/sermant-agentcore-core)提供给`插件模块(plugin)`和`服务模块(service)`使用的日志只能是**jul**日志,通过以下方法获取**jul**日志实例: - -```java - -import com.huaweicloud.sermant.core.common.LoggerFactory; -Logger logger=LoggerFactory.getLogger(); -``` - -插件开发者如果需要输出日志信息,可以参考[DemoLogger](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/common/DemoLogger.java)示例开发。 - -#### 心跳功能 - -心跳功能是[**Sermant**核心功能模块](../../sermant-agentcore/sermant-agentcore-core)的核心服务之一,通过以下代码获取实例: -```java -HeartbeatService heartbeatService = ServiceManager.getService(HeartbeatService.class); -``` - -心跳功能在初始化的时候就会启动执行,定期将每个插件的名称、版本等信息发送至后端服务器。目前来说,插件的心跳上报的信息包括: - -- `hostname`:发送客户端的主机名 -- `ip`:发送客户端的IP地址 -- `app`:应用名称,即启动参数中的`appName` -- `appType`:应用类型,即启动参数中的`appType` -- `heartbeatVersion`:上一次心跳发送时间 -- `lastHeartbeat`:上一次心跳发送时间 -- `version`:核心包的版本,即核心包`manifest`文件的`Sermant-Version`值 -- `pluginName`:插件名称,通过插件设定文件确定 -- `pluginVersion`:插件版本号,取插件jar包中`manifest`文件的`Sermant-Plugin-Version`值 - -如果希望在插件上报的数据中增加额外的内容,可以调用以下api: -```java -// 通过自定义ExtInfoProvider提供额外内容集合 -heartbeatService.setExtInfo(new ExtInfoProvider() { - @Override - public Map getExtInfo() { - // do something - } -}); -``` - -插件开发者如果需要往心跳功能发送的数据包中增加额外内容,可以参考[DemoHeartBeatService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoHeartBeatService.java)示例开发。 - -更多心跳服务相关内容可参见[心跳服务介绍](service_heartbeat-zh.md)。 - -#### 链路功能 - -**链路功能**是一个继消息发送能力建立的一个上层功能,该功能简单来说就是从宿主端的调用链之间嵌入以下逻辑: - -- 在发送数据的时候,在数据包中插入链路所需的`TraceId`和`SpanId`,前者是请求在分布式系统中的整个链路视图,后者代表整个链路中不同服务内部的视图。 -- 在接收数据的时候,解析数据包中嵌入的链路相关内容,形成链路的一环提交到后台服务器中,逐渐形成调用链。 - -在示例宿主的[DemoTraceService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-application/src/main/java/com/huawei/example/demo/service/DemoTraceService.java)中,`counsumer`方法和`provider`方法模仿服务器接收数据并处理发送数据的流程,而数据包则假定存在一个`ThreadLocal`中,直到下一次调用`provider`方法接收数据。 - -基于上述示例宿主,我们编写[DemoTraceDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoTraceDeclarer.java)增强定义 -,对`DemoTraceService`的`provider`方法和`consumer`方法分别使用使用[DemoTraceProviderInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoTraceProviderInterceptor.java)和[DemoTraceConsumerInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoTraceConsumerInterceptor.java)拦截器进行增强。 - -- 对于发送`provider`方法,做如下增强: - ```java - private final TracingService tracingService = ServiceManager.getService(TracingService.class); - - @Override - public ExecuteContext before(ExecuteContext context) throws Exception { - TracingRequest request = - new TracingRequest(context.getRawCls().getName(), context.getMethod().getName()); - ExtractService> extractService = (tracingRequest, carrier) -> { - tracingRequest.setTraceId(carrier.get(TracingHeader.TRACE_ID.getValue())); - tracingRequest.setParentSpanId(carrier.get(TracingHeader.PARENT_SPAN_ID.getValue())); - tracingRequest.setSpanIdPrefix(carrier.get(TracingHeader.SPAN_ID_PREFIX.getValue())); - }; - tracingService.onProviderSpanStart(request, extractService, (HashMap)context.getArguments()[0]); - return context; - } - - @Override - public ExecuteContext after(ExecuteContext context) throws Exception { - tracingService.onSpanFinally(); - return context; - } - - @Override - public ExecuteContext onThrow(ExecuteContext context) throws Exception { - tracingService.onSpanError(context.getThrowable()); - return context; - } - ``` -- 对于`consumer`方法,做如下增强: - ```java - TracingService tracingService = ServiceManager.getService(TracingService.class); - - @Override - public ExecuteContext before(ExecuteContext context) throws Exception { - return context; - } - - @Override - public ExecuteContext after(ExecuteContext context) throws Exception { - TracingRequest request = - new TracingRequest(context.getRawCls().getName(), context.getMethod().getName()); - InjectService> injectService = (spanEvent, carrier) -> { - carrier.put(TracingHeader.TRACE_ID.getValue(), spanEvent.getTraceId()); - carrier.put(TracingHeader.PARENT_SPAN_ID.getValue(), spanEvent.getSpanId()); - carrier.put(TracingHeader.SPAN_ID_PREFIX.getValue(), spanEvent.getNextSpanIdPrefix()); - }; - tracingService.onConsumerSpanStart(request, injectService, (HashMap)context.getResult()); - tracingService.onSpanFinally(); - return context; - } - - @Override - public ExecuteContext onThrow(ExecuteContext context) throws Exception { - tracingService.onSpanError(context.getThrowable()); - return context; - } - ``` - **Sermant**的`示例模块`这里只是简单地抛砖引玉。 - 如果插件开发者需要使用链路功能,参照[DemoTraceNormalInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoTraceNormalInterceptor.java)自行开发。 - - -### 动态配置功能 - -动态配置功能是[**Sermant**核心功能模块](../../sermant-agentcore/sermant-agentcore-core)的核心服务之一,通过以下代码获取实例: -```java -DynamicConfigService service = ServiceManager.getService(DynamicConfigService.class); -``` - -调用以下方法注册一个监听器: -```java -// ${group}为用户分组,${key}为监听的键,对zookeeper来说,监听的路径相当于: / + ${group} + ${key} -// 如果不传${group},则会默认设置为统一配置中dynamicconfig.default_group对应的值 -service.addConfigListener("${key}", "${group}", new DynamicConfigListener() { - @Override - public void process(ConfigChangedEvent event) { - // do something - } -}); -``` - -注册监听器之后,当服务器对应节点发生创建、删除、修改、添加子节点等事件时,就会触发`process`函数。 - -插件开发者如果需要使用动态配置,可以参考[DemoDynaConfService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoDynaConfService.java)示例开发。 - -更多动态配置服务相关内容可参见[动态配置服务介绍](service_dynamicconfig-zh.md)。 - - -## 插件服务模块 - -**插件服务模块**较**插件模块**相比: - -- 只能编写**插件配置**和**插件服务接口**的实现,不能编写**增强定义**、**拦截器**和**插件服务接口** -- 允许自由添加需要的第三方依赖,打包的时候,需要提供输出依赖的方式,可以用`shade`插件或`assembly`插件打带依赖*jar*包,也可以直接使用`dependency`插件输出依赖包。 - -注意:由于`byte-buddy`和`slf4j`包的限制,还是建议直接使用`shade`插件打包,相关的规则已在[插件根模块](../../sermant-plugins)中定义完毕,直接引入插件即可,详见[插件模块开发手册](dev_plugin_module-zh.md#添加插件服务模块)。 - -**插件服务模块**中通常涉及[插件配置](#插件配置)和[插件服务](#插件服务)的编写,其中**插件服务**主要是指[复杂插件服务](#复杂插件服务)的实现。以上相关内容前文已有介绍,这里不做赘述。 - -[返回**Sermant**说明文档](../README.md) \ No newline at end of file diff --git a/docs/dev-guide/dev_plugin_code.md b/docs/dev-guide/dev_plugin_code.md deleted file mode 100644 index 91e7e636e5..0000000000 --- a/docs/dev-guide/dev_plugin_code.md +++ /dev/null @@ -1,583 +0,0 @@ -# Plugin Code Development Guide - -[简体中文](dev_plugin_code-zh.md) | [English](dev_plugin_code.md) - -This document focuses on **Sermant**'s [example module](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template), which describes some common scenarios during plug-in development. - -- [Components](#Components) -- [Plugin Module](#Plugin-Module) - - [Enhancement Definition](#Enhancement-Definition) - - [Enhancement for Native Class](#Enhancement-for-Native-Class) - - [Interceptor](#Interceptor) - - [Plugin Configuration](#Plugin-Configuration) - - [Plugin Service](#Plugin-Service) - - [Simple Plugin Service](#Simple-Plugin-Service) - - [Complex Plugin Service](#Complex-Plugin-Service) - - [Log](#Log) - - [Heartbeat](#Heartbeat) - - [Trace Tracking](#Trace-Tracking) - - [Dynamic Configuration](#Dynamic-Configuration) -- [Plugin Service Module](#Plugin-Service-Module) - -## Components - -According to the [Plugin Module Development Guide](dev_plugin_module.md), a `main` plugin module contains the following five things: - -- The `plugin` module, which is mainly used to declare enhancements to the host application. -- The `service` module, which provides the service implementation for the plugin package. -- The `backend` module (server), which receives the data from plugin. -- The `frontend` module (webapp), which is used to display the server-side data -- The `other` module (special add-on), which is usually used for debugging. - -Considering that the latter three have great changes with the actual business scenarios, they are given a high degree of development freedom, and they are only limited by the module directory and the output directory. For this reason, the `example module` will not be a reference case for them. The `example module` contains the following modules: - -- [demo-plugin](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin): the example for plugin -- [demo-service](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service): the example for plugin service -- [demo-application](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-application): the example for host application - -## Plugin Module - -The example plugin module `demo-plugin` is mainly used to show plugin developers some scenarios that may be encountered in the development process of plugins and some functions that may be used. - -Before we start, it's important to agree that in `plugin` modules, developers can only use the *Java* native API and the [**Sermant** core module](../../sermant-agentcore/sermant-agentcore-core) and cannot rely on or use any third-party dependencies other than `byte-buddy` and `slf4j`. If the business needs to use other third-party dependencies, you can only define the interface in the `plugin` module and write the implementation in the `service` module. Refer to the [Plugin Module Development Guide](dev_plugin_module.md#Add-Plugin-Module) for more information. - -### Enhancement Definition - -The core capability of **Sermant** is to make non-intrusive bytecode enhancements to the host application, and these enhancement rules are base on plugins. In the `main` module of each **Sermant** plugin, enhancement definitions can be defined to enhance the bytecode of specific methods of the host application to achieve certain functionality. So how the `main` module tells the **Sermant** which classes to augment is an important topic. - -The Enhancement definition of plugins requires the implementation of [PluginDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/PluginDeclarer.java) interface, which contains two methods: - -- `getClassMatcher` is used to get the matcher [ClassMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/ClassMatcher.java) of the enhanced class. -- `getInterceptDeclarers` is used to obtain the method of interceptor point of the enhanced class, as well as the interceptors embedded in it, encapsulated in the method interceptor point [InterceptDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/InterceptDeclarer.java). -- `getSuperTpeDecarers` gets the plugin's superclass declaration [SuperTypeDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/SuperTypeDeclarer.java). - -The matcher [ClassMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/ClassMatcher.java), which provides two types of matchers in the core module: - -[ClassTypeMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/ClassTypeMatcher.java)(the matcher for class name) - -- The most common way to do this is purely by name matching, which is obtained by: - ```java - ClassMatcher.nameEquals("${class reference}"); - ``` - Where `${class reference}` is the full qualified class name of the enhanced class. - - -- Matching multiple classes by name, which is the plural version of `nameEquals`, can be obtained with the following method: - ```java - ClassMatcher.nameContains("${class reference array}"); - ``` - Where `${class reference array}` is a full qualified class name mutable array of the enhanced class. - -[ClassFuzzyMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/ClassFuzzyMatcher.java)(the fuzzy matcher of class name) - -- The enhanced class is located by the prefix of full qualified class name, which can be obtained by: - ```java - ClassMatcher.namePrefixedWith("${prefix}"); - ``` - Where `${prefix}` is the prefix of full qualified class name. - - -- The enhanced class is located by the suffix of full qualified class name, which can be retrieved as follows: - ```java - ClassMatcher.nameSuffixedWith("${suffix}") - ``` - Where `${suffix}` is the suffix of full qualified class name. - - -- The enhanced class is located by the infix of full qualified class name, which can be obtained as follows: - ```java - ClassMatcher.nameinfixedWith("${infix}") - ``` - Where `${infix}` is the infix of full qualified class name. - - -- The enhanced class is located by matching the full qualified class name with a regular expression, which can be obtained as follows: - ```java - ClassMatcher.nameMatches("${pattern}") - ``` - Where `${pattern}` is a regular expression. - - -- The enhanced class is located by annotation decorated, which can be obtained as follows: - - ```java - ClassMatcher.isAnnotationWith("${annotation reference array}"); - ``` - Where `${annotation reference array}` is a full qualified class name array of annotations. - - -- Locating a subclass by means of a superclass can be obtained using the following methods: - ```java - ClassMatcher.isExtendedFrom("${super class array}"); - ``` - Where `${super class array}` is a superclass mutable array. Due to Java inheritance rules, the array can only have one `class`, the rest must be `interface`. - - -- A matching logical operation, which is true when all matchers do not match: - ```java - ClassMatcher.not("${class matcher array}") - ``` - Where `${class matcher array}` is a variable-length array of matcher. - - -- A matching logical operation, which is true if the matcher matches all of them: - ```java - ClassMatcher.and("${class matcher array}") - ``` - Where `${class matcher array}` is a variable-length array of matcher. - - -- A matching logical operation, which is true if one of the matcher matches: - ```java - ClassMatcher.or("${class matcher array}") - ``` - Where `${class matcher array}` is a variable-length array of matcher. - -For method interception points [MethodMatcher](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/matcher/MethodMatcher.java), we provide a variety of matching methods: - -- Match any method: - ```java - MethodMatcher.any(); - ``` -- Match by method name: - ```java - MethodMatcher.nameEquals("${method name}"); - ``` - Where `${method name}` is the method name. - - -- Match static method: - ```java - MethodMatcher.isStaticMethod(); - ``` -- Match constructor: - ```java - MethodMatcher.isConstructor(); - ``` -- Match multiple methods: - ```java - MethodMatcher.nameContains("${method name array}"); - ``` - Where `${method name array}` is an array of method names. - - -- Match by prefix of method name: - ```java - MethodMatcher.namePrefixedWith("${method name prefix}"); - ``` - Where `${method name prefix}` is the prefix of method name . - - -- Match by suffix of method name: - ```java - MethodMatcher.nameSuffixedWith("${method name suffix}"); - ``` - Where `${method name suffix}` is the suffix of method name. - - -- Match by infix of method name: - ```java - MethodMatcher.nameinfixedWith("${method name infix}"); - ``` - Where `${method name infix}` is the infix of method name. - - -- Match by regular expression: - ```java - MethodMatcher.nameMatches("${pattern}"); - ``` - Where `${pattern}` is a regular expression. - - -- Matches by annotation: - ```java - MethodMatcher.isAnnotatedWith("${annotations array}"); - ``` - Where `${annotations array}` is the annotation set. - - -- Match by specified number of arguments: - ```java - MethodMatcher.paramCountEquals("${param count}"); - ``` - Where `${param count}` is the number of input parameters. - - -- Match by the specific type of argument: - ```java - MethodMatcher.paramTypeEquals("${param type array}"); - ``` - Where `${param type array}` is the set of input types. - - -- Match by return type - ```java - MethodMatcher.resultTypeEquals("${result type}"); - ``` - Where `${result type}` is the return type. - - -- Logical operation, where the result is true if the method matcher set does not match at all. - ```java - MethodMatcher.not("${element matcher array}"); - ``` - Where `${element matcher array}` is the set of method matcher. - - -- Logical operation, where the result is true if the method matcher set fully matches. - ```java - MethodMatcher.and("${element matcher array}"); - ``` - Where `${element matcher array}` is the set of method matcher. - - -- Logical operation, where the result is true if method matcher set matches one of the result. - ```java - MethodMatcher.or("${element matcher array}"); - ``` - Where `${element matcher array}` is the set of method matcher. - -For more methods matching method, refer to [byte-buddy](https://javadoc.io/doc/net.bytebuddy/byte-buddy/latest/net/bytebuddy/matcher/ElementMatchers.html) methods with a generic type of `MethodDescription` . - -Don't forget to add the *SPI* configuration file for the `PluginDeclarer` interface: - -- Add `META-INF/services` folder under `resources`. -- Add `com.huaweicloud.sermant.core.plugin.agent.declarer.PluginDeclarer` under `META-INF/services` . -- In the above file, type all the enhancements definitions of `PluginDeclarer` in the plugin package separated with LF. - -The `example module` of **Sermant** contains the following example implementation of the `PluginDeclarer` interface: - -- [DemoAnnotationDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoAnnotationDeclarer.java): Locate enhanced class by annotation in the decorated class. -- [DemoNameDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoNameDeclarer.java): Locate enhanced class by name. -- [DemoSuperTypeDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoSuperTypeDeclarer.java): Locate enhanced class by superclass. -- [DemoBootstrapDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoBootstrapDeclarer.java): Enhancement definition for the boot classloader, refer to [Enhancement for Native Class](#Enhancement-for-Native-Class) for details. -- [DemoTraceDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoTraceDeclarer.java): Enhancement definition for the usage of trace tracking, refer to [Trace Tracking](#Trace-Tracking) for details. - -When the plugin developers write the plugin enhancement definition, you can use the above examples as a reference to develop the enhancement definition that meets their own needs. - -#### Enhancement for Native Class - -For *Java* native classes such as `java.lang.Thread`, which are loaded by the `BootStrapClassLoader`, there are two main difficulties in enhancing them: - -- Native classes are loaded by the BootStrapClassLoader, so if we want to enhance them, we need to overwrite the enhanced bytecode back into the BootStrapClassLoader. Considering that the enhanced embedded code is mostly written in **interceptors**, this content is mainly loaded by the system class loader `AppClassLoader`, which is not accessible by BootStrapClassLoader. Since [**Advice template class**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/template) invokes the interceptors by reflection, it is allowed to write interceptors without restrictions for enhancement of native classes. - -- Due to *Java* redefining *Class* restrictions, we can't modify the metadata of these native classes, so we can't use byte-buddy delegation to enhance them (by adding delegation properties and static code blocks). Fortunately, we can use [**Advice template class**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/template) with [**byte-buddy advice**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/transformer/BootstrapTransformer.java) technology to enhance. That's what **core module** is doing. - -Combined with the above, there is no difference between native classes and regular classes in terms of enhancement definition and writing interceptors. However, it is desirable for plugin developers to minimize enhancement to native classes for three reasons: - -- Enhancements to native classes tend to be divergent. And enhancements to them are likely to impact other plugins or host functionality. -- The native class enhancement logic will use reflection to invoke interceptor methods in the system classloader. Due to the *Java* redefinition of the *Class*, every time an enhanced method is called, the reflection logic is processed, which significantly limits the *TPS* of the method. -- The enhancements to the native classes involved using the **Advice template class** to generate a dynamic interceptor class. For each enhanced native class method, one will be generated dynamically and they will be loaded by the system classloader. If native classes are enhanced without restriction, loading dynamic classes can also become a significant burden during startup. - -In summary, [**Sermant** core module](../../sermant-agentcore/sermant-agentcore-core) provides the ability to augment *Java* native classes. However, it is not recommended to enhance them without restrictions. If there are multiple enhancement points to choose from, you'd better choose enhancing regular classes. - -In **Sermant** `example module`, [DemoBootstrapDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoBootstrapDeclarer.java) enhances `java.lang.Thread`. You can launch the example application [DemoApplication](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-application/src/main/java/com/huawei/example/demo/DemoApplication.java) to see if `java.lang.Thread` is enhanced properly. - -### Interceptor - -In the development of the new version of the plugin, the distinction between static methods, constructors and instance methods is no longer made at the interceptor level, which reduces the complexity of plugin development. -For `MethodInterceptPoint`, there are three acquisition types: static method, constructor, and instance method. There are also three types of interceptors: - -- [interceptor](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/interceptor/Interceptor.java): the interceptor interface, which contains three methods: - - `before`, the preceding method, which is executed before the interception point. The ExecuteContext parameter is the context of the plugin execution, which encapsulates all the parameters required for the interceptor to operate. Through the skip method, the main process can be skipped and the final method result can be set. Note that the main process cannot be skipped when the constructor is enhanced . - - `after`, the post-method, ends up in the post-method whether or not the intercepted method executes normally. Postmethods can override the return value of the intercepted method with their return value, so developers need to be careful not to return null easily here. - - `onThrow`, an exception handling method that is triggered when the intercepted method executes an exception. Handling the exception here does not affect the normal throwing of the exception. - -The `example module` of **Sermant** contains the following example interceptor: - -- [DemoStaticInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoStaticInterceptor.java): an ordinary static method interceptor -- [DemoConstInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoConstInterceptor.java): an ordinary constructor interceptor -- [DemoMemberInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoMemberInterceptor.java): an ordinary instance method interceptor -- [DemoConfigInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoConfigInterceptor.java): an example interceptor for the plugin configuration acquisition, as described in the [Plugin Configuration](#Plugin-Configuration) section. -- [DemoServiceInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoServiceInterceptor.java): an example interceptor for the usage of plugin service, as described in the [Plugin Service](#Plugin-Service) section. - -When writing custom interceptors, plugin developers can use the above example as a reference to develop interceptors that meet their own functional needs. - -### Plugin Configuration - -**Plugin Configuration** refers to the configuration system used in plugin packages and plugin service packages. It consists of three main parts: - -- [PluginConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config/PluginConfig.java) plugin configuration interface: All normal plugin configurations must implement this interface. - -- [PluginConfigManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config/PluginConfigManager.java) plugin configuration manager: provides a method to get the plugin configuration `PluginConfig` : - - ```java - // ${plugin config class} is the plugin configuration class - PluginConfigManager.getPluginConfig(${plugin config class}); - ``` - `PluginConfigManager` is the unified configuration manager [ConfigManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/ConfigManager.java), The plugin side can directly use the interface of the latter to obtain plugin configuration and unified configuration: - - ```java - // ${base config class}is the plugin configuration class or unified configuration class - ConfigManager.getConfig(${base config class}); - ``` - -From the **Sermant** `example module` plugin configuration file [config.yaml](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/config/config.yaml) can be seen that the configuration file is a *yaml file*. The `plugin` and `service` configurations of a `main` plugin module are encapsulated in a single `config.yaml`. - -Instead of a traditional *YAML* format configuration file for a single *Java Pojo* object, here `config.yaml` can encapsulate multiple *Java Pojos*, which are distinguished by fully qualified names or aliases, forming a *Map-like* structure. The key `demo.test` corresponds to the [DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java) object in the **example plugin package** and `com.huawei.example.demo.config.DemoServiceConfig` key corresponds to [DemoServiceConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service/src/main/java/com/huawei/example/demo/config/DemoServiceConfig.java) object in the **example plugin service pack**. - -Compared to `DemoServiceConfig`, [DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java) is decorated with the [ConfigTypeKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigTypeKey.java) annotation, so the `demo.test` alias is set. If it is not annotated with the `ConfigTypeKey` annotation, the full qualified class name is used as the index. - -The `map` property in [DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java) is annotated with [ConfigFieldKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigFieldKey.java), changing its property name to `str2DemoSimplePojoMap`. However, it is important to note that the semantics of the **Java Pojo** using this annotation is invalid if it is wrapped by an array, a *List* or a *Map*. Therefore, for now, this annotation can only be used to modify the current **plugin configuration class** or directly used **Java Pojo**. - -As [DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java)[DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java) shows, plugin configuration now supports data types include: - -- Primitive and wrapper types for Boolean and numeric classes -- String -- Enum -- Complex object -- Array of the above types -- List of the first four types -- Map of the first four types - -*YAML* format configuration files currently have a few other rules: - -- For complex objects involved in arrays, lists, and maps, using `ConfigFieldKey` to fix property names is not supported. -- For strings in arrays, lists, and maps, there is no support for `${}` conversions, **plugin configuration class** string properties and string properties inside complex type properties are supported. -- Parameters are only used for string `${}` conversions. Direct setting property values using parameters is not supported. -- The field names of configuration classes are usually small camels.You can use [ConfigFieldKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigFieldKey.java) to define aliases for the transverse-line style. After the annotation is added, it can be parsed in *YAML* using either transverse-line or small camel style. Refer to the `intField` of [DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java). -- The priority of the configuration is: startup parameters > environment variables > system variables (-d parameter) > *YAML* file configuration -- The camel style and transverse line can be used to split words to look for matches when the configuration class properties fetch reference values according to the priority(startup parameters, environment variables, and system variables (-d parameter)) in effect. For example, for `intField` of [DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java), the key will be transformed into one of the following forms and searched in order: - - demo.test.intField - - demo_test_intField - - demo-test-intField - - DEMO.TEST.INTFIELD - - DEMO_TEST_INTFIELD - - DEMO-TEST-INTFIELD - - demo.test.intfield - - demo_test_intfield - - demo-test-intfield - - demo.test.int.field - - demo_test_int_field - - demo-test-int-field - - DEMO.TEST.INT.FIELD - - DEMO_TEST_INT_FIELD - - DEMO-TEST-INT-FIELD -- If the key of the basic data type/array /map/list/set(which does not support complex objects) is not defined in the *YAML* configuration, the reference value will be obtained according to the priority of the configuration effect: startup parameters > environment variables > system variables (-d parameter). When retrieving reference values from the above data sources, note that: - - The array /list/set should be configured in `YAML` string format. For example: DEMO_TEST_LIST_NAME=[elem1,elem2] - - The map needs to be configured as a `YAML` string format. For example: DEMO_TEST_MAP_NAME={key1: value1, key2: value2} - -Most of the possible configuration scenarios are covered in [DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java), plugin developers can reference and write plugin configuration classes that meet your business needs. - -Finally, don't forget to add the *SPI* configuration file for the plugin configuration: - -- Add `META-INF/services` folder under `resources`. -- Add `com.huaweicloud.sermant.core.plugin.config.PluginConfig` configuration file under `META-INF/services`. -- In the above file, type the `PluginConfig` implementation for all plugin configurations in the plugin package and separate them by LF. - -### Plugin Service - -**Plugin service** refers to the service system used in plugin package and plugin service package. It mainly consists of two parts: - -- [PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java), the plugin service interface. -- [PluginServiceManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginServiceManager.java), the plugin service manager, which provides an interface to get `PluginService` : - - ```java - // ${plugin service class} is the plugin service class - PluginServiceManager.getPluginService(${plugin service class}); - ``` - `PluginServiceManager` is a particular case of [ServiceManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/ServiceManager.java). The latter interface can be used directly to access the core and plugin services: - - ```java - // ${base service class}is the core service class or plugin service class - ServiceManager.getService(${base service class}); - ``` - - Learned form [Plugin Module Development Guide](dev_plugin_module.md#Add-Plugin-Module), plugins can be categorized as **simple plugins** and **complex plugins**, depending on the complexity of the service they define: - - - Services defined in **simple plugins** can only use *Java* native *APIs*, self-developed *APIs* (start with `com.huawei`) in [**Sermant** core module](../../sermant-agentcore/sermant-agentcore-core) , and *APIs* of `byte-buddy` and `slf4j`. - - In addition to the above *API*, the services in **complex plugins** have the right to use other *APIs* that third parties rely on. These services need to be separated into the **plugin service interface** and the **plugin service implementation**: the former is written in the `plugin` module for the interceptor to invoke. The latter is written in the `service` module and loaded by a custom *ClassLoader* to achieve classloader-level dependency isolation. - -#### Simple Plugin Service - -As for **simple plugin service**, you can just implement [PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java), such as [DemoSimpleService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoSimpleService.java). Based on the implementation of the `start` and `stop` methods, you can add other required methods such as the `activeFunc` method. Get an instance of the `DemoSimpleService` and invoke the `activeFunc` method with the following code: -```java -DemoSimpleService simpleService = PluginServiceManager.getPluginService(DemoSimpleService.class); -simpleService.activeFunc(); -``` - -For **simple plugin service**, the only restriction is to use only the *Java* native *API*, [**Sermant** core module](../../sermant-agentcore/sermant-agentcore-core) self-developed *APIs* (starting with `com.huawei`) and *APIs* in `byte-buddy` and `slf4j`. - -Plugin developers can refer to [DemoSimpleService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoSimpleService.java) to write **simple plugin services** for your business on demand. - -Finally, don't forget to add the *SPI* configuration file for [PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java): - -- Add `META-INF/services` folder under `resources`. -- Add `com.huaweicloud.sermant.core.plugin.service.PluginService` configuration file under `META-INF/services`. -- In the above file, type the `PluginService` implementation for all plugin services in the plugin package and separate them by LF. - -In particular, do not try to get instances of other **plugin services** in the `start` method of `PluginService`, since **plugin services** are still being initialized and it may not be possible to get these **plugin services** correctly. - -#### Complex Plugin Service - -There are only two differences between **complex plugin service** and **simple plugin service**: - -- **Complex plugin services** write their interface in the `plugin` module and their implementation in the [Plugin Service Module](#Plugin-Service-Module), while **simple plugin services** do not need to write the interface and are implemented directly in the `plugin` module. -- The implementation of a **complex plugin service** can use any third-party dependency on demand. - -[DemoComplexService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoComplexService.java) is a **complex plugin service** sample interface. Methods can be added on demand, such as the `activeFunc` method. [DemoComplexServiceImpl](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service/src/main/java/com/huawei/example/demo/service/DemoComplexServiceImpl.java) is the corresponding implementation. We can invoke the `activeFunc` method with the following code: - -```java -DemoComplexService complexService = PluginServiceManager.getPluginService(DemoComplexService.class); -complexService.activeFunc(); -``` - -Adding *SPI* configuration and other considerations is no different than **simple plugin service**. Developers can refer the `DemoComplexService` interface and `DemoComplexServiceImpl` implementation to write **complex plugin services** that meet business requirements. - -#### Log - -Considering dependency isolation, [**Sermant** core module](../../sermant-agentcore/sermant-agentcore-core) provides the `plugin` and `service` to use only **jul** log. Get the **jul** log instance by: - -```java - -import com.huaweicloud.sermant.core.common.LoggerFactory; -Logger logger=LoggerFactory.getLogger(); -``` - -Plugin developers who need to output log information can refer to [DemoLogger](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/common/DemoLogger.java) sample development. - -#### Heartbeat - -Heartbeat is one of the core services in [**Sermant** core module](../../sermant-agentcore/sermant-agentcore-core). An instance of heartbeatService is obtained by: -```java -HeartbeatService heartbeatService = ServiceManager.getService(HeartbeatService.class); -``` - -The heartbeat service starts execution when it is initialized, and periodically sends the name, version and other information of each plugin to the backend server. Currently, plugin heartbeats report information like: - -- `hostname`: the hostname of the sending client -- `ip`: the ip of the sending client -- `app`: application name, as well as `appName` in startup parameters -- `appType`: application type,as well as `appType` in startup parameters -- `heartbeatVersion`: time of last heartbeat -- `lastHeartbeat`: time of last heartbeat -- `version`: the version of the core package, as well as the `sermant-version` value of the core package `manifest` file -- `pluginName`: plugin name -- `pluginVersion`:plugin version, which is the `Sermant-plugin-version` value of the `manifest` file in the plugin jar - -If you want to add additional content to the data reported by the plugin, you can call the following API: -```java -// use ExtInfoProvider to add additional content -heartbeatService.setExtInfo(new ExtInfoProvider() { - @Override - public Map getExtInfo() { - // do something - } -}); -``` - -Plugin developers who need to add additional content to the packets sent by the heartbeat function can refer to [DemoHeartBeatService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoHeartBeatService.java) sample development. - -For more information about heartbeat services, see [Heartbeat Service](service_heartbeat.md). - -#### Trace Tracking - -The **Trace Tracking** is an upper layer function established by message sending capability, which simply means embedding the following logic between the invoke chains of the host side: - -- When sending data, the `TraceId` and `SpanId` required by the trace are inserted in the data packet. The former is the view of the whole trace in the distributed system, and the later represents the view inside the different services in the whole trace. -- When receiving data, it parses the trace-related content embedded in the data packet, forms a trace and submits it to the backend server, and gradually forms a invoke chain. - -In the [DemoTraceService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-application/src/main/java/com/huawei/example/demo/service/DemoTraceService.java), the `counsumer` and `provider` methods mimic how the server receives data and handles sending it, while the packet is assumed to exist in a `ThreadLocal` until the next invocation to the `provider` method receives the data. - -Based on the above example host application, we write enhancement definition [DemoTraceDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoTraceDeclarer.java) and enhance `provider` and `consumer` of `DemoTraceService` by [DemoTraceProviderInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoTraceProviderInterceptor.java) and [DemoTraceConsumerInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoTraceConsumerInterceptor.java) respectively - -- For the sending `provider` method, the following enhancements are made: - ```java - private final TracingService tracingService = ServiceManager.getService(TracingService.class); - - @Override - public ExecuteContext before(ExecuteContext context) throws Exception { - TracingRequest request = - new TracingRequest(context.getRawCls().getName(), context.getMethod().getName()); - ExtractService> extractService = (tracingRequest, carrier) -> { - tracingRequest.setTraceId(carrier.get(TracingHeader.TRACE_ID.getValue())); - tracingRequest.setParentSpanId(carrier.get(TracingHeader.PARENT_SPAN_ID.getValue())); - tracingRequest.setSpanIdPrefix(carrier.get(TracingHeader.SPAN_ID_PREFIX.getValue())); - }; - tracingService.onProviderSpanStart(request, extractService, (HashMap)context.getArguments()[0]); - return context; - } - - @Override - public ExecuteContext after(ExecuteContext context) throws Exception { - tracingService.onSpanFinally(); - return context; - } - - @Override - public ExecuteContext onThrow(ExecuteContext context) throws Exception { - tracingService.onSpanError(context.getThrowable()); - return context; - } - ``` - -- For the `consumer` method, the following enhancements are made: - ```java - TracingService tracingService = ServiceManager.getService(TracingService.class); - - @Override - public ExecuteContext before(ExecuteContext context) throws Exception { - return context; - } - - @Override - public ExecuteContext after(ExecuteContext context) throws Exception { - TracingRequest request = - new TracingRequest(context.getRawCls().getName(), context.getMethod().getName()); - InjectService> injectService = (spanEvent, carrier) -> { - carrier.put(TracingHeader.TRACE_ID.getValue(), spanEvent.getTraceId()); - carrier.put(TracingHeader.PARENT_SPAN_ID.getValue(), spanEvent.getSpanId()); - carrier.put(TracingHeader.SPAN_ID_PREFIX.getValue(), spanEvent.getNextSpanIdPrefix()); - }; - tracingService.onConsumerSpanStart(request, injectService, (HashMap)context.getResult()); - tracingService.onSpanFinally(); - return context; - } - - @Override - public ExecuteContext onThrow(ExecuteContext context) throws Exception { - tracingService.onSpanError(context.getThrowable()); - return context; - } - ``` - If the plugin developers need to use the trace tracking function, refer to [DemoTraceNormalInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoTraceNormalInterceptor.java) for further development. - - -### Dynamic Configuration - -Dynamic configuration is one of the core services in [**Sermant** core module](../../sermant-agentcore/sermant-agentcore-core). An instance is obtained by: -```java -DynamicConfigService service = ServiceManager.getService(DynamicConfigService.class); -``` - -Invoke the following method to register a listener: -```java -// ${group} is user group,${key} is the key listened. For zookeeper, the path is: / + ${group} + ${key} -// if ${group} do not exist,it will set the value by dynamicconfig.default_group in unified configuration -service.addConfigListener("${key}", "${group}", new DynamicConfigListener() { - @Override - public void process(ConfigChangedEvent event) { - // do something - } -}); -``` - -Once the listener is registered, the `process` method will be triggered when the server creates, deletes, modifies, or adds child nodes. - -Plugin developers who need to use dynamic configuration can refer to [DemoDynaConfService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoDynaConfService.java) sample development. - -For more information on dynamic configuration service, refer to [Dynamic Configuration Service](service_dynamicconfig.md). - - -## Plugin Service Module - -Compared to **plugin module**, **plugin service module** : - -- can only write a **plugin configuration** and **plugin service interface** implementation, and cannot write **enhancement definition ** **interceptor** and **plugins service interface**. -- allow the freedom to add third-party dependencies as needed. When packaging, you need to provide a way to export dependencies, you can use the `shade` plugin or `assembly` plugin to export the dependency *jar* package, or you can directly use the `dependency` plugin to export the dependency package. - -Note: Due to the limitations of the `byte-buddy` and `slf4j` packages, it is still recommended to use the `shade` plugin package directly. The relevant rules are defined in the [main module of plugins](../../sermant-plugins). You can directly import the plugin. Refer to [Plugin Module Development Guide](dev_plugin_module.md#Add-Plugin-Service-Module) for details. - -The **plugin service module** usually involves writing [plugin configuration](#Plugin-Configuration) and [plugin service](#Plugin-Service), where **plugin service** mainly refers to the implementation of [complex plugin service](#Complex-Plugin-Service). - -[Back to README of **Sermant**](../README.md) \ No newline at end of file diff --git a/docs/dev-guide/dev_plugin_introduce-zh.md b/docs/dev-guide/dev_plugin_introduce-zh.md deleted file mode 100644 index e0b50d81a3..0000000000 --- a/docs/dev-guide/dev_plugin_introduce-zh.md +++ /dev/null @@ -1,433 +0,0 @@ -# Sermant 插件开发说明 - -[简体中文](dev_plugin_introduce-zh.md) | [English](dev_plugin_introduce.md) - -## 1. 环境准备 - -- IDEA -- Maven3.* -- Java idk 8/11 - -## 2. 通过模版生成插件项目 - -- IDEA 新建项目 - ![idea_new_project.png](../binary-docs/idea_new_project.png) - -- 增加 Archetype - ![add_archetype.png](../binary-docs/add_archetype.png) - ![archetype_info.png](../binary-docs/archetype_info.png) -```properties -GroupId: com.huaweicloud.sermant.examples -ArtifactId: sermant-examples-archetype -Version: 0.0.1 -``` -- 创建项目 - ![create_project_by_template.png](../binary-docs/create_project_by_template.png) - -- 生成插件项目 - ![create_project_by_template_result.png](../binary-docs/create_project_by_template_result.png) - -## 3. 新建插件项目 - -本部分仅说明插件去源码开发文件配置情况,具体插件开发参考[插件模块开发手册](dev_plugin_module-zh.md)和[插件代码开发手册](dev_plugin_code-zh.md)。 - -### 3.1 IDEA创建maven工程(本文档创建的工程名为**sermant-test**) - -- 创建插件模块(本文档创建插件模块名为**template**) -- 在插件模块中创建plugin子模块(本文档创建的子模块名为**template-plugin**) -- 在插件模块中创建service子模块(本文档创建的子模块名为**template-service**) -- 在主项目**sermant-test**下创建config目录 -- 在插件**template**模块下创建config目录 - -### 3.2 在主项目**sermant-test**下config目录增加以下文件: - -- [bootstrap.properties](https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/bootstrap.properties)(启动配置文件,该配置为Sermant实例指定启动信息) - -```properties -appName=default -appType=0 -instanceName=default -``` - -- [config.properties](https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/config.properties)(核心配置文件,该配置为Sermant启动的核心配置集,指定了Sermant的一些运行机制和服务的运行逻辑) - -```properties -# agent config -agent.config.isEnhanceBootStrapEnable=false -agent.config.ignoredPrefixes=com.huawei.sermant,com.huaweicloud.sermant -agent.config.combineStrategy=ALL -agent.config.serviceBlackList=com.huaweicloud.sermant.implement.service.heartbeat.HeartbeatServiceImpl,com.huaweicloud.sermant.implement.service.send.NettyGatewayClient,com.huaweicloud.sermant.implement.service.tracing.TracingServiceImpl -agent.config.serviceInjectList=com.huawei.discovery.service.lb.filter.NopInstanceFilter,com.huawei.discovery.service.lb.DiscoveryManager - -# adaptor config -adaptor.config.isLoadExtAgentEnable=false - -# dynamic config -dynamic.config.timeoutValue=30000 -dynamic.config.defaultGroup=sermant -dynamic.config.serverAddress=127.0.0.1:2181 -dynamic.config.dynamicConfigType=ZOOKEEPER -dynamic.config.connectRetryTimes=5 -dynamic.config.connectTimeout=1000 -dynamic.config.userName= -dynamic.config.password= -dynamic.config.privateKey= -dynamic.config.enableAuth=false - -# heartbeat config -heartbeat.interval=30000 - -#backend config -backend.nettyIp=127.0.0.1 -backend.nettyPort=6888 -backend.httpIp=127.0.0.1 -backend.httpPort=8900 - -# service meta config -service.meta.application=default -service.meta.version=1.0.0 -service.meta.project=default -service.meta.environment= -service.meta.zone= - -``` - -- [plugins.yaml](https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/plugins.yaml)(插件配置文件,该配置指定Sermant启动时加载的插件和适配器,名称为开发插件时在pom中配置的) - -```yaml -plugins: - - pluginName -``` - -- [logback.xml](https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/logback.xml)(日志配置文件,该配置为日志配置,指定了日志的输出规则,在sermant-agentcore-core中对日志依赖进行了shade,所以此处的Appender不可做修改,需按照如下配置进行操作) - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ERROR - ACCEPT - DENY - - - - ${log.pattern} - - - - - - - - ${log.home_dir}/app/%d{yyyy-MM-dd}/${log.app_name}-%i.log - ${log.maxHistory} - ${log.maxSize} - ${log.totalSize} - true - - - - ${log.pattern} - - - - - - - - - - - -``` - -### 3.3 在插件**template**模块下config目录增加以下文件: - -- config.yaml(插件配置文件,根据插件实际情况,有配置文件则需要创建,无配置则不需创建) - -### 3.4 pom文件配置 - -#### 3.4.1 在插件模块(本文档中**template**)项目的pom文件中增加以下内容: - -- ``字段根据实际需要可以更改版本。 -- ``字段根据实际情况需要修改插件名。 - -```xml - - - ${pom.basedir}/.. - x.x.x - template - com.huaweicloud.sermant.dependencies - ${sermant.basedir}/agent/pluginPackage - undefined - ${package.plugin.dir}/${package.plugin.name}/${package.plugin.type} - ${project.version} - ../config - ${package.plugin.dir}/${package.plugin.name}/config - 8 - 8 - -``` - -```xml - - - - - org.apache.maven.plugins - maven-resources-plugin - 3.1.0 - false - - - package - - copy-resources - - - ${sermant.basedir}/agent/config - true - - - ${config.source.dir} - - bootstrap.properties - config.properties - logback.xml - plugins.yaml - - - - - - - - - org.apache.maven.plugins - maven-clean-plugin - 2.5 - false - - - agent-clean - clean - - clean - - - - - ${sermant.basedir}/agent - - - - - - - - org.apache.maven.plugins - maven-dependency-plugin - 3.3.0 - false - - - copy - package - - copy - - - - - - - com.huaweicloud.sermant - sermant-agentcore-premain - ${sermant.version} - jar - false - ${sermant.basedir}/agent - sermant-agent.jar - - - com.huaweicloud.sermant - sermant-agentcore-core - ${sermant.version} - jar - false - ${sermant.basedir}/agent/core - - - com.huaweicloud.sermant - sermant-agentcore-implement - ${sermant.version} - jar - false - ${sermant.basedir}/agent/implement - - - com.huaweicloud.sermant - sermant-common - ${sermant.version} - jar - false - ${sermant.basedir}/agent/common - - - - - - - - - - org.apache.maven.plugins - maven-jar-plugin - - - - ${package.plugin.name} - ${package.plugin.version} - - - - - - org.apache.maven.plugins - maven-resources-plugin - - - package - - copy-resources - - - ${config.output.dir} - true - - - ${config.source.dir} - - config.yaml - - - - - - - - - - org.apache.maven.plugins - maven-shade-plugin - - - package - - shade - - - - - ${package.output.dir}/${project.artifactId}-${project.version}.jar - - - net.bytebuddy - ${shade.common.prefix}.net.bytebuddy - - - - - - - - - - - -``` - -#### 3.4.2 在子模块(本文档中template-plugin)项目中的pom文件中增加以下内容: - -- ``字段根据实际情况需要修改插件名。 - -```xml - - - ${pom.basedir}/../.. - template - plugin - false - -``` - -```xml - - - - - org.apache.maven.plugins - maven-shade-plugin - - - -``` - -#### 3.4.3 在子模块(本文档template-plugin)项目中的pom文件中增加以下内容: - -- ``字段根据实际情况需要修改插件名。 - -```xml - - - ${pom.basedir}/../.. - template - service - -``` - -```xml - - - - - org.apache.maven.plugins - maven-shade-plugin - - - -``` - -#### 3.4.5 打包 - -- 在父工程(本文档中sermant-plugin-template)下执行```mvn clean package -DskipTests``` -- 在父工程(本文档中sermant-plugin-template)出现agent目录,即为最终结果。 \ No newline at end of file diff --git a/docs/dev-guide/dev_plugin_introduce.md b/docs/dev-guide/dev_plugin_introduce.md deleted file mode 100644 index 825c337dc5..0000000000 --- a/docs/dev-guide/dev_plugin_introduce.md +++ /dev/null @@ -1,441 +0,0 @@ -# Introduction To Sermant Plugin Development - -[简体中文](dev_plugin_introduce-zh.md) | [English](dev_plugin_introduce.md) - -## 1. ENV - -- IDEA -- Maven3.* -- Java idk 8/11 - -## 2. Dev Sermant Plugin By Use Plugin Template - -- IDEA New Project - ![idea_new_project.png](../binary-docs/idea_new_project.png) - -- Add Archetype - ![add_archetype.png](../binary-docs/add_archetype.png) - ![archetype_info.png](../binary-docs/archetype_info.png) - -```properties -GroupId:com.huaweicloud.sermant.examples -ArtifactId:sermant-examples-archetype -Version:0.0.1 -``` - -- Create Project - ![create_project_by_template.png](../binary-docs/create_project_by_template.png) - -- Result - ![create_project_by_template_result.png](../binary-docs/create_project_by_template_result.png) - -## 3. Dev Sermant Plugin By Create Plugin Project - -This section describes the configuration of the plugin development file no source,specific plugin development -reference [Plugin Module Development Guide](dev_plugin_module.md) and [Plugin Code Development Guide](dev_plugin_code.md). - -### 3.1 IDEA Creates A Maven Project (The Project Created in This Document is Named **sermant-test**) - -- Create a plugin module (this document creates in this document a plugin module named **template**) -- Create a plugin submodule in the plugin module (the submodule created in this document is named ** - template-plugin**) -- Create a service submodule in the plugin module (the submodule created in this document is named ** - template-service**) -- Create a config directory under the main project **sermant-test** -- Create a config directory under the plugin **template** module - -### 3.2 Add The Following Files To The Config Directory Of The Main Project **sermant-test** - -- [bootstrap.properties](https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/bootstrap.properties) (startup configuration file, which specifies startup information for the Sermant instance) - -```properties -appName=default -appType=0 -instanceName=default -``` - -- [config.properties](https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/config.properties) (core configuration file, this configuration is the core configuration set started by Sermant, - specifying some operating mechanisms of Sermant and the running logic of services) - -```properties -# agent config -agent.config.isEnhanceBootStrapEnable=false -agent.config.ignoredPrefixes=com.huawei.sermant,com.huaweicloud.sermant -agent.config.combineStrategy=ALL -agent.config.serviceBlackList=com.huaweicloud.sermant.implement.service.heartbeat.HeartbeatServiceImpl,com.huaweicloud.sermant.implement.service.send.NettyGatewayClient,com.huaweicloud.sermant.implement.service.tracing.TracingServiceImpl -agent.config.serviceInjectList=com.huawei.discovery.service.lb.filter.NopInstanceFilter,com.huawei.discovery.service.lb.DiscoveryManager - -# adaptor config -adaptor.config.isLoadExtAgentEnable=false - -# dynamic config -dynamic.config.timeoutValue=30000 -dynamic.config.defaultGroup=sermant -dynamic.config.serverAddress=127.0.0.1:2181 -dynamic.config.dynamicConfigType=ZOOKEEPER -dynamic.config.connectRetryTimes=5 -dynamic.config.connectTimeout=1000 -dynamic.config.userName= -dynamic.config.password= -dynamic.config.privateKey= -dynamic.config.enableAuth=false - -# heartbeat config -heartbeat.interval=30000 - -#backend config -backend.nettyIp=127.0.0.1 -backend.nettyPort=6888 -backend.httpIp=127.0.0.1 -backend.httpPort=8900 - -# service meta config -service.meta.application=default -service.meta.version=1.0.0 -service.meta.project=default -service.meta.environment= -service.meta.zone= -``` - -- [plugins.yaml](https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/plugins.yaml) (plugin configuration file, the configuration specifies the plugins and adapters loaded when Sermant - starts, the name is the configured in the pom when developing the plugin) - -```yaml -plugins: - - pluginName -``` - -- [logback.xml](https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/logback.xml) (log configuration file, this configuration is the log configuration, which specifies the output rules of - the log. The log dependency is shaded in the sermant-agentcore-core, so the Appender here cannot be modified, and the - following configuration is required. operate) - -```xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - ERROR - ACCEPT - DENY - - - - ${log.pattern} - - - - - - - - ${log.home_dir}/app/%d{yyyy-MM-dd}/${log.app_name}-%i.log - ${log.maxHistory} - ${log.maxSize} - ${log.totalSize} - true - - - - ${log.pattern} - - - - - - - - - - - -``` - -### 3.3 Add The Following Files To The Config Directory Under The Plugin **template** Module: - -- config.yaml (plugin configuration file, according to the actual situation of the plugin, if there is a configuration - file, it needs to be created, if there is no configuration, it does not need to be created) - -### 3.4 Pom File Configuration - -#### 3.4.1 Add The Following Content To The Pom File Of The Plugin Module (**template** In This Document) Project: - -- The `` field can change the version according to actual needs. -- The `` field needs to modify the plugin name according to the actual situation. - -```xml - - - ${pom.basedir}/.. - x.x.x - template - com.huaweicloud.sermant.dependencies - ${sermant.basedir}/agent/pluginPackage - undefined - ${package.plugin.dir}/${package.plugin.name}/${package.plugin.type} - ${project.version} - ../config - ${package.plugin.dir}/${package.plugin.name}/config - 8 - 8 - -``` - -```xml - - - - - org.apache.maven.plugins - maven-resources-plugin - 3.1.0 - false - - - package - - copy-resources - - - ${sermant.basedir}/agent/config - true - - - ${config.source.dir} - - bootstrap.properties - config.properties - logback.xml - plugins.yaml - - - - - - - - - org.apache.maven.plugins - maven-clean-plugin - 2.5 - false - - - agent-clean - clean - - clean - - - - - ${sermant.basedir}/agent - - - - - - - - org.apache.maven.plugins - maven-dependency-plugin - 3.3.0 - false - - - copy - package - - copy - - - - - - - com.huaweicloud.sermant - sermant-agentcore-premain - ${sermant.version} - jar - false - ${sermant.basedir}/agent - sermant-agent.jar - - - com.huaweicloud.sermant - sermant-agentcore-core - ${sermant.version} - jar - false - ${sermant.basedir}/agent/core - - - com.huaweicloud.sermant - sermant-agentcore-implement - ${sermant.version} - jar - false - ${sermant.basedir}/agent/implement - - - com.huaweicloud.sermant - sermant-common - ${sermant.version} - jar - false - ${sermant.basedir}/agent/common - - - - - - - - - org.apache.maven.plugins - maven-jar-plugin - - - - ${package.plugin.name} - ${package.plugin.version} - - - - - - org.apache.maven.plugins - maven-resources-plugin - - - package - - copy-resources - - - ${config.output.dir} - true - - - ${config.source.dir} - - config.yaml - - - - - - - - - org.apache.maven.plugins - maven-shade-plugin - - - package - - shade - - - - - ${package.output.dir}/${project.artifactId}-${project.version}.jar - - - net.bytebuddy - ${shade.common.prefix}.net.bytebuddy - - - - - - - - - - - -``` - -#### 3.4.2 Add The Following To The Pom File In The Submodule (template-plugin In This Document) Project: - -- The `` field needs to modify the plugin name according to the actual situation. - -```xml - - - ${pom.basedir}/../.. - template - plugin - false - -``` - -```xml - - - - - org.apache.maven.plugins - maven-shade-plugin - - - -``` - -#### 3.4.3 Add The Following To The Pom File In The Submodule (template-plugin) Project: - -- The `` field needs to modify the plugin name according to the actual situation. - -```xml - - - ${pom.basedir}/../.. - template - service - -``` - -```xml - - - - - org.apache.maven.plugins - maven-shade-plugin - - - -``` - -#### 3.4.5 Package - -- Execute `mvn clean package -DskipTests` under the parent project (sermant-plugin-template in this document) -- The agent directory appears in the parent project (sermant-plugin-template in this document), which is the final - result. \ No newline at end of file diff --git a/docs/dev-guide/dev_plugin_module-zh.md b/docs/dev-guide/dev_plugin_module-zh.md deleted file mode 100644 index 65eac35d2b..0000000000 --- a/docs/dev-guide/dev_plugin_module-zh.md +++ /dev/null @@ -1,449 +0,0 @@ -# 插件模块开发手册 - -[简体中文](dev_plugin_module-zh.md) | [English](dev_plugin_module.md) - -本文档主要针对**Sermant**的[插件根模块](../../sermant-plugins),介绍如何在`插件根模块`中添加一个插件及其服务和附加件。 - -- [开发环境](#开发环境) -- [组成分类](#组成分类) -- [打包流程](#打包流程) -- [添加插件主模块](#添加插件主模块) - - [插件名称和版本](#插件名称和版本) -- [插件开发流程](#插件开发流程) - - [插件开发前言](#插件开发前言) - - [添加插件模块](#添加插件模块) - - [添加插件服务模块](#添加插件服务模块) - - [添加配置](#添加配置) - - [示例工程解读](#示例工程解读) - - [注意事项](#注意事项) - - [插件打包流程](#插件打包流程) -- [附加件开发流程](#附加件开发流程) - -## 开发环境 - -- [HuaweiJDK 1.8](https://gitee.com/openeuler/bishengjdk-8) / [OpenJDK 1.8](https://github.com/openjdk/jdk) / [OracleJDK 1.8](https://www.oracle.com/java/technologies/downloads/) -- [Apache Maven 3](https://maven.apache.org/download.cgi) - -## 组成分类 - -**Sermant**的`插件根模块`按照插件功能划分子模块,即`插件主模块(main)`,其中又可以包含以下类型的子模块: - -- `插件模块(plugin)`,该模块主要用于声明对宿主应用的增强逻辑 -- `服务模块(service)`,用于为插件包提供服务实现 -- `后端模块(server)`,用于接收插件数据的服务端 -- `前端模块(webapp)`,用于对服务端数据作前端展示 -- `其他模块(other)`,特殊附加件,一般用作调试 - -## 打包流程 - -目前[Sermant](../../pom.xml)的打包流程中,包含`agent`、`test`和`release`等 -6个步骤,其中与[sermant-plugins](../../sermant-plugins/pom.xml)相关的步骤如下: - -- `agent`: 对所有Sermant中包含的稳定版本的`插件模块(plugin)`和`服务模块(service)`进行打包,他们将输出到产品`agent/pluginPackage/${功能名称}`目录; 对所有稳定版本的附加件进行打包,包括`后端模块(server)`、`前端模块(webapp)`和`其他模块(other)`,其中`后端模块(server)`和`前端模块(webapp)`将输出到产品的`server/${功能名称}`目录,`其他模块(other)`一般为调试用的附加件,没有打包要求。 -- `test`: 对Sermant项目下所有的`插件模块(plugin)`、`服务模块(service)`和附加件进行打包。 -- `release`: 对需发布至maven中心仓的稳定版本的模块进行打包。 - -## 添加插件主模块 - -- 添加`插件主模块(main)`,依据该`插件主模块(main)`中涉及的内容,在[sermant-plugins的pom文件](../../sermant-plugins/pom.xml)中的特定`profile`中添加相应模块: - - 必须在`id`为`test`的`profile`中添加该模块。 -- 在该模块的`pom.xml`中添加以下标签: - ```xml - pom - ``` - ```xml - - ${pom.basedir}/../../.. - ${插件名称} - - ``` - - 在[默认插件设置文件](../../sermant-agentcore/sermant-agentcore-config/config/plugins.yaml)和[全数插件设置文件](../../sermant-agentcore/sermant-agentcore-config/config/test/plugins.yaml)中添加新增的`插件主模块(main)`,完成注册。 - -`插件主模块(main)`的子模块开发流程参见一下章节: -- `插件模块(plugin)`和`服务模块(service)`开发流程参见[插件开发流程](#插件开发流程) -- `后端模块(server)`和`前端模块(webapp)`开发流程参见[附加件开发流程](#附加件开发流程) -- `其他模块(other)`由于只参与调试,不涉及开发流程限定 - -### 插件名称和版本 - -插件的名称和版本,属于`插件模块(plugin)`和`服务模块(service)`的内禀属性,因此我们将他们封装到`manifest`文件中,作为`jar`包的元信息存在: - -- **插件名称**封装于`manifest`文件的`Sermant-Name-Version`参数中,通过`pom`文件中的`package.plugin.name`参数设定,默认含义为**插件名称**。 -- **插件版本**封装于`manifest`文件的`Sermant-Plugin-Version`参数中,默认取值为`project.version`,可通过`pom`文件中的`package.plugin.version`参数修改。 -```xml - - ${插件名称} - ${插件版本} - -``` - -在插件包被加载的过程中,将对`插件模块(plugin)`和`服务模块(service)`的名称和版本进行校验,如果不满足以下条件的话,将抛出异常: - -- 对于所有`插件模块(plugin)`来说,由于不允许包含`byte-buddy`和`slf4j`以外的第三方依赖,考虑到`byte-buddy`和`slf4j`包将通过`shade`插件修改全限定名,因此,在加载`插件模块(plugin)`存放目录(`插件主模块(main)`目录下的`plugin`目录)时,如果检出不含**插件名称**和**插件版本**的第三方包,将抛出异常。 -- 对于所有`插件模块(plugin)`和`服务模块(service)`来说,如果其中设置的**插件名称**与**插件设定文件**中配置的名称不一致,将抛出异常。 -- 对于所有`插件模块(plugin)`和`服务模块(service)`来说,如果其中存在多个不同的**插件版本**,将抛出异常。 - -对于插件开发者来说,如果没有特殊的需要,不建议修改默认的设计,保持`插件模块(plugin)`中不使用`byte-buddy`和`slf4j`以外的第三方依赖、`插件模块(plugin)`写接口、`服务模块(service)`写实现等原则就好。 - -## 插件开发流程 - -本节将介绍插件开发的相关流程,其中涉及的模块为`插件模块(plugin)`和`服务模块(service)`。 - -### 插件开发前言 - -`插件模块(plugin)`的定位是定义宿主应用的增强逻辑,考虑到依赖冲突的问题,其增强的字节码中不能涉及对`byte-buddy`和`slf4j`以外的第三方依赖的使用,这时就需要分两种情况讨论: - -- 对于简单的插件,其中编写的插件服务只会使用核心包中的自研功能,不涉及需要依赖其他第三方依赖的复杂功能时,那么只需要开发`插件模块(plugin)`即可。`插件模块(plugin)`将被系统类加载器`AppClassLoader`加载。 -- 对于一些复杂的插件,如果需要依赖其他第三方依赖的复杂功能时,就需要在`插件模块(plugin)`设计服务接口,并编写`服务模块(service)`予以实现。其中`插件模块(plugin)`仍被系统类加载器`AppClassLoader`加载,而`服务模块(service)`则会优先被自定义类加载器[PluginClassLoader](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/classloader/PluginClassLoader.java)加载,以此达成类加载级别的依赖隔离。 - -至于**核心模块**中的第三方依赖,他们在打包过程中会随自研代码一起,被[shade插件](https://github.com/apache/maven-shade-plugin)修正全限定名。除非`插件模块(plugin)`打包时做同样的全限定名的操作,不然是无法在`插件模块(plugin)`使用的。 - -另外,对于`byte-buddy`包来说,由于方法匹配器没有在**核心模块**中提取,`插件模块(plugin)`仍需沿用他们,因此对`插件模块(plugin)`才有修正`byte-buddy`包全限定名的要求。 - -至于`slf4j`包,考虑到在**复杂插件服务**初始化期间,由于类加载器隔离的问题,导致第三方的`slf4j`接口使用了**核心功能模块**的配置却无法关联到**核心功能模块**的实现,因此只能修正`slf4j`的全限定名以适配。 - -以上就是`插件模块(plugin)`和`服务模块(service)`打包时必须修正`byte-buddy`和`slf4j`的全限定名的原因,也是`插件模块(plugin)`可以使用这两个依赖的原因。 - -### 添加插件模块 - -结合[打包流程](#打包流程)中介绍的步骤,与插件开发相关的步骤有`agent`、`test`和`release`三个`profile`。其中`agent`用于社区release出包,`release`用于maven中心仓库出包,`test`用于开发测试,前期开发使用`test`即可,插件经测试验证稳定后需发布则添加至`agent`或`release`。如果需要为`插件主模块(main)`添加`插件模块(plugin)`子模块: - -- 在`插件主模块(main)`的`pom.xml`文件的以下`profile`中添加`module`: - ```xml - - - agent - - true - - - ${插件模块名} - - - - test - - ${插件模块名} - - - - release - - ${插件模块名} - - - - ``` -- 为`插件模块(plugin)`子模块添加以下参数: - ```xml - - plugin - - ``` -- 为`插件模块(plugin)`子模块添加核心包依赖: - ```xml - - - com.huaweicloud.sermant - sermant-agentcore-core - provided - - - ``` - 注意,不能为`插件模块(plugin)`添加或使用`byte-buddy`和`slf4j`以外的第三方依赖,除非使用`shade`插件将他们的全限定名修正(不建议)! -- 为`插件模块(plugin)`子模块添加`shade`插件,以修正`byte-buddy`和`slf4j`的全限定名,原因详见[插件开发前言](#插件开发前言): - ```xml - - - - org.apache.maven.plugins - maven-shade-plugin - - - - ``` - -### 添加插件服务模块 - -和`插件模块(plugin)`相似,添加`服务模块(service)`步骤如下: - -- 在`插件主模块(main)`的`pom.xml`文件的以下`profile`中添加`module`: - ```xml - - - agent - - true - - - ${插件服务模块名} - - - - test - - ${插件服务模块名} - - - - release - - ${插件服务模块名} - - - - ``` - -- 为`服务模块(service)`子模块添加以下参数: - ```xml - - service - - ``` - -- 为`服务模块(service)`子模块添加核心包和相关插件包的依赖: - ```xml - - - com.huaweicloud.sermant - sermant-agentcore-core - provided - - - com.huaweicloud.sermant - ${插件模块名} - ${插件模块版本} - provided - - - ``` - -- 为`服务模块(service)`中添加第三方依赖或公共依赖 - - - 直接添加 - - `服务模块(service)`中允许按需添加第三方依赖,在`pom.xml`直接以`compile`的方式添加即可。该方式引入的第三方依赖是由各个插件独立的插件类加载器进行加载,插件和宿主应用之间、插件与插件之间都是类隔离的。 - - - 通过引入`sermant-common`间接添加公共第三方依赖 - - Sermant提供了公共类加载机制,各插件的可按需提取公共依赖至`sermant-common`中,以实现插件之间的公共依赖的共享。 - - `服务模块(service)`可通过`provided`的方式引入`sermant-common`,该方式的第三方依赖将由公共类加载器进行加载,各插件不存在类隔离。 - - 若插件服务模块引入`sermant-common`的同时,需使用与`sermant-common`中引入的第三方依赖的不同版本,则需在本模块以`compile`方式引入该版本依赖。改方式引入的第三方依赖是由当前插件的插件类加载器进行加载,与公共类加载器是隔离的。 - -- 为`服务模块(service)`子模块添加`shade`插件打包: - ```xml - - - - org.apache.maven.plugins - maven-shade-plugin - - - - ``` - 这里不建议使用其他打包插件,详见[插件开发前言](#插件开发前言)。 - -### 添加配置 - -如果`插件模块(plugin)`和`服务模块(service)`中需要使用插件配置`PluginConfig`,那么需要添加插件的配置文件: - -- 在`插件主模块(main)`的主目录下添加`config`文件夹。 -- 在`config`文件夹中添加一个`config.yaml`文件,这就是插件的配置文件。 -- 在`插件主模块(main)`的任意子模块(一般取第一个子模块)中添加以下配置以启动资源拷贝: - ```xml - - false - - ``` - 如果配置上述参数的子模块不在`插件主模块(main)`的目录下,还需要根据该模块与`config`目录的相对位置设置以下参数: - ```xml - - ../config - - ``` - -### 示例工程解读 - -[Sermant-examples](https://github.com/huaweicloud/Sermant-examples)是一个示例功能项目,其中`sermant-template`涉及了大部分开发插件时可能碰到的场景,本节将会对该项目示例的内容进行解读,以帮助读者能尽快上手开发插件功能。 - -- 增强定义示例,见于[Declarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer)包: - - [DemoAnnotationDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoAnnotationDeclarer.java)展示如何通过修饰类的注解定位到被增强的类。 - - [DemoNameDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoNameDeclarer.java)展示如何通过名称定位到被增强的类。 - - [DemoSuperTypeDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoSuperTypeDeclarer.java)展示如何通过超类定位到被增强的类。 - - 上述三者都可以看出如何声明用于增强构造函数、静态函数和实例函数的拦截器。 - - 需要添加[EnhanceDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/PluginDeclarer.java)的[spi配置文件](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/resources/META-INF/services/com.huaweicloud.sermant.core.plugin.agent.declarer.PluginDeclarer)。 -- 拦截器示例,见于[interceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor)包: - - [DemoConstInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoConstInterceptor.java)展示了如何编写一个用于增强构造方法的拦截器。 - - [DemoStaticInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoStaticInterceptor.java)展示了如何编写一个用于增强静态方法的拦截器。 - - [DemoMemberInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoMemberInterceptor.java)展示了如何编写一个用于增强实例方法的拦截器。 -- 日志系统使用示例,如[DemoLogger](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/common/DemoLogger.java)展示了如何在插件中获取日志类。 -- 通过心跳功能添加额外参数示例,如[DemoHeartBeatService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoHeartBeatService.java)服务所示,通常使用自定义服务的方式将额外参数带入。 -- 链路功能使用示例,如[DemoTraceNormalInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoTraceNormalInterceptor.java)所示,通常链路功能应用于拦截器,对宿主应用的方法调用过程进行增强,捕获其相关的数据信息并上报。 -- 增强原生类示例,如[DemoBootstrapDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/Java/com/huawei/example/demo/declarer/DemoBootstrapDeclarer.java)所示,与普通类的增强方式无异。但是,考虑到修改原生类是非常危险的且风险扩散的操作,不建议对原生类进行增强。 -- 插件配置示例:插件配置是统一配置系统的特化,遵循统一配置系统的规则。[config.yaml](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/config/config.yaml)是示例工程的配置文件,其中包含[DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java)和[DemoServiceConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service/src/main/java/com/huawei/example/demo/config/DemoServiceConfig.java)两个配置类对应的配置信息,从配置的定义和调用可以看到: - - 每个功能的配置文件仅能有1个,即`config.yaml`文件。 - - 插件包的配置类无论是否有拦截器别名的设定,都需要实现[PluginConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config/PluginConfig.java)接口。 - - 必须添加[PluginConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config/PluginConfig.java)的[spi配置文件](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/resources/META-INF/services/com.huaweicloud.sermant.core.plugin.config.PluginConfig)。 - - 配置类的属性类型可以是布尔、数字、字符串、枚举、复杂对象,以及他们的数组、列表和字典类型。 - - 普通字符串和复杂对象的字符串字段支持`${key:default}`风格的映射,优先级如下: - ``` - javaagent启动参数 > 当前类的其他属性 > 环境变量 > 系统变量 > 默认值 - ``` - 但是,被数组、列表和字典类型包装的字符串将不会做上述映射。 - - 配置类支持使用[ConfigTypeKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigTypeKey.java)注解修改限定名,但是需要确保,所有统一配置的限定名(无论是否修改)不可重复。 - - 配置类及其复杂对象的属性支持使用[ConfigFieldKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigFieldKey.java)注解修改字段的名称。但是,被数组、列表和字典类型包装的复杂对象的属性则不支持修改。 - - 通过以下代码可以获取配置对象: - ```java - PluginConfigManager.getPluginConfig(PluginConfigType.class) - ``` -- 插件服务示例:插件服务是核心服务系统的特化,遵循核心服务系统的规则。 - - 如[DemoSimpleService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoSimpleService.java)所示,是一个简单的插件服务,他编写于`插件模块(plugin)`中。鉴于简单的插件服务的定位,它只能使用java原生api以及核心包中自研的api,不能使用任何第三方api(无论核心包是否引入)。 - - [DemoComplexService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoComplexService.java)接口是示例`插件模块(plugin)`中定义复杂服务接口,该接口将会在`服务模块(service)`中实现。 - - [DemoComplexServiceImpl](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service/src/main/java/com/huawei/example/demo/service/DemoComplexServiceImpl.java)是[DemoComplexService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoComplexService.java)接口的实现,它编写于`服务模块(service)`中,属于复杂的插件服务,可以按需使用其他第三方依赖(示例中未使用)。 - - 简单的插件服务和复杂的插件服务接口都需要继承(实现)[PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java)接口。 - - 需要添加[PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java)的[spi配置文件](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/resources/META-INF/services/com.huaweicloud.sermant.core.plugin.service.PluginService)。 - - 通过以下代码可以获取服务对象: - ```java - ServiceManager.getService(ServiceType.class) - ``` - -更多详细的插件开发相关内容,参见[插件代码开发手册](dev_plugin_code-zh.md)。 - -### 注意事项 - -本节将列举一些开发插件过程中容易出现错误的点: - -- `插件模块(plugin)`不能依赖或使用`byte-buddy`和`slf4j`以外第三方依赖,如果服务功能较为复杂,必须使用其他第三方依赖,则可以将他们提取为`服务模块(service)`,或者用`shade`插件隔离(不建议)。 -- 同个`插件主模块(main)`中,如果存在多个`服务模块(service)`,他们不能存在依赖冲突的问题。 -- 插件的配置文件有且只能有一个,即`config.yaml`。 -- `config.yaml`中,被数组、列表和字典包装的复杂对象将不支持[ConfigFieldKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigFieldKey.java)属性别名,被包装的字符串也将不支持`${xxx}`映射。 -- 配置文件中对应配置类的限定名不能重复,该规则针对全局所有统一配置有效。 -- `插件模块(plugin)`和`服务模块(service)`如果不是定义在`插件主模块(main)`的目录下,需要留意输出的jar包和配置路径是否正确。 -- 拦截器的类型需要和[MethodInterceptPoint](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/agent/definition/MethodInterceptPoint.java)的对应方法保持一致,注意别写错。 - -### 插件打包流程 - -- `插件模块(plugin)`的产品输出到整个产品的`agent/pluginPackage/${功能名称}/plugin`目录,直接使用`shade`插件打包,添加如下标签即可: - ```xml - - - - org.apache.maven.plugins - maven-shade-plugin - - - - ``` -- `服务模块(service)`的产品输出到整个产品的`agent/pluginPackage/${功能名称}/service`目录: - - 优先选择使用`shade`插件,添加以下标签: - ```xml - - - - org.apache.maven.plugins - maven-shade-plugin - - - - ``` - - 如果确认`服务模块(service)`不含`byte-buddy`和`slf4j`依赖,也可以: - - 选择使用`assembly`插件打带依赖包。 - - 或者直接使用`jar`插件和`dependency`插件将相关的第三方依赖连同不带依赖的`服务模块(service)`包一同打到`agent/pluginPackage/${功能名称}/service`目录下。 - - 另外,如果存在多个`服务模块(service)`,且他们存在公共依赖(`byte-buddy`和`slf4j`除外),可以选择混用`shade`插件和`dependency`插件,将这些公共依赖排除出`shade`插件的依赖列表,并使用`dependency`插件导出。 - -## 附加件开发流程 - -本节将介绍`后端模块(server)`和`前端模块(webapp)`两种附加件的开发流程,由于这两部分是`功能function`中相对独立的内容,因此没有太多开发上的限制。 - -结合[打包流程](#打包流程)中介绍的步骤,与附加件开发相关的步骤有`agent`和`test`两个`profile`, 附加件一般不添加至`release`。如果需要为`插件主模块(main)`添加`后端模块(server)`或`前端模块(webapp)`子模块: - -- 在`插件主模块(main)`的`pom.xml`文件的以下`profile`中添加`module`: - ```xml - - - agent - - true - - - ${后端模块名(如果有)} - ${前端模块名(如果有)} - ${其他模块名(如果有)} - - - - test - - ${后端模块名(如果有)} - ${前端模块名(如果有)} - ${其他模块名(如果有)} - - - - ``` -- 将`后端模块(server)`子模块和`前端模块(webapp)`子模块的输出调整至`${package.server.output.dir}`,常见打包插件如下: - ```xml - - - org.springframework.boot - spring-boot-maven-plugin - ${spring-boot打包插件版本} - - ${main函数入口} - ${package.server.output.dir} - - - - - repackage - - - - - - - - org.apache.maven.plugins - maven-shade-plugin - ${shade插件版本} - - ${package.server.output.dir} - - - - package - - shade - - - - - - - - org.apache.maven.plugins - maven-assembly-plugin - ${assembly插件版本} - - ${package.server.output.dir} - - jar-with-dependencies - - - - - make-assembly - package - - single - - - - - ``` -- `后端模块(server)`子模块和`前端模块(webapp)`子模块如何开发依实际情况而定,仅有的要求,就是输出到产品的`server/${功能名称}`目录,同时提供启动他们的脚本或辅助性文本,能够帮助使用者快速启动和关闭即可。 - -[返回**Sermant**说明文档](../README-zh.md) diff --git a/docs/dev-guide/dev_plugin_module.md b/docs/dev-guide/dev_plugin_module.md deleted file mode 100644 index 9f59704dd6..0000000000 --- a/docs/dev-guide/dev_plugin_module.md +++ /dev/null @@ -1,470 +0,0 @@ -# Plugin Module Development Guide - -[简体中文](dev_plugin_module-zh.md) | [English](dev_plugin_module.md) - -This document focuses on **Sermant** 's [root module of plugins](../../sermant-plugins) and describes how to add a plugin and its services and add-ons to the `root module of plugins`. - -- [Development Environment](#Development-Environment) -- [Components](#Components) -- [Packaging](#Packaging) -- [Add Main Module of Plugin](#Add-Main-Module-of-Plugin) - - [Plugin Name and Version](#Plugin-Name-and Version) -- [Plugin Development Process](#Plugin Development Process) - - [Before Development](#Before-Development) - - [Add Plugin Module](#Add-Plugin-Module) - - [Add Plugin Service Module](#Add-Plugin-Service-Module) - - [Add Configuration](#Add-Configuration) - - [Example Project](#Example-Project) - - [Attentions](#Attentions) - - [Packaging for Plugin](#Packaging-for-Plugin) -- [Add-on Development Process](#Add-on-Development-Process) - -## Development Environment - -- [HuaweiJDK 1.8](https://gitee.com/openeuler/bishengjdk-8) / [OpenJDK 1.8](https://github.com/openjdk/jdk) / [OracleJDK 1.8](https://www.oracle.com/java/technologies/downloads/) -- [Apache Maven 3](https://maven.apache.org/download.cgi) - -## Components - -The `root module of plugins` of **Sermant** is divided into sub-modules based on plugin functionality known as `main module of plugin`, which could contain the following types of sub-modules: - -- The `plugin` module, which is mainly used to declare enhancements to the host application. -- The `service` module, which provides the service implementation for the plugin package. -- The `server` module, which receives the plugin data. -- The `frontend` module, which is used to display the server-side data. -- The `other` module, special add-on, usually used for debugging. - -## Packaging - -There six steps of packaging in current [Sermant](../../pom.xml), including `agent`, `test`, and `release`. among which the ones related to [sermant-plugins](../../sermant-plugins/pom.xml) are as follows: - -- `agent`: Package all the stable version `plugin module` and `service module`,and export them to the `agent/pluginPackage/${feature name}` directory; package all the stable version add-ons, including `backend module(server)`, `frontend module(webApp)` and `other`. And`backend module (server)` and `frontend module (WebApp)` will be exported to the product's `server/${feature name}` directory. `Other` modules are generally add-ons for debugging purposes and have no packaging requirements. -- `test`: Package all `plugin module`, `service module` and add-ons in Sermant. -- `release` : Package the stable version modules in Sermant which should be published to maven central repository. - -## Add Main Module of Plugin - -- Add the `main` module to the [pom.xml of sermant-plugins](../../sermant-plugins/pom.xml). According to the contents of the `main` module, add this module in specific `profile` of `pom.xml` . - - This module must be added to `profile` whose `id` is `test`. -- Add the following label to the module's `pom.xml`: - ```xml - pom - ``` - ```xml - - ${pom.basedir}/../../.. - ${plugin name} - - ``` - - Add the new `main` module to [default plugin setup file](../../sermant-agentcore/sermant-agentcore-config/config/plugins.yaml) and [all plugin setup file](../../sermant-agentcore/sermant-agentcore-config/config/test/plugins.yaml) to complete registration. - -The sub-module development process of the `main` module of plugin is described in the following chapter: - -- Refer to [Plugin Development Process](#Plugin-Development-Process) for detailed information of `plugin` and `service` development process. -- Refer to [Add-on Development Process](#Add-on-Development-Process) for detailed information of `backend(server)` and `frontend(webapp)` development process. -- The `other` module is only involved in debugging and is not involved in development flow constraints. - -### Plugin Name and Version - -The name and version of the plugin are intrinsic properties of the `plugin` and `service`, so we encapsulate them in the `manifest` file as meta-information for the `jar` package: - -- The **plugin name** is encapsulated in the `Sermant-Name-Version` parameter of the `manifest` file, set by the `package.plugin.name` parameter of the `pom` file, which defaults to the **plugin name** meaning. -- The **plugin version** is encapsulated in the `Sermant-Plugin-Version` parameter of the `manifest` file, which defaults to `project.version` and can be changed via the `package.plugin.version` parameter in the `pom` file. -```xml - - ${plugin name} - ${plugin version} - -``` - -During the loading of the plugin package, the name and version of the `plugin` and `service` modules are checked and an exception is thrown if the following conditions are not met: - -- For all `plugin` modules, since third-party dependencies other than `byte-buddy` and `slf4j`are not allowed, full qualified class name in the `byte-buddy` and `slf4j` packages will be modified through the `shade` plugin. Therefore, when loading the `plugin` directory (the `plugin` directory inside the `main` module directory), an exception will be thrown if a third-party package without the **plugin name** and **plugin version** is checked out. -- For all `plugin` and `service` modules, an exception will be thrown if the **plugin name** does not match the name configured in the **plugin setup file**. -- For all `plugin` and `service` modules, an exception will be thrown if there are multiple different **plugin versions**. - -For plugin developers, it is not recommended to change the default design without special needs. Just keep plugins free of third-party dependencies other than `byte-buddy` and `slf4j`. Keep the principle that plugins contains interfaces, and services contains implementations. - -## Plugin Development Process - -In this section, we will go through the process of developing plugins. The modules involved are `plugin` and `service`. - -### Before Development - -The position of `plugin` is to define the enhanced logic of the host application. Considering the problem of dependency conflicts, the enhanced bytecode cannot involve the use of third-party dependencies other than `byte-buddy` and `slf4j`, which needs to be discussed in two cases: - -- For simple plugins, where the plugin service is written to use only the self-developed functionality of the core package, and does not involve complex functionality that depends on other third-party dependencies, then only the `plugin` module is needed. The `plugin` will be loaded by the system class loader `AppClassLoader`. -- For some complex plugins, if you need to rely on the complex functions of other third parties, you need to design the service interface in the `plugin` module, and write the `service` module to implement it. The `plugin` module is still loaded by the system class loader `AppClassLoader`, while the `service` module is preferentially loaded by the custom class loader [PluginClassLoader](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/classloader/PluginClassLoader.java) to achieve classloader-level dependency isolation. - -As for the third party dependencies in the core module, the full qualified class name of code will be modified by [shade plugin](https://github.com/apache/maven-shade-plugin) as well as self-developed code. It can't be used in `plugin` modules unless you do the same thing when plugins are packaged. - -Also, for the `byte-buddy` package, since the method matcher is not extracted in the **core module**, the plugin still needs to use them, so the `plugin` is required to fix the full qualified class name of the `byte-buddy` package. - -As for the `slf4j` package, due to classloader isolation during the initialization of the **complex plugin service**, the third-party `slf4j` interface used the **core module** configuration but could not be linked to the **core module** implementation, so the full qualified class name of `slf4j` had to be fixed to fit. - -That's why plugin and service packages have to fix the full qualified class name of `byte-buddy` and `slf4j`, and why plugin can use these two dependencies. - -### Add Plugin Module - -Combined with the steps introduced in the [Packaging](# Packaging), there are three `profiles` related to plugin development: `agent`, `test` and `release`. `agent` is used to publish release package in github. `release` is used to publish modules to maven central repository. `test` is used for developing code and testing. If you need to add a `plugin` submodule to the `main` module: - -- Add the `module` to the following `profile` in the `pom.xml` file of the `main` module: - ```xml - - - agent - - true - - - ${plugin module name} - - - - test - - ${plugin module name} - - - - release - - ${plugin module name} - - - - ``` - -- Add the following parameters to the `plugin` submodule: - ```xml - - plugin - - ``` - -- Add the core package dependency to the `plugin` submodule: - ```xml - - - com.huaweicloud.sermant - sermant-agentcore-core - provided - - - ``` - Note that third party dependencies other than `byte-buddy` and `slf4j` cannot be added or used for `plugin`, unless their full qualified class name are corrected using the `shade` plugin (not recommended)! - -- Add the `shade` plugin to the `plugin` submodule to fix the full qualified class name of `byte-buddy` and `slf4j`, for reasons detailed in [Before Development](# Before-Development) : - ```xml - - - - org.apache.maven.plugins - maven-shade-plugin - - - - ``` - -### Add Plugin Service Module - -Similar to the `plugin` module, here's how to add a `service` module: - -- Add the `module` to the following `profile` in the `pom.xml` file of the `main` module: - ```xml - - - agent - - true - - - ${plugin service module name} - - - - test - - ${plugin service module name} - - - - release - - ${plugin service module name} - - - - ``` - -- Add the following parameters to the `service` submodule: - ```xml - - service - - ``` - -- Add the core package and related plugin dependency to the `service` submodule: - ```xml - - - com.huaweicloud.sermant - sermant-agentcore-core - provided - - - com.huaweicloud.sermant - ${plugin module name} - ${plugin module version} - provided - - - ``` - -- Add third-party dependencies to the `service` module - - - Add directly - - The `service` module allows you to add third-party dependencies on demand, directly in `pom.xml` via ` compile`. The third-party dependencies introduced by this method are loaded by the PluginClassloader of each plugin independently. There is a class isolation between the plugin and the host application or between the plugins - - - Add public third-party dependencies indirectly by importing`sermant-common` - - Sermant provides a CommonClassLoader mechanism, and plugins can extract common dependencies into `sermant-common` on demand to share common dependencies between plugins. - - `service` module can import `sermant-common` via `provided`, where third-party dependencies are loaded by the CommonClassLoader and there is no class isolation between plugins. - - If the `service` module imports `sermant-common` and needs to use a different version of the third-party dependency from the one imported in `sermant-common`, it needs to import the specific dependency via`compile` in this module. Third-party dependencies imported by this approach are loaded by the PluginClassLoader of the current plugin, isolated from the CommonClassLoader. - -- Add the `shade` plugin to the `service` submodule: - - ```xml - - - - org.apache.maven.plugins - maven-shade-plugin - - - - ``` - It is not recommended to use other package plugins. Refer to [Before Development](# Before-Development) for details. - -### Add Configuration - -If plugin configuration `PluginConfig` is needed in the `plugin` and `service` module, you need to add the plugin configuration file: - -- Add a `config` folder to the home directory of `main` module. -- Add a `config.yaml` file in the `config` folder. This is the configuration file of the plugin. -- Add the following configuration to any submodule of `main` module (usually the first submodule) to execute the resource copy: - ```xml - - false - - ``` - If the submodule configured with the above parameters is not in the `main` module directory of the plugin, you also need to set the following parameters based on the relative path of the module to the `config` directory: - ```xml - - ../config - - ``` - -### Example Project - -The [Sermant-examples](https://github.com/huaweicloud/Sermant-examples) is a demo project. The `sermant-template` module is a sample module that covers most of the scenarios you might encounter when developing a plugin. This section explains the contents of this module to help you get started with developing plugin features as soon as possible. - -- The example for enhancement definition, which can be found in [Declarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer): - - [DemoAnnotationDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoAnnotationDeclarer.java) shows how to locate the enhanced class by annotations that decorates the class. - - [DemoNameDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoNameDeclarer.java) shows how to locate enhanced classes by name. - - [DemoSuperTypeDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/declarer/DemoSuperTypeDeclarer.java) shows how to locate enhanced classes via superclasses. - - In all three above, you can see how to declare interceptors to enhance constructors, static functions, and instance functions. - - Remember to add the [spi file](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/resources/META-INF/services/com.huaweicloud.sermant.core.plugin.agent.declarer.PluginDeclarer) for [EnhanceDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/PluginDeclarer.java). - -- The example for interceptors, which can be found in [interceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor): - - [DemoConstInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoConstInterceptor.java) shows how to write an interceptor to enhance a constructor. - - [DemoStaticInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoStaticInterceptor.java) shows how to write an interceptor to enhance a static function. - - [DemoMemberInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoMemberInterceptor.java) shows how to write an interceptor to enhance an instance function. - -- The example for log system. [DemoLogger](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/common/DemoLogger.java) shows how to get the log class in the plugin. - -- The example for adding additional parameters via the heartbeat function, as shown by the [DemoHeartBeatService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoHeartBeatService.java) service, which is typically a custom service to bring in additional parameters. - -- The example for trace tracking usage. As [DemoTraceNormalInterceptor](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/interceptor/DemoTraceNormalInterceptor.java) shows, the trace tracking function is applied to the interceptor, which enhances the method invocation process of the host application, captures its relevant data information and reports it. - -- The example for enhancing native class. As [DemoBootstrapDeclarer](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/Java/com/huawei/example/demo/declarer/DemoBootstrapDeclarer.java) shows, it is the same as the general way of enhancement. However, considering that modifying native classes is a very dangerous and risk-spreading operation, it is not recommended to enhance native classes. - -- The example for plugin configuration : plugin configuration is a specialization of the unified configuration system and follows the rules of the unified configuration system. [config.yaml](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/config/config.yaml) is the configuration file of this sample project , which contains the information of [DemoConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/config/DemoConfig.java) and [DemoServiceConfig](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service/src/main/java/com/huawei/example/demo/config/DemoServiceConfig.java). As you can see from the definition and invoke of the configuration: - - There can only be one configuration file per feature, (the `config.yaml` file). - - - The package configuration class needs to implement [PluginConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config/PluginConfig.java) interface whether or not it has an alias for interceptor. - - - It is necessary to add the [spi file](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/resources/META-INF/services/com.huaweicloud.sermant.core.plugin.config.PluginConfig) for [PluginConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config/PluginConfig.java). - - - The property type of configuration classes can be boolean, number, string, enum, complex object, as well as their array, list, and dictionary type. - - - Plain strings and string fields of complex objects support `${key:default}` style mappings with the following precedence: - ``` - javaagent startup parameters > Other properties in this class > environment variables > system variables> default value - ``` - However, strings wrapped in array, list, and dictionary type will not execute this mapping. - - - It is supported to use of [ConfigTypeKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigTypeKey.java) annotations to modify full qualified class name in configuration classes , but make sure that all full qualified class name of unified configuration classes (whether modified or not) are not repeatable. - - - It is supported to use of [ConfigFieldKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigFieldKey.java) to modify the name of field for configuration class and its complex object. However, properties of complex objects wrapped in array, list, and dictionary type do not support modification. - - - The object of configuration class can be retrieved with the following code: - ```java - PluginConfigManager.getPluginConfig(PluginConfigType.class) - ``` - -- The example for plugin service. Plugin services are specializations of the core service system that follow the rules of the core service system. - - As [DemoSimpleService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoSimpleService.java) shows, it is a simple plugin service written in the `plugin` module. Because of the positioning of a simple plugin service, it can only use the native Java API and the self-developed API in the core package, and cannot use any third-party API (whether the core package is imported or not). - - [DemoComplexService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoComplexService.java) is the complex service interface defined in the example `plugin` module, which will be implemented in the `service` module. - - [DemoComplexServiceImpl](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-service/src/main/java/com/huawei/example/demo/service/DemoComplexServiceImpl.java) is the implementation of [DemoComplexService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoComplexService.java). It's written in a `service` module, which is a complex plugin service that can use other third-party dependencies (not used in the example). - - Both simple plugin services and complex plugin service interfaces need to inherit (implement) [PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java). - - It is necessary to add the [spi file](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/resources/META-INF/services/com.huaweicloud.sermant.core.plugin.service.PluginService) for [PluginService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service/PluginService.java) - - The object of service can be retrieved with the following code: - ```java - ServiceManager.getService(ServiceType.class) - ``` - -For more details on developing plugins, refer to the [Plugin Code Development Guide](dev_plugin_code-zh.md). - -### Attentions - -In this section, we'll list some of the most error-prone areas of plugin development: - -`plugin` cannot rely on or use third-party dependencies other than `byte-buddy` and `slf4j `. If the service functionality is complex and must use other third-party dependencies, they can be extracted as `service` or isolated with `shade` plugin (not recommended). - -- If there are multiple `service` modules in the same `main` module, they cannot have dependency conflicts. -- There can be only one configuration file for plugins: `config.yaml`. -- In `config.yaml`, complex objects wrapped in arrays, lists, and dictionaries will not support [ConfigFieldKey](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/ConfigFieldKey.java) to modify names. Wrapped strings also do not support the `${XXX}` mapping. -- The full qualified class name of the corresponding configuration class in the configuration file cannot be repeated. This rule is valid for all unified configurations globally. -- If the `plugin` and `service` modules are not defined in the `main` module directory of the plugin, you need to pay attention to the output jar package and the configuration path is correct. -- The interceptor type needs to be the same as [MethodInterceptPoint](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/agent/definition/MethodInterceptPoint.java). Be careful not to make mistakes. - -### Packaging for Plugin - -- The output of the `plugin` product is exported to the `agent /pluginPackage/${feature name}/plugin` directory of the entire product, which is packaged directly with the `shade` plugin by adding the following label: - ```xml - - - - org.apache.maven.plugins - maven-shade-plugin - - - - ``` - -- The `service` product outputs to the `agent/pluginPackage/${feature name}/service` directory of the entire product: - - Using the `shade` plugin in preference, add the following tags: - ```xml - - - - org.apache.maven.plugins - maven-shade-plugin - - - - ``` - - - If you make sure the `service` module doesn't have `byte-buddy` and `slf4j` dependencies, you can also: - - Choose the `Assembly` plugin to pack age dependencies. - - Or use the `jar` plugin and `dependency` plugin to add the relevant third-party dependencies to the `agent/pluginPackage/${feature name}/service` directory, along with the `service` package without dependencies. - - In addition, if there are multiple `service` modules, and they have common dependencies (except `byte-buddy ` and `slf4j`), you can choose to mix `shade` and `dependency` plugins to exclude these common dependencies from the dependency list of `shade` plugin. And export it using the `dependency` plugin. - -## Add-on Development Process - -This section will describe the development process of two add-ons: `backend module (server)` and `frontend module (webapp)`. Since these two parts are relatively independent parts of the `function`, there are not many development restrictions. - -Combined with the steps covered in the [Packaging](# Packaging), there are two `profiles` related to add-on development: `agent` and `test`. It's not recommended adding add-ons to `release`. If you need to add a `backend module (server)` or `frontend module (webapp)` submodule to the `main` plugin module: - -- Add the `module` to the following `profile` in the `pom.xml` file of the `main` plugin module: - ```xml - - - agent - - true - - - ${backend module name(if exists)} - ${frontend module name(if exists)} - ${other module name(if exists)} - - - - test - - ${backend module name(if exists)} - ${frontend module name(if exists)} - ${other module name(if exists)} - - - - ``` -- Export ` backend module (server) ` and ` frontend module (webapp) ` to `${package.server.output.dir} `. Common package plugin as follows: - ```xml - - - org.springframework.boot - spring-boot-maven-plugin - ${version of spring-boot package plugin} - - ${main class} - ${package.server.output.dir} - - - - - repackage - - - - - - - - org.apache.maven.plugins - maven-shade-plugin - ${version of shade plugin} - - ${package.server.output.dir} - - - - package - - shade - - - - - - - - org.apache.maven.plugins - maven-assembly-plugin - ${version of assembly plugin} - - ${package.server.output.dir} - - jar-with-dependencies - - - - - make-assembly - package - - single - - - - - ``` -- How the `backend module (server)` submodule and the `frontend module (webapp)` submodule are developed depends on the actual situation. The only requirement is to export them to the `server/${function name}` directory of the product, and provide scripts or auxiliary text to start them, which can help users start and close quickly. - -[Back to README of **Sermant**](../README-zh.md) diff --git a/docs/dev-guide/service_dynamicconfig-zh.md b/docs/dev-guide/service_dynamicconfig-zh.md deleted file mode 100644 index d14939c58f..0000000000 --- a/docs/dev-guide/service_dynamicconfig-zh.md +++ /dev/null @@ -1,172 +0,0 @@ -# 动态配置服务介绍 - -[简体中文](service_dynamicconfig-zh.md) | [English](service_dynamicconfig.md) - -本文档主要介绍**核心模块**的[动态配置服务](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig)。 - -- [功能定位](#功能定位) -- [Api解析](#Api解析) -- [ZooKeeper实现](#ZooKeeper实现) -- [Kie实现](#Kie实现) -- [实现包装](#实现包装) -- [使用方式](#使用方式) - -## 功能定位 - -**动态配置服务**是一个允许使用者动态从服务器拉取配置的服务,它作为[统一配置系统](../user-guide/agentcore-zh.md#统一配置系统)的动态补充,其核心述求在于解决后者提供的配置不可改变的问题。 - -## Api解析 - -**动态配置服务**的服务功能`API`由[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)抽象类提供,其实现三个接口,见于[api](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api)目录中,具体接口如下所示: - -|接口|方法|解析| -|:-|:-|:-| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|String getConfig(String)|获取某个键的配置值(默认组)| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|boolean publishConfig(String, String)|设置某个键的配置值(默认组)| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|boolean removeConfig(String)|移除某个键的配置值(默认组)| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|List\ listKeys()|获取所有键(默认组)| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|boolean addConfigListener(String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java))|为某个键添加监听器(默认组)| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|boolean removeConfigListener(String)|移除某个键的监听器(默认组)| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|String getConfig(String, String)|获取组下某个键的配置值| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|boolean publishConfig(String, String, String)|设置组下某个键的配置值| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|boolean removeConfig(String, String)|移除组下某个键的配置值| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|boolean addConfigListener(String, String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java))|为组下某个键添加监听器| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|boolean removeConfigListener(String, String)|移除组下某个键的监听器| -|[GroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/GroupService.java)|List\ listKeysFromGroup(String)|获取组中所有键| -|[GroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/GroupService.java)|boolean addGroupListener(String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java))|为组下所有的键添加监听器| -|[GroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/GroupService.java)|boolean removeGroupListener(String)|移除组下所有键的监听器| -|[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)|boolean addConfigListener(String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java), boolean)|为某个键添加监听器(默认组),根据入参决定是否触发初始化事件| -|[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)|boolean addConfigListener(String, String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java), boolean)|为组下某个键添加监听器,根据入参决定是否触发初始化事件| -|[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)|boolean addGroupListener(String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java), boolean)|为组下所有的键添加监听器,根据入参决定是否触发初始化事件| - -以上,需要明确两个概念: - -- `Key`,单指某个动态配置的键 -- `Group`,指一系列动态配置的分组,通常用于区分使用者 - -通过观察可以发现,以上的`API`主要分为数据的增删查改操作,以及监听器的[DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java)增删操作,其中后者的事件回调是**动态配置服务**得以实现功能中至关重要的一环,也是插件中使用**动态配置服务**的主要功能。 - -另外,在[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)接口中定义的所有`API`都是不带`Group`的`API`,它们在[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)中其实都会使用默认`Group`修正为[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)的`API`,这点需要注意。默认`Group`可以通过**统一配置文件**`config.properties`的`dynamic.config.default_group`修改。 - -最后,除了以上的服务接口以外,使用者还需要关注一些其他接口、配置或实体: - -- **动态配置服务**的静态配置[DynamicConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/config/DynamicConfig.java),其中涉及以下配置: - |类型|属性|统一配置值|解析| - |:-|:-|:-|:-| - |int|timeoutValue|dynamic.config.timeout_value|服务器连接超时时间,单位:ms| - |String|defaultGroup|dynamic.config.default_group|默认分组| - |String|serverAddress|dynamic.config.server_address|服务器地址,必须形如:{@code host:port[(,host:port)...]}| - |[DynamicConfigServiceType](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigServiceType.java)|serviceType|dynamic.config.dynamic_config_type|服务实现类型,取NOP、ZOOKEEPER、KIE| -- **动态配置服务**实现类型[DynamicConfigServiceType](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigServiceType.java),含一下几种类型: - |枚举值|解析| - |:-|:-| - |ZOOKEEPER|ZooKeeper实现| - |KIE|ServiceComb Kie实现| - |NOP|无实现| -- 动态配置监听器[DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java),其中包含的接口方法如下: - |方法|解析| - |:-|:-| - |void process([DynamicConfigEvent](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigEvent.java))|处理配置改变事件的回调接口| -- 动态配置改变事件[DynamicConfigEvent](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigEvent.java),其成员属性如下: - |类型|属性|解析| - |:-|:-|:-| - |String|key|配置键| - |String|group|配置分组| - |String|content|配置信息| - |[DynamicConfigEventType](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigEventType.java)|changeType|事件类型| -- 动态配置改变事件类型[DynamicConfigEventType](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigEventType.java),含以下四种: - |枚举值|解析| - |:-|:-| - |INIT|添加监听器时的初始化响应| - |CREATE|配置新增事件| - |MODIFY|配置信息修改事件| - |DELETE|配置删除事件| - -## ZooKeeper实现 - -对于`ZooKeeper`服务器来说,所谓的动态配置就是`ZooKeeper`节点的值,至于`Key`和`Group`应当作为构建**节点路径**的元素。考虑到`Group`包含区别使用者的信息,应当作为**节点路径**的前缀,这样`Key`值则作为后半部分存在: -```txt -/${group}/${key} -> ${value} -``` - -至于监听器[DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java),则需要转换为`ZooKeeper`的`Watcher`。 - -`ZooKeeper`实现见于[zookeeper](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper)包,主要包含[ZooKeeperDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperDynamicConfigService.java)和[ZooKeeperBufferedClient](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperBufferedClient.java)两个类: - -- [ZooKeeperDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperDynamicConfigService.java)是[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)的`ZooKeeper`实现类,主要职责是完成下面的参数转换: - - - `Key`和`Group` -> `ZooKeeper`节点路径 - - [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java) -> `ZooKeeper`的`Watcher`。 - - 将他们解析完毕之后,交由[ZooKeeperBufferedClient](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperBufferedClient.java)做业务操作。 -- [ZooKeeperBufferedClient](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperBufferedClient.java),其主要功能是对原生`ZooKeeper`客户端进行包装,封装其原生的功能,提供更为高阶的`API`: - |方法|解析| - |:-|:-| - |boolean ifNodeExist(String)|判断节点是否存在| - |String getNode(String)|查询节点内容| - |boolean createParent(String)|创建节点的前置节点| - |boolean updateNode(String, String)|更新节点内容,不存在时自动创建| - |boolean removeNode(String)|移除节点| - |List\ listAllNodes(String)|查询节点下所有子孙节点的路径集合| - |boolean addDataLoopWatch(String, Watcher, BreakHandler)|添加循环的临时数据监听器,该监听器将在触发后重新注册,直到接收到移除监听器事件

注意,当同一节点的其他监听器被精准移除时,由于该监听器无法鉴别到底是不是移除自身,因此会选择放弃循环注册| - |boolean addPersistentRecursiveWatches(String, Watcher)|添加持久递归的监听器,对子孙节点有效| - |boolean removeDataWatches(String)|移除数据监听器| - |boolean removeAllWatches(String)|移除节点下所有的监听器,含子孙节点| - |void close()|关闭`ZooKeeper`客户端| - -## Kie实现 - -对于`Kie`服务来说,所谓动态配置就是`Kie`配置的键值,`Kie`是基于标签去查询关联配置, 至于`Key`与`Group`则是关联配置的元素。`Key`即配置的键的名称,而`Group`则是关联`Key`的标签, 每一个`Key`都可配置一个或者多个标签,其格式往往如下: - -```properties -{ - "key": "keyName", # 配置键 - "value": "value", # 配置值 - "labels": { - "service": "serviceName" #标签,kv形式,支持一个或者多个 - }, - "status": "enabled" -} -``` - -相对于`Zookeeper`, `Kie`更专注于`Group`, 其传值格式也有所不同,`Kie`的传值格式如下: - -```properties -groupKey1=groupValue1[&groupKey2=groupVaue2...] -``` - -> 其中`groupKey`为标签键, `groupValue`则为标签值,多个标签使用`&`拼接;`Group`可通过[LabelGroupUtils#createLabelGroup](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/utils/LabelGroupUtils.java)生成 -> -> **特别说明:** -> -> ​ 若传入的`Group`非以上格式,则会默认添加标签`GROUP=传入Group` - -`Kie`的实现见于包[kie](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie), 主要包含[KieDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/KieDynamicConfigService.java)、[LabelGroupUtils](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/utils/LabelGroupUtils.java)与[SubscriberManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/listener/SubscriberManager.java)三个类: - -- [KieDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/KieDynamicConfigService.java)是[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)的`Kie`实现类, 主要职责是封装[SubscriberManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/listener/SubscriberManager.java)的订阅API以及`Group`的`Key`管理 - -- [LabelGroupUtils](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/utils/LabelGroupUtils.java)则是负责`Group`转换,主要包含以下API: - - | 方法 | 解析 | - | --------------------------- | -------------------------------- | - | createLabelGroup(Map) | 创建标签,多个标签使用KV形式传入 | - | getLabelCondition(String) | 将Group转换为请求的条件 | - | isLabelGroup(String) | 判断是否为Kie的标签 | - -- [SubscriberManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/listener/SubscriberManager.java)主要职责是管理`Group`的所有订阅者以及进行数据更新通知;其会根据订阅的Group,即标签组,与`Kie`建立连接请求任务,动态监听数据更新变化;该类主要包含以下API: - - | 方法 | 解析 | - | ------------------------------------------------------------ | ------------------------------------------------------------ | - | boolean addGroupListener(String, DynamicConfigListener, boolean) | 订阅标签监听,由[SubscriberManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/listener/SubscriberManager.java)管理,建立监听任务,并提供首次订阅通知能力 | - | boolean removeGroupListener(String, DynamicConfigListener) | 移除标签监听 | - | boolean publishConfig(String, String, String) | 发布Kie配置 | - -## 实现包装 - -从[核心模块介绍](../user-guide/agentcore-zh.md#插件服务系统)可知,**插件服务系统**是基于`SPI`实现的,而[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)对应的`SPI`实现配置为[BufferedDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/BufferedDynamicConfigService.java),后者为前者所有具体实现类的包装。它在初始化的过程中读取[DynamicConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/config/DynamicConfig.java)配置,通过`dynamic.config.dynamic_config_type`配置选择具体的服务实现,并将所有`API`委派给这些具体的服务实现完成。 - -## 使用方式 - -**动态配置服务**主要应用于插件的拦截器或插件服务中,具体使用方式可以参见[插件代码开发手册的动态配置功能一节](dev_plugin_code.md#动态配置功能),使用过程中较为关键的当属`Key`和`Group`的构建,具体内容可参见前文中几种实现中对这两个值的要求,这里不做赘述。 - -[返回**Sermant**说明文档](../README-zh.md) diff --git a/docs/dev-guide/service_dynamicconfig.md b/docs/dev-guide/service_dynamicconfig.md deleted file mode 100644 index f41801036a..0000000000 --- a/docs/dev-guide/service_dynamicconfig.md +++ /dev/null @@ -1,183 +0,0 @@ -# Dynamic Configuration Service - -[简体中文](service_dynamicconfig-zh.md) | [English](service_dynamicconfig.md) - -This document is about the [Dynamic Configuration Service](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig) in **sermant-agentcore**. - -- [Function Orientation](#Function-Orientation) -- [API](#API) -- [Implementation for ZooKeeper](#Implementation-for-ZooKeeper) -- [Implementation for Kie](#Implementation-for-Kie) -- [Wrapper](#Wrapper) -- [How to Use](#How-to-Use) - -## Function Orientation - -**Dynamic Configuration Service** is a service that allows developers to dynamically pull configuration from servers, acting as a [Unified Configuration System](../user-guide/agentcore.md#Unified-Configuration-System). Its core purpose is to solve the problem that the configuration provided by the latter can not be changed. - -## API - -The functionality `API` of **Dynamic Configuration Service** is provided by the abstract class [DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java) , which implements three interfaces, as seen in [api](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api) directory, The concrete interface is as follows:: - -|Interface|Method|Explanation| -|:-|:-|:-| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|String getConfig(String)|Get the configured value for a key (default group).| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|boolean publishConfig(String, String)|Set value for a key (default group) .| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|boolean removeConfig(String)|Remove a configured value for a key (default group).| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|List\ listKeys()|Get all keys (default group).| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|boolean addConfigListener(String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java))|Add a listener for a key (default group).| -|[KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java)|boolean removeConfigListener(String)|Remove a listener for a key (default group).| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|String getConfig(String, String)|Get the configured value for a key in the group.| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|boolean publishConfig(String, String, String)|Set value for a key in the group.| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|boolean removeConfig(String, String)|Remove the configured value for a key in the group.| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|boolean addConfigListener(String, String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java))|Add a listener for a key in the group.| -|[KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java)|boolean removeConfigListener(String, String)|Remove a listener for a key in the group.| -|[GroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/GroupService.java)|List\ listKeysFromGroup(String)|Get all keys in the group.| -|[GroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/GroupService.java)|boolean addGroupListener(String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java))|Add listeners for all keys in the group.| -|[GroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/GroupService.java)|boolean removeGroupListener(String)|Remove listeners for all keys in the group.| -|[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)|boolean addConfigListener(String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java), boolean)|Add a listener for a key(default group). Whether to trigger the initialization event depends on the input parameters| -|[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)|boolean addConfigListener(String, String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java), boolean)|Add a listener for a key in the group. Whether to trigger the initialization event depends on the input parameters.| -|[DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java)|boolean addGroupListener(String, [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java), boolean)|Add listeners for all keys in the group. Whether to trigger the initialization event depends on the input parameters.| - -Above all, two concepts need to be clear: - -- `Key`, a single reference to a dynamical configuration key -- `Group`, a dynamical configuration set of groups, often used to distinguish between users - -As you can see, the above `API` is mainly divided into data adding, deleting, querying and modifying operations, and add/remove operations of the listener's [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java). The latter event callback is a crucial part of the functionality of the **Dynamic Configuration Service**, which is the main feature of the plugin using **Dynamic Configuration Service**. - -Also, in the [KeyService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyService.java) interface, all the `API` defined are `API` without `Group`. They will actually use the default `Group` and be fixed to `API` of [KeyGroupService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/api/KeyGroupService.java) in [DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java). The default `Group` can be modified via `dynamic.config.default_group` in the **unified configuration file** `config.properties`. - -Finally, besides the above service interfaces, there are a few other interfaces, configurations, or entities that developers need to pay attention to: - -- Static configuration [DynamicConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/config/DynamicConfig.java) for **Dynamic Configuration Service**, which involves the following configuration: - |Type|Property|Key in Unified Configuration File|Explanation| - |:-|:-|:-|:-| - |int|timeoutValue|dynamic.config.timeout_value|Timeout for server connection, unit: ms| - |String|defaultGroup|dynamic.config.default_group|Default group| - |String|serverAddress|dynamic.config.server_address|Server address, must be of the form: {@code host:port[(,host:port)...]}| - |[DynamicConfigServiceType](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigServiceType.java)|serviceType|dynamic.config.dynamic_config_type|Service implementation type, take NOP, ZOOKEEPER, KIE| - -- **Dynamic configuration service implementation type**[DynamicConfigServiceType](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigServiceType.java), contains: - - |Enum|Explanation| - |:-|:-| - |ZOOKEEPER|ZooKeeper| - |KIE|ServiceComb Kie| - |NOP|No implementation| - -- **Dynamic configuration listener** [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java), which contains the following interface methods: - - |Method|Explanation| - |:-|:-| - |void process([DynamicConfigEvent](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigEvent.java))|Callback interface for handling change events of configuration| - -- **Change events of dynamic configuration** [DynamicConfigEvent](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigEvent.java), whose member properties are as follows: - - |Type|Property|Explanation| - |:-|:-|:-| - |String|key|Key of configuration| - |String|group|Group of configuration| - |String|content|Content of configuration| - |[DynamicConfigEventType](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigEventType.java)|changeType|Type of configuration change event| - -- **Type of change events of dynamic configuration** [DynamicConfigEventType](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigEventType.java), which contains following four kinds: - - |Enum|Explanation| - |:-|:-| - |INIT|Initial response when adding a listener| - |CREATE|Event of adding new configuration| - |MODIFY|Event of modifying configuration| - |DELETE|Event of deleting configuration| - -## Implementation for ZooKeeper - -For `ZooKeeper` servers, the dynamic configuration is the value of the ZooKeeper node. The `Key` and `Group` should be used as elements to build the **node path**. Since `Group` contains user-specific information, it should be the prefix string for the **node path** so that the `Key` value exists as the second half: -```txt -/${group}/${key} -> ${value} -``` - -As for [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java), we convert it to a `Watcher` of `ZooKeeper`. - -The implementation of `Zookeeper` could be found in [zookeeper](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper). It mainly contains [ZooKeeperDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperDynamicConfigService.java) and [ZooKeeperBufferedClient](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperBufferedClient.java). - -- [ZooKeeperDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperDynamicConfigService.java) is an implementation of [DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java) for `ZooKeeper`, whose main duty is to complete the following parameter conversions: - - - `Key` and `Group` -> `ZooKeeper` node path - - [DynamicConfigListener](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/common/DynamicConfigListener.java) -> `Watcher` of `ZooKeeper`。 - - After they are parsed, [ZooKeeperBufferedClient](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperBufferedClient.java) will do the business operation. -- [ZooKeeperBufferedClient](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/zookeeper/ZooKeeperBufferedClient.java), its main function is to wrap the native `ZooKeeper` client to provide higher-level `API`: - - |Method|Explanation| - |:-|:-| - |boolean ifNodeExist(String)|Check whether the node exists.| - |String getNode(String)|Query node information.| - |boolean createParent(String)|Create the parent node of a node.| - |boolean updateNode(String, String)|Update the content of a node. If the node does not exist, it will be automatically created.| - |boolean removeNode(String)|Remove a node| - |List\ listAllNodes(String)|Query the path set of all descendant nodes under a node| - |boolean addDataLoopWatch(String, Watcher, BreakHandler)|Add a temporary data watcher for a loop. This watcher will be re-registered after triggering until it receives a watcher remove event

Note that when other watchers on the same node are accurately removed, the watcher will choose to abandon the loop registration because it cannot identify whether it has been removed.| - |boolean addPersistentRecursiveWatches(String, Watcher)|Add a watches for persistent recursion, valid for descendant nodes| - |boolean removeDataWatches(String)|Remove data watchers| - |boolean removeAllWatches(String)|Remove all watchers under a node, including descendant nodes| - |void close()|Close `ZooKeeper` client| - -## Implementation for Kie - -For the `Kie` service, the so-called dynamic configuration is the value of the `Kie'` configuration. `Kie` queries the associated configuration based on the label. `Key` and `Group` are the elements of the associated configuration. `Key` is the name of the configured Key, and `Group` is the label of the associated Key. Each `Key` can be configured with one or more labels. The format is usually as follows: - -```properties -{ - "key": "keyName", # key - "value": "value", # value - "labels": { - "service": "serviceName" #label,support one or more - }, - "status": "enabled" -} -``` - -Compared with `Zookeeper`, `Kie` is more focused on `Group` and its value transfer format is different. The value transfer format of `Kie` is as follows: - -```properties -groupKey1=groupValue1[&groupKey2=groupValue2...] -``` - -> `groupKey` is the key of label, `groupValue` is the value of label. Multiple labels are spliced by `&`. `Group` could be generated by [LabelGroupUtils#createLabelGroup](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/utils/LabelGroupUtils.java). -> -> **NOTE:** -> -> ​ If the input `Group` is not in the above format, the label `Group=input Group` will be added by default. - -The implementation of `Kie` could be found in [kie](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie), which contains [KieDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/KieDynamicConfigService.java), [LabelGroupUtils](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/utils/LabelGroupUtils.java) and [SubscriberManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/listener/SubscriberManager.java): - -- [KieDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/KieDynamicConfigService.java) is an implementation of [DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java) for `Kie`. Its main duty is to wrap the subscription API of [SubscriberManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/listener/SubscriberManager.java) and the `Key` management of `Group`. - -- [LabelGroupUtils](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/utils/LabelGroupUtils.java) is used for conversion of `Group`, which contains following APIs: - - | Method | Explanation | - | --------------------------- | --------------------------------------------------- | - | createLabelGroup(Map) | Create labels and transfer multiple labels in KV | - | getLabelCondition(String) | Converts the `Group` to the condition for a request | - | isLabelGroup(String) | Check whether it is a label of `Kie` | - -- The main responsibility of [SubscriberManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/listener/SubscriberManager.java) is to manage all the `Group` subscribers and to provide data update notifications. It will establish a connection request task with `Kie` according to the subscribed Group, namely the Label Group, and dynamically monitor data update changes. This class contains the following APIs: - - | Method | Explanation | - | ------------------------------------------------------------ | ------------------------------------------------------------ | - | boolean addGroupListener(String, DynamicConfigListener, boolean) | And a listener for a label group , which is managed by [SubscriberManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/kie/listener/SubscriberManager.java). Listening task will be established and the ability to notify the first subscription is provided. | - | boolean removeGroupListener(String, DynamicConfigListener) | Remove a label group listener. | - | boolean publishConfig(String, String, String) | Publish configuration of Kie | - -## Wrapper - -You can learn from [Sermant-agentcore-core](../user-guide/agentcore.md#Plugin-Service-System) that **Plugin Service System** is based on `SPI`. - -The corresponding ` SPI ` implementation of [DynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/DynamicConfigService.java) is [BufferedDynamicConfigService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/BufferedDynamicConfigService.java). The latter is the wrapper of all the methods of the former. It reads [DynamicConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/dynamicconfig/config/DynamicConfig.java) configuration at startup, selects concrete service implementation and delegates all `API` to these concrete service implementations via `dynamic.config. dynamic_config_type`. - -## How to Use - -**Dynamic Configuration Service** is mainly used in plugin interceptors or plugin services. The specific way can be found [Plugin Code Development Guide](dev_plugin_code.md). The important thing is the construction of `Key` and `Group`. For details, see the requirements for these two values in the previous implementations. - -[Back to README of **Sermant** ](../README.md) diff --git a/docs/dev-guide/service_heartbeat-zh.md b/docs/dev-guide/service_heartbeat-zh.md deleted file mode 100644 index 0ecfd1b22a..0000000000 --- a/docs/dev-guide/service_heartbeat-zh.md +++ /dev/null @@ -1,85 +0,0 @@ -# 心跳服务介绍 - -[简体中文](service_heartbeat-zh.md) | [English](service_heartbeat.md) - -本文档主要介绍**核心模块**的[心跳服务](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/heartbeat)。 - -## 功能定位 - -**心跳服务**指的是**核心模块**定期向**后端模块**发送心跳包的服务,起到告知当前`Sermant`应用存活的作用。**心跳服务**主要针对所有插件,对每个`插件主模块(main)`,**心跳服务**都会为其定制一个心跳数据包并定期发送,这些定制化数据将在**后端模块**的后续流程中发挥作用。 - -## 实现方式 - -**心跳服务**以**核心服务系统**为基础开发的一套用于`告知存活`和`定制数据`的服务。 - -**核心服务系统**相关内容详见[核心模块介绍](../user-guide/agentcore-zh.md#核心服务系统),这里不做赘述。 - -心跳系统的常见使用方式如下: -```java -// 创建netty客户端 -NettyClient nettyClient = ClientManager.getNettyClientFactory().getNettyClient( - AgentConfigManager.getNettyServerIp(), - Integer.parseInt(AgentConfigManager.getNettyServerPort())); -// 创建心跳数据包,其中包含一些默认数据,下面会介绍 -HeartbeatMessage message = new HeartbeatMessage(); -// 定制心跳数据包中的其他数据 -message.registerInformation("${key}", "${value}"); -// 构建心跳数据包信息 -String msg = message.generateCurrentMessage(); -// 序列化心跳数据包,并通过netty客户端发送,数据类型标注为心跳 -nettyClient.sendData(msg.getBytes(Charset.forName("UTF-8")), Message.ServiceData.DataType.SERVICE_HEARTBEAT); -``` - -其中`HeartbeatMessage`中默认包含的数据如下: - -- `hostname`:发送客户端的主机名 -- `ip`:发送客户端的IP地址 -- `app`:应用名称,即启动参数中的`appName` -- `appType`:应用类型,即启动参数中的`appType` -- `heartbeatVersion`:上一次心跳发送时间 -- `lastHeartbeat`:上一次心跳发送时间 -- `version`:核心包的版本 - -### 初始化插件心跳 - -**心跳服务**在初始化的时候,将从**插件管理器**中获取插件的名称和版本号: -```java -// 键为插件名称,值为插件版本 -Map pluginVersionMap = PluginManager.getPluginVersionMap(); -``` - -每隔一段时间,就会对每个`插件主模块(main)`构建一个心跳数据包并使用心跳系统发送,间隔时间配置于核心配置文件`config.properties`中: -```properties -# 单位:ms -heartbeat.interval=3000 -``` - -发送的心跳数据包中,除了上述心跳系统固定发送的信息外,将额外增加两个参数: - -- `pluginName`:插件名称 -- `pluginVersion`:插件版本号 - -### 添加定制数据 - -**心跳服务**允许插件开发者定制化地为插件的心跳数据包添加额外动态参数: -```java -final HeartbeatService service = ServiceManager.getService(HeartbeatService.class); -service.setExtInfo(new ExtInfoProvider() { - @Override - public Map getExtInfo() { - // do something - } -}); -``` - -`setExtInfo`方法在执行的时候,将通过自定义`ExtInfoProvider`实现找到所在的插件或插件服务`jar`包,获取其`manifest`文件`Sermant-Plugin-Name`的值,即插件名称。获取到插件名称之后,**心跳服务**才能正确地将动态参数绑定到相应的心跳数据包中。 - -`ExtInfoProvider`接口定义了`getExtInfo`方法,**心跳服务**每次构建心跳数据包时,将通过该方法获取动态获取额外参数。 - -## 使用方式 - -一般情况下,对于插件开发者来说,**心跳服务**是无需关心的内容。只有当插件`后端模块(backend)`需要从**后端模块**的kafka心跳主题中捞特定数据时,才有必要为心跳数据包定制数据。插件为其心跳数据包定制数据时,通常可以[自定义插件服务](dev_plugin_code-zh.md#插件服务),在`start`方法中[添加定制数据](#添加定制数据)即可。 - -可以参考示例工程的[DemoHeartBeatService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoHeartBeatService.java)进行开发。 - -[返回**Sermant**说明文档](../README-zh.md) \ No newline at end of file diff --git a/docs/dev-guide/service_heartbeat.md b/docs/dev-guide/service_heartbeat.md deleted file mode 100644 index c57d99279f..0000000000 --- a/docs/dev-guide/service_heartbeat.md +++ /dev/null @@ -1,86 +0,0 @@ -# Heartbeat Service - -[简体中文](service_heartbeat-zh.md) | [English](service_heartbeat.md) - -This document focuses on [Heartbeat Service](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/heartbeat) of the **sermant-agentcore-core**. - -## Function Orientation - -The **Heartbeat Service** is a service that periodically sends heartbeat messages from **sermant-agentcore-core** to the **Backend Module** to inform the current `Sermant` that the application is alive. The **Heartbeat Service** mainly targets all plugins. For each `main` of plugin, **Heartbeat Service** will customize a heartbeat message for it and send it regularly. These customized data will be used in the subsequent flow of the **Backend Module**. - -## Implementation - -**Heartbeat Service** is built based on the **sermant-agentcore-core** for `informing survival` and `customizing data`. - -Details of **Sermant-agentcore-core** could be found [introduction to sermant-agentcore-core](../user-guide/agentcore.md#Core-Service-System). - -The common usage of heartbeat system is as follows: - -```java -// create netty client -NettyClient nettyClient = ClientManager.getNettyClientFactory().getNettyClient( - AgentConfigManager.getNettyServerIp(), - Integer.parseInt(AgentConfigManager.getNettyServerPort())); -// create heartbeat message -HeartbeatMessage message = new HeartbeatMessage(); -// customize additional data in heartbeat message -message.registerInformation("${key}", "${value}"); -// build message -String msg = message.generateCurrentMessage(); -// Serialization, and send through the Netty client with the data type annotated as heartbeat -nettyClient.sendData(msg.getBytes(Charset.forName("UTF-8")), Message.ServiceData.DataType.SERVICE_HEARTBEAT); -``` - -The `HeartbeatMessage` contains the following data by default: - -- `hostname`: hostname of the sending client -- `ip`:ip of the sending client -- `app`:application name (`appName` at startup) -- `appType`:application type, (`appType` at startup) -- `heartbeatVersion`:time of last heartbeat -- `lastHeartbeat`:time of last heartbeat -- `version`:version of sermant-agentcore-core - -### Initialize Heartbeat of Plugin - -The **Heartbeat Service** gets the name and version of the plugin from the **Plugin Manager** when it is initialized: -```java -// key is the name of plugin, value is the version of plugin -Map pluginVersionMap = PluginManager.getPluginVersionMap(); -``` - -Every once in a while, a heartbeat message is built for each `main` of plugin module and sent using heartbeat system. The interval is configured in the core configuration file `config.properties`: -```properties -# unit:ms -heartbeat.interval=3000 -``` - -Besides the information that heartbeat system sends regularly, two additional parameters will be added to the heartbeat message: - -- `pluginName`:the name of plugin -- `pluginVersion`:the version of plugin - -### Custom Data - -The **Heartbeat Service** allows plugin developers to customize the plugin's heartbeat message with additional dynamic parameters: -```java -final HeartbeatService service = ServiceManager.getService(HeartbeatService.class); -service.setExtInfo(new ExtInfoProvider() { - @Override - public Map getExtInfo() { - // do something - } -}); -``` - -When the `setExtInfo` method is executed, it will find the `jar` package of plugin or plugin service through the custom `ExtInfoProvider` implementation and get the value of `sermant-plugin-name ` of its `manifest` file. Once the plugin name is obtained, the **Heartbeat Service** can correctly bind dynamic parameters to the corresponding heartbeat message. - -The `ExtInfoProvider` interface defines `getExtInfo` method, through which the **Heartbeat Service** will dynamically fetch additional parameters each time a heartbeat message is built. - -## How to Use - -In general, the **Heartbeat Service** is a no-concern for plugin developers. Customizing data for heartbeat messages is only necessary if the plugin `backend` needs to fetch specific data from the Kafka heartbeat topic of the **Backend Module**. When plugins need to customize data for their heartbeat messages, usually you can develop a [custom plugin service](dev_plugin_code.md#Plugin-Service) by [adding custom data](#Custom-Data) in the `start` method. - -You can refer to [DemoHeartBeatService](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/template/template-plugin/src/main/java/com/huawei/example/demo/service/DemoHeartBeatService.java) for your development. - -[Back to README of **Sermant** ](../README.md) \ No newline at end of file diff --git a/docs/dev-guide/service_send-zh.md b/docs/dev-guide/service_send-zh.md deleted file mode 100644 index 519af7889e..0000000000 --- a/docs/dev-guide/service_send-zh.md +++ /dev/null @@ -1,37 +0,0 @@ -# 统一数据发送 - -[简体中文](service_send-zh.md) | [English](service_send.md) - -本文档主要介绍**核心模块**的[统一网关数据发送服务](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/send) - -`GatewayClient`:统一数据发送服务,简称统一发送服务,用于把Agent数据发往sermant-backend,再由sermant-backend转发给Kafka。`GatewayClient` 是数据发送的客户端。 - -用户通过调用服务提供的`send(byte[] data, int typeNum)`方法来发送数据。 -```java -ServiceManager.getService(GatewayClient.class).send(data, typeNum); -``` -其中参数`data`为待发送数据的字节,参数`typeNum`为数据的类型编号,它是某特定类型数据在所对接的sermant-backend的唯一标识编号,即同一个类型编号在一个sermant-backend实例或集群内只能表示一种类型数据。sermant-backend通过该编号来定位到相应的Kafka topic,以正确地把数据转发到该数据类型对应的topic当中。数据类型以及编号定义在[Message.proto文件](../../sermant-agentcore/sermant-agentcore-core/src/main/proto/Message.proto)的`ServiceData`元素的`DataType`当中。格式为``DATA_TYPE = typeNum``,其中`DATA_TYPE`为数据类型,`typeNum`为类型编号。 - -```protobuf -message ServiceData { - enum DataType { - DATA_TYPE_1 = 0, - DATA_TYPE_2 = 1, - ... - DATA_TYPE_N = typeNumN; - } -} -``` - -相应的,在sermant-backend模块的[Message.proto文件](../../sermant-backend/src/main/proto/Message.proto)也要添加相应的数据类型和编号,内容和格式与上面相同。 - -数据类型与Kafka topic之间映射关系的配置在sermant-backend模块的配置文件[application.properties](../../sermant-backend/src/main/resources/application.properties)的`datatype.topic.mapping`元素当中,配置规则为``datatype.topic.mapping.${typeNum} = kafka-topic``。 - -```properties -datatype.topic.mapping.0=topic-zero -datatype.topic.mapping.1=topic-one -... -datatype.topic.mapping.n=topic-n -``` - -[返回**Sermant**说明文档](../README-zh.md) diff --git a/docs/dev-guide/service_send.md b/docs/dev-guide/service_send.md deleted file mode 100644 index 6d3b6b8e3f..0000000000 --- a/docs/dev-guide/service_send.md +++ /dev/null @@ -1,37 +0,0 @@ -# Unified Data Sending - -[简体中文](service_send-zh.md) | [English](service_send.md) - -This document mainly introduces [Unified Data Sending Service](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/send) of **sermant-agentcore-core**. - -`GatewayClient`:The unified gateway data sending service, is used to send data of sermant-agent to the sermant-backend. And then the sermant-backend send these data to Kafka. `GatewayClient` is used to send data of sermant-agent. - -Developers can send data by invoking the `send(byte[] data, int typeNum)` method provided by `GatewayClient`. -```java -ServiceManager.getService(GatewayClient.class).send(data, typeNum); -``` -The parameter `data` is the byte of the data to be sent, and the parameter `typeNum` is the type number of the data, which is the unique identification number of a specific type of data in the connected sermant-backend. That is, the same type number can only represent one type of data in sermant-backend instance or cluster. The sermant-backend uses this number to locate the Kafka topic and sends the data to the appropriate topic for that data type. The data types and numbers are defined in the `DataType` of `ServiceData` in [Message.proto](../../sermant-agentcore/sermant-agentcore-core/src/main/proto/Message.proto). The format is `DATA_TYPE = typeNum`, where `DATA_TYPE` is the data type, `typeNum` is the type number. - -```protobuf -message ServiceData { - enum DataType { - DATA_TYPE_1 = 0, - DATA_TYPE_2 = 1, - ... - DATA_TYPE_N = typeNumN; - } -} -``` - -Accordingly, the corresponding data type and number should be added in the [Message.proto](../../sermant-backend/src/main/proto/Message.proto), in which content and format is the same as above. - -The mapping between data types and Kafka topics is configured in the element `datatype.topic.mapping` of [application.properties](../../sermant-backend/src/main/resources/application.properties) of sermant-backend. The configuration rule is `datatype.topic.mapping.${typeNum} = kafka-topic`. - -```properties -datatype.topic.mapping.0=topic-zero -datatype.topic.mapping.1=topic-one -... -datatype.topic.mapping.n=topic-n -``` - -[Back to README of **Sermant** ](../README.md) diff --git a/docs/dev-guide/service_template.md b/docs/dev-guide/service_template.md deleted file mode 100644 index ac8e5ec51b..0000000000 --- a/docs/dev-guide/service_template.md +++ /dev/null @@ -1,9 +0,0 @@ -# service name - -[服务功能目录](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service) - -[定位 是什么]: todo -[功能 做什么]: todo -[使用方式 怎么做]: todo - -[返回**Sermant**说明文档](../README.md) diff --git a/docs/dev-guide/third_party_copyright-zh.md b/docs/dev-guide/third_party_copyright-zh.md deleted file mode 100644 index 187d221f89..0000000000 --- a/docs/dev-guide/third_party_copyright-zh.md +++ /dev/null @@ -1,92 +0,0 @@ -# 第三方版权说明手册 - -[简体中文](third_party_copyright-zh.md) | [English](third_party_copyright.md) - -本文档针对开发过程中涉及的**第三方**源码或二进制包的版权作相关说明。 - -## 源码引用 - -如果在代码中,存在以下情况,视为对**第三方**源码的**引用**: - -- **整体拷贝**:直接拷贝**第三方**源码中的文件,在其基础上进行修改。 -- **局部拷贝**:拷贝**第三方**源码中部分方法或内部类,将其用于自研代码中。 -- **设计参考**:开发者在进行架构设计时,若参考**第三方**的架构,且两种架构中存在定位相同的内容,也视为 **引用**。 - -以上三种情况中,需要开发者对涉及的文件做如下操作: - -- 在`LICENSE`文件中添加对**第三方**源码的拷贝说明,形如: - ```txt - The following files contain a portion of ${THIRD PARTY PROJECT NAME} project. - - ${RELATED FILE A} in this product is copied from ${THIRD PARTY FILE A} of ${THIRD PARTY PROJECT NAME} project. - - ${RELATED FILE B} in this product is copied from ${THIRD PARTY FILE B} of ${THIRD PARTY PROJECT NAME} project. - - ... - - ${THIRD PARTY PROJECT NAME} project is published at ${THIRD PARTY PROJECT CODEBASES URL} and its license is ${THIRD PARTY PROJECT LICENSE NAME}. - ``` - 其中: - - `THIRD PARTY PROJECT NAME`表示**第三方**工程的名称。 - - `RELATED FILE`为本项目的**涉事文件**:为类时,键入全限定名路径;否则,键入项目相对路径。 - - `THIRD PARTY FILE`表示**第三方**的**被拷贝文件**:为类时,键入全限定名路径;否则,键入项目相对路径;如果**第三方**项目是单模块项目,也可键入source目录相对路径。 - - `THIRD PARTY PROJECT CODEBASES URL`表示**第三方**工程源码仓的地址;如果找不到源码仓地址,可以改为官方网站地址或源码下载地址,总之原则就是要做到可溯源。 - - `THIRD PARTY PROJECT LICENSE NAME`表示**第三方**工程的`LICENSE`名称,通常可以参考其`pom`文件中的`licenses`标签,如果存在多个`LICENSE`,则改为复数形式: - ```txt - ... - and its licenses are ${LICENSE A}, ${LICENSE B}, ..., and ${LICENSE C}. - ``` - - 如果已经存在目标**第三方**工程的条目,则掐头去尾将中间的拷贝信息填入即可。 -- 在**涉事文件**中键入**被拷贝文件**的头信息(如果有),并添加拷贝源信息,形如: - ```txt - Based on ${THIRD PARTY FILE} from the ${THIRD PARTY PROJECT NAME} project. - ``` -- 如果**第三方**工程中含有`NOTICE`文件,则将其追加到本工程的`NOTICE`文件结尾。如果已经包含,无需重复追加多次。 - -## 带依赖jar包 - -如果开发者: - -- 没有修改`resources`标签的内容 -- 开发的模块中`sermant.basedir`参数正确指向顶层目录 -- 不打带依赖`jar`包,或使用`shade`插件打带依赖`jar`包,且没有修改`transformers`标签 - -那么无需对输出的`jar`包作任何调整,否则请详细阅读下面的说明,并按实际情况处理。 - -在默认打包过程中,需要将本工程默认的`LICENSE`文件和`NOTICE`文件打入。这两个文件存放于`sermant-package`模块的`resources/META-INF`目录下,由`resources`标签特别地指向。 - -一般情况下,只要保证打包的模块(`packaging`标签的值不为`pom`)中`sermant.basedir`参数指向本工程的顶层目录,就会默认添加这两个文件,无需特别关心。 - -在打包流程中,使用`shade`插件、`assembly`插件或`spring`打包插件打带依赖`jar`包时,如果打入的**第三方**`jar`包中含有`NOTICE`文件,最好将他们与本工程默认的`NOTICE`文件合并。`shade`插件的`ApacheNoticeResourceTransformer`正好可以做到这一点。这一点在顶层工程的`pom`文件中有配置,除非有修改`Transformer`的需要,否则不建议覆盖顶层工程的`shade`插件设置。 - -注意:本节所提到的默认的`LICENSE`文件和`NOTICE`文件,指的是仅包含本工程相关信息的文件。在项目顶层目录中存放的`LICENSE`文件和`NOTICE`文件,系整理过源码拷贝信息后的文件,包含本工程相关信息和被拷贝的**第三方**工程信息。 - -## RELEASE产品包 - -`RELEASE`产品包中需要将工程源码的`LICENSE`文件和`NOTICE`文件带上,前者还需要添加`RELEASE`产品包中所有涉及的**第三方**`jar`包的`LICENSE`信息。`RELEASE`产品包还需要将与本工程`LICENSE`不同的**第三方**`LICENSE`存放于`licenses`目录中带上,该目录存放于`sermant-package`模块的`resources`目录中。 - -综上,`RELEASE`产品包内部结构形如: -- `agent`目录: 核心增强逻辑 -- `server`目录: 增强逻辑配套的服务端 -- `licenses`目录: 与本工程`LICENSE`不同的**第三方开源依赖项目**`LICENSE`存放目录 -- `LICENSE`文件: 本工程`LICENSE`文件,附加拷贝**第三方开源**源码的LICENSE声明,以及`RELEASE`产品包中涉及的所有**第三方开源依赖项目**`jar`包的`LICENSE`说明 -- `NOTICE`文件: 本工程`NOTICE`文件,追加拷贝**第三方开源**源码的`NOTICE`文件。 - -本工程通过以下方式生成`RELEASE`产品包的`LICENSE`文件、`NOTICE`文件和`licenses`目录: -- 通过`license-maven-plugin`插件生成项目中所有涉及的第三方`jar`包的`LICENSE`信息: - ```shell - mvn license:aggregate-add-third-party - ``` - 生成的文件`LICENSE-binary-suffix.txt`存放于`sermant-package`模块的`resources`目录。该过程初次执行时间较久,请耐心等待。 -- 工程各组件打包,输出到临时目录下。 -- 在`sermant-package`模块打包时: - - 将工程源码的`LICENSE`文件、`NOTICE`文件和`licenses`目录拷贝到临时目录中。 - - 调用脚本将`LICENSE-binary-suffix.txt`文件追加到临时目录的`LICENSE`文件。 - - 将临时目录压缩为`RELEASE`产品包。 - -综上,开发者可以通过以下命令编译并发布`RELEASE`产品包: -```shell -mvn license:aggregate-add-third-party clean package -Dmaven.test.skip -``` - -[返回**Sermant**说明文档](../README-zh.md) diff --git a/docs/dev-guide/third_party_copyright.md b/docs/dev-guide/third_party_copyright.md deleted file mode 100644 index 889c86a2f9..0000000000 --- a/docs/dev-guide/third_party_copyright.md +++ /dev/null @@ -1,94 +0,0 @@ -# Third Party Copyright Guide - -[简体中文](third_party_copyright-zh.md) | [English](third_party_copyright.md) - -This document focus on the **copyright** of **third party** source code or binary packages involved in the development process. - -## Source Code Reference - -If the following situation exists in the code, it is considered as a **reference** to **third party** source code: - -- **Copy Overall**: Copy files directly from **third party** source code and make changes based on them. -- **Partial Copy**: Copy some methods or inner classes in **third party** source code and use them in the self-developed code. -- **Reference Design**: If developers refer to the architecture of a **third party** when designing the architecture, and there is the same content in the two architectures, it is also considered as **reference**. - -In all three cases, developers are required to complete the following work with the files involved: - -- Add instructions for copying **third party** source code to your `LICENSE` file, like this: - ```txt - The following files contain a portion of ${THIRD PARTY PROJECT NAME} project. - - ${RELATED FILE A} in this product is copied from ${THIRD PARTY FILE A} of ${THIRD PARTY PROJECT NAME} project. - - ${RELATED FILE B} in this product is copied from ${THIRD PARTY FILE B} of ${THIRD PARTY PROJECT NAME} project. - - ... - - ${THIRD PARTY PROJECT NAME} project is published at ${THIRD PARTY PROJECT CODEBASES URL} and its license is ${THIRD PARTY PROJECT LICENSE NAME}. - ``` - Note: - - `THIRD PARTY PROJECT NAME` represents the name of the **third party** project. - - `RELATED FILE` is the **related file** for this project: if it is a class, type the path of full qualified class name; Otherwise, type the project relative path. - - `THIRD PARTY FILE` represents the **copied file** of the **third party**: if it is a class, type the path of full qualified class name; Otherwise, type the project relative path. If the **third party** project is a single module project, you can also type the relative path to the source directory. - - `THIRD PARTY PROJECT CODEBASES URL` represents the address of the **third party** project repository; If you can't find the address of source code, you can change it to the official website address or source code download address. In short, the principle is to be traceable. - - `THIRD PARTY PROJECT LICENSE NAME` represents to the `LICENSE` name of the **third party** project, which is usually referred to the `licenses` label in the `pom` file, or pluralized if multiple `LICENSE` exist: - - ```txt - ... - and its licenses are ${LICENSE A}, ${LICENSE B}, ..., and ${LICENSE C}. - ``` - - If there is already an entry for the target **third party** project, just cut back and fill in the copy information in the middle. -- Type the header of the **copied file** (if exists) in the **file in question** and add the copy source information, like this: - ```txt - Based on ${THIRD PARTY FILE} from the ${THIRD PARTY PROJECT NAME} project. - ``` -- If a **third party** project contains a `NOTICE` file, append it to the end of the `NOTICE` file of current project. If it is already included, there is no need to append it more than once. - -## Jar Package with Dependencies - -If developers: - -- have not modified the content of the `resources` label. -- develop the module of where the `sermant.basedir` parameter correctly points to the top-level directory. -- package the project without jar packages with dependencies or package the jar packages with dependencies via `shade` and have not modified `transformers` label. - -There is no need to make any adjustments to the output `jar` package, otherwise please read the instructions below and take it as it is. - -In the default packaging process, the current project's default `LICENSE` file and `NOTICE` file need to be inserted. These two files are stored in the `resources/META-INF` directory of the `sermant-package` module and are specifically pointed to by the `resources` label. - -In general, as long as the `sermant.basedir` parameter in the packaged module (the `packaging` label is not `pom`) points to the top-level directory of the project, these files will be added by default and don't need to be concerned. - -When using the `shade` `assembly` or `spring` package plugin to package a jar package with dependencies, if the `NOTICE` file is included in the **third-party ** `jar` package, it is best to merge it with the default `NOTICE ` file of current project. `ApacheNoticeResourceTransformer` of ` shade ` plugin just can do this. This is configured in the top-level project's `pom` file. And it is not recommended to override the top-level project's settings of `shade` plugin unless you need to modify the `Transformer`. - -Note: The default `LICENSE` file and `NOTICE` file mentioned in this section refer to files that only contain information about current project. The `LICENSE` file and `NOTICE` file stored in the top-level directory of the project are the files after sorting out the source code copy information, containing information related to current project and the copied **third party** project information. - -## RELEASE Package - -The `RELEASE` package needs to include the `LICENSE` file of the project source code and the `NOTICE` file. The former also needs to add the `LICENSE` information of all the **third party** `jar` packages included in the `RELEASE` package. The `RELEASE` package also requires **third party** `LICENSE`, which are different from the project's `LICENSE`, to be placed in the `licenses` directory. The directory is located in the `resources` directory of the `sermant-package` module. - -To summarize, the internal structure of the `RELEASE` package looks like this: -- `agent` directory: core enhancement logic. -- `server` directory: supporting server sides. -- `licenses ` directory: where `LICENSE` of **third-party-open-source dependencies** that are different from the project's `LICENSE` locates in. -- `LICENSE` file: the project's `LICENSE` file, which appends a copy of the LICENSE statement of source code of **third-party-open-source** project, and the `LICENSE` description of all `jar` packages of **third-party open-source dependencies** included in the `RELEASE` package. -- `NOTICE` file: the `NOTICE` file of this project, appends the `NOTICE` file of source code of **third-party-open source** project. - -This project generates a `LICENSE` file, a `NOTICE` file, and a `licenses` directory for the `RELEASE`package as follows: -- Generate the `LICENSE` information for all third-party `jar` packages involved in the project via the `license-maven-plugin`: - ```shell - mvn license:aggregate-add-third-party - ``` - The resulting file, `LICENSE-binary-suffix.txt`, is stored in the `resources` directory of the `sermant-package` module. This process takes a long time to execute for the first time, so be patient. -- Project components are packaged and exported to a temporary directory. -- When`sermant-package`module is packaging, it will: - - copy the `LICENSE` file, `NOTICE` file, and `licenses` directory of source code of current project into a temporary directory. - - run a script to append the `LICENSE-binary-suffix.txt` file to the `LICENSE` file in the temporary directory. - - compress the temporary directory to a 'RELEASE' package. - -To sum up, developers can compile and release the `RELEASE` package with the following command: -```shell -mvn license:aggregate-add-third-party clean package -Dmaven.test.skip -``` - -[Back to README of **Sermant** ](../README.md) - diff --git a/docs/dev-guide/version_manage-zh.md b/docs/dev-guide/version_manage-zh.md deleted file mode 100644 index 7616cb0dbc..0000000000 --- a/docs/dev-guide/version_manage-zh.md +++ /dev/null @@ -1,38 +0,0 @@ -# 版本管理手册 - -[简体中文](version_manage-zh.md) | [English](version_manage.md) - -本文档主要对**Sermant**的代码版本管理做介绍。 - -**Sermant**直接使用[versions-maven-plugin](https://github.com/mojohaus/versions-maven-plugin)做版本管理,常用的命令如下: - -- 更新版本号为`${version}`: - ```shell - mvn versions:set -DnewVersion=${version} - ``` - 该命令默认保留原`pom`文件备份。 -- 回滚版本号: - ```shell - mvn versions:revert - ``` -- 提交新版本号更新,即删除原`pom`文件备份: - ```shell - mvn versions:commit - ``` -- 更新版本号为`${version}`并提交: - ```shell - mvn versions:set -DnewVersion=${version} -DgenerateBackupPoms=false - ``` - 该命令不会备份原`pom`文件,使用时要注意版本号别写错。 - -以上更新版本的命令中,只会修改项目中与顶级模块的版本相同的模块,如果需要单独对某个模块进行更新,可以使用`-pl`参数指定,比如: -```shell -mvn versions:set -DnewVersion=${version} -DgenerateBackupPoms=false -pl ${module} -``` -其中`${module}`可以传递`${groupId}:${artifactId}`,也可以传递相对路径。多个模块的情况下,使用`','`号连接。 - -关于设置版本命令`versions:set`的更多信息可以查看[Versions Maven Plugin versions:set](http://www.mojohaus.org/versions-maven-plugin/set-mojo.html)。 - -更多`versions-maven-plugin`的命令可以查看[Versions Maven Plugin Introduction](http://www.mojohaus.org/versions-maven-plugin/index.html)。 - -[返回**Sermant**说明文档](../README-zh.md) \ No newline at end of file diff --git a/docs/dev-guide/version_manage.md b/docs/dev-guide/version_manage.md deleted file mode 100644 index 39397bfa98..0000000000 --- a/docs/dev-guide/version_manage.md +++ /dev/null @@ -1,41 +0,0 @@ -# Version Management - -[简体中文](version_manage-zh.md) | [English](version_manage.md) - -This document is about **Version Management of Sermant**. - -**Sermant** manages versions via [versions-maven-plugin](https://github.com/mojohaus/versions-maven-plugin). Common commands are as follows: - -- Update current version to `${version}`: - ```shell - mvn versions:set -DnewVersion=${version} - ``` - This command keeps the original `pom` file backup by default. - -- Rollback the version: - ```shell - mvn versions:revert - ``` - -- Commit the new version updated (delete the original `pom` file backup): - ```shell - mvn versions:commit - ``` - -- Update current version to `${version}` and commit: - ```shell - mvn versions:set -DnewVersion=${version} -DgenerateBackupPoms=false - ``` - This command will not back up the original `pom` file, be careful not to write the wrong version number when executing it. - -After executing the above update commands, only the modules with the same version as the top-level module in the project will be modified. If you need to update a module separately, you can specify it with `-pl`, for example: -```shell -mvn versions:set -DnewVersion=${version} -DgenerateBackupPoms=false -pl ${module} -``` -Where `${module}` can be `${groupId}:${artifactId}`. Or you can input relative path of the module. In the case of multiple modules, please use `','`. - -For more information on setting versions with the `versions:set` command, refer to [Versions Maven Plugin versions:set](http://www.mojohaus.org/versions-maven-plugin/set-mojo.html). - -Refer to [Versions Maven Plugin Introduction](http://www.mojohaus.org/versions-maven-plugin/index.html) for more `versions-maven-plugin` commands. - -[Back to README of **Sermant** ](../README.md) \ No newline at end of file diff --git a/docs/user-guide/FAQ-zh.md b/docs/user-guide/FAQ-zh.md deleted file mode 100644 index 84f889cf27..0000000000 --- a/docs/user-guide/FAQ-zh.md +++ /dev/null @@ -1,12 +0,0 @@ -# Sermant 框架功能 - -[简体中文](FAQ-zh.md) | [English](FAQ.md) - -## 启动参数appName是什么参数? - -- `appName`表示宿主应用的名称,多个实例`appName`可以相同,`实例id`不同。 - -## Sermant提供哪些方面的服务治理插件? - -- Sermant有着很强的扩展性,除了框架本身提供的服务治理插件([限流降级功能介绍](../user-guide/flowcontrol/flowcontrol.md),[服务注册功能介绍](../user-guide/registry/document.md)等)之外, 开发者可以根据业务需求去开发插件包括(数据收集,链路等)。 - diff --git a/docs/user-guide/FAQ.md b/docs/user-guide/FAQ.md deleted file mode 100644 index c54845568b..0000000000 --- a/docs/user-guide/FAQ.md +++ /dev/null @@ -1,12 +0,0 @@ -# FAQ About Sermant Framework - -[简体中文](FAQ-zh.md) | [English](FAQ.md) - -## **What does the input parameter "appName" mean** - -- The `appName` represents the name of the host application. Multiple instances can have the same `appName` and different `instanceName`. - -## **What kind of service governance plugins does Sermant provide?** - -- Sermant is extensible. Besides the service governance plugin provided by the framework itself ([Introduction to FlowControl](../user-guide/flowcontrol/flowcontrol.md), [Introduction to Service Registration](../user-guide/registry/document.md)), developers can develop plugins including (data collection, link collection, etc.) according to business requirements. - diff --git a/docs/user-guide/agentcore-zh.md b/docs/user-guide/agentcore-zh.md deleted file mode 100644 index 6f4316e082..0000000000 --- a/docs/user-guide/agentcore-zh.md +++ /dev/null @@ -1,496 +0,0 @@ -# 核心模块介绍 - -[简体中文](agentcore-zh.md) | [English](agentcore.md) - -本文档主要介绍[**Sermant核心模块**](../../sermant-agentcore/sermant-agentcore-core),该模块提供处理字节码增强、统一配置、核心服务、插件管理等能力重要内核。 - -- [核心包版本](#核心包版本) -- [目录结构](#目录结构) -- [字节码增强](#字节码增强) -- [统一配置系统](#统一配置系统) - - [统一配置管理类](#统一配置管理类) - - [统一配置类](#统一配置类) - - [properties策略详解](#properties策略详解) - - [yaml策略详解](#yaml策略详解) - - [插件设定配置](#插件设定配置) -- [核心服务系统](#核心服务系统) - - [核心服务管理类](#核心服务管理类) - - [核心服务类](#核心服务类) -- [插件管理系统](#插件管理系统) - - [插件管理类](#插件管理类) - - [插件类加载器](#插件类加载器) - - [插件配置系统](#插件配置系统) - - [插件服务系统](#插件服务系统) -- [LubanAgent](#LubanAgent) -- [相关文档](#相关文档) - -本文更多地只是简单介绍[**Sermant核心模块**](../../sermant-agentcore/sermant-agentcore-core)中各个目录的意义,仅做抛砖引玉的作用,如果开发者想要更为细致的了解代码中业务逻辑,请移步至相关的目录或类查看。 - -## 核心包版本 - -核心包的版本,属于核心包的内禀属性,因此我们将版本的定义封装到`manifest`文件中,作为`jar`包的元信息存在。核心包版本信息封装于`manifest`文件的`Sermant-Version`参数中,默认取值为`project.version`。在代码中,可以通过以下方法获取核心包版本: -```java -String version = BootArgsIndexer.getCoreVersion(); -``` - -如果需要修改核心包的版本,可以直接修改`project.version`的值。 - -## 目录结构 - -[**Sermant核心模块**](../../sermant-agentcore/sermant-agentcore-core)的代码包含以下目录结构: - -- `agent`目录,存放[字节码增强](#字节码增强)相关代码。 -- `common`目录,存放一些公共的代码。 -- `config`目录,存放[统一配置系统](#统一配置系统)相关代码。 -- `exception`目录,存放自定义异常。 -- `plugin`目录,存放[插件管理系统](#插件管理系统)相关代码。 -- `service`目录,存放[核心服务系统](#核心服务系统)相关代码。 -- `util`目录,存放公用工具类。 -- `AgentCoreEntrance`类,系[**Sermant核心模块**](../../sermant-agentcore/sermant-agentcore-core)的入口,调用`run`方法、传入**启动参数**和*Instrumentation*对象带起。 - -[**Sermant核心模块**](../../sermant-agentcore/sermant-agentcore-core)中还包含以下资源: - -- `META-INF/services`目录,*SPI*配置文件目录。 - - `com.huaweicloud.sermant.core.config.common.BaseConfig`文件,用于声明统一配置类。 - - `com.huaweicloud.sermant.core.config.strategy.LoadConfigStrategy`文件,用于声明配置的加载策略。 - - `com.huaweicloud.sermant.core.service.BaseService`文件,用于声明核心服务实现。 - -## 字节码增强 - -**Sermant**的**字节码增强**代码见于[agent](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent)目录。 - -**Sermant**基于`byte-buddy`字节码增强框架做字节码增强,主要采用[**byte-buddy委派**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core//plugin/agent/transformer/AdviceTransformer.java)的方式进行,对于原生类增强的场景,则使用[**Advice模板类**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/template)配合[**byte-buddy advice**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/transformer/BootstrapTransformer.java)技术进行增强。 - -`plugin/agent`目录下主要包含以下内容: - -- `declarer`目录,存放**增强定义接口**,是插件开发者需要关注的内容。 -- `interceptor`目录,存放**拦截器接口**, 是插件开发者需要关注的内容。 -- `matcher`目录,存放**被增强类的匹配器**,是插件开发者需要关注的内容。 -- `template`目录,存放**Advice模板类**。 -- `transformer`目录,存放**字节码转换器**。 -- `ByteBuddyAgentBuilder`类,字节码增强的入口。 - -### 增强定义 - -插件开发者在编写**增强定义**时,实现[PluginDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/PluginDeclarer.java)接口的`getClassMatcher`方法和`getInterceptDeclarers`方法即可,详情可参见[插件代码开发手册中增强定义一节](../dev-guide/dev_plugin_code-zh.md#增强定义)。 - -注意不要忘记添加`PluginDeclarer`的*SPI*配置文件。 - -### 拦截器 - -插件开发者在编写**拦截器**时,只需实现[interceptor](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/interceptor)目录的`Interceptor`接口即可。 - -具体如何怎么做,可以参见[插件代码开发手册中拦截器一节](../dev-guide/dev_plugin_code-zh.md#拦截器)。 - -## 统一配置系统 - -**Sermant**的**统一配置系统**代码见于[config](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config)目录。 - -`config`目录下包含以下内容: - -- `common`目录,存放公用内容。 - - `BaseConfig`类,**统一配置类**通用接口。 - - `ConfigFieldKey`注解,用于为**统一配置类**的字段器别名。 - - `ConfigTypeKey`注解,用于为**统一配置类**起别名。 -- `strategy`目录,存放加载配置策略的相关内容。 - - `LoadConfigStrategy`接口,为配置加载策略接口,为加载不同格式的配置文件提供规范方法。 - - `LoadPropertiesStrategy`类,用于加载`properties`格式配置文件的策略,该策略主要用于加载统一配置文件`config.properties`。 - - `LoadYamlStrategy`类,用于加载`yaml`格式配置文件的策略,该策略主要用于加载插件设置和插件配置,详见于[插件配置系统](#插件配置系统)。 -- `utils`目录,存放一些统一配置系统使用到的工具类。 -- `ConfigManager`类,统一配置管理类,提供加载和获取统一配置的方法。 - -### 统一配置管理类 - -**统一配置管理类**`ConfigManager`中,使用者可以通过`getConfig`方法获取**统一配置类**实例: -```java -ConfigExample config = ConfigManager.getConfig(ConfigExample.class); -``` - -### 统一配置类 - -**统一配置系统**是一个加载**静态配置**为**Java Pojo**的管理系统,因此,**统一配置类**必须是一个实现[BaseConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/BaseConfig.java)接口的**Java Pojo**。这些**统一配置类**的具体要求由`LoadPropertiesStrategy`而定,详见[properties策略详解](#properties策略详解)。至于插件相关的[插件配置](#插件配置系统),则与`LoadYamlStrategy`的要求有关,详见[yaml策略详解](#yaml策略详解)。 - -**统一配置类**是一个**Java Pojo**,他的`getter`方法和`setter`方法可以直接使用`lombok`的`Data`注解、`Getter`注解和`Setter`注解生成。 - -注意,编写完**统一配置类**之后,不要忘记添加[BaseConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/BaseConfig.java)接口的*SPI*配置文件: - -- 在资源目录`resources`下添加`META-INF/services`文件夹。 -- 在`META-INF/services`中添加`com.huaweicloud.sermant.core.config.common.BaseConfig`配置文件。 -- 在上述文件中,以换行为分隔,键入插件包中所有的**统一配置类**。 - -### properties策略详解 - -`LoadPropertiesStrategy`加载策略用于对*properties*格式的配置文件进行加载,现在主要用于加载统一配置文件`config.properties`。 - -`LoadPropertiesStrategy`的思路简单来说就是,以**统一配置类**的全限定名或别名为前缀,以**统一配置类**的属性名或别名为后缀,拼接成*properties*格式的键,获取相应值之后,转化为对应属性的类型并赋值。 - -假设有以下**统一配置类**: -```java -package com.huawei.example; -public class ConfigExample implements BaseConfig { - private String string; - private int intField; - // getter and setter -} -``` - -则对应的配置可能形如: -```properties -# 全限定名.属性名=属性值 -com.huawei.example.ConfigExample.string=value -com.huawei.example.ConfigExample.intField=123456 -``` - -#### 属性类型 - -`LoadPropertiesStrategy`支持的属性类型包括: - -- 布尔、数值类的基础类型及包装类型 -- 字符串类型 -- 枚举类型 -- 上述类型构成的数组 -- 前三种类型构成的*List* -- 前三种类型构成的*Map* - -其中`数组`和`List`有两种配置的形式,一种是将字符串用`','`分割: - -```properties -# 数组配置 -com.huawei.example.ConfigExample.stringArr=value1,value2,value3 -# List列表配置 -com.huawei.example.ConfigExample.intList=100,200,300 -``` - -另一种为索引的方式: - -```properties -# 数组配置 -com.huawei.example.ConfigExample.stringArr[0]=value1 -com.huawei.example.ConfigExample.stringArr[1]=value2 -com.huawei.example.ConfigExample.stringArr[2]=value3 -# List列表配置 -com.huawei.example.ConfigExample.intList[0]=100 -com.huawei.example.ConfigExample.intList[1]=200 -com.huawei.example.ConfigExample.intList[2]=300 -``` - -而`Map`的解析方式也有两种方式,一是是通过`','`分割键值对,然后通过`':'`分割键值: -```properties -# Map字典配置 -com.huawei.example.ConfigExample.string2IntMap=key1:value1,key2:value2,key3:value3 -``` - -另一种方式为把key放在属性名后面: - -```properties -# Map字典配置 -com.huawei.example.ConfigExample.string2IntMap.key1=value1 -com.huawei.example.ConfigExample.string2IntMap.key2=value2 -com.huawei.example.ConfigExample.string2IntMap.key3=value3 -``` - - - -需要注意的是,`LoadPropertiesStrategy`不支持复杂类型属性。 - -#### 起别名 - -`LoadPropertiesStrategy`支持使用`ConfigTypeKey`注解和`ConfigFieldKey`注解为全限定名和属性名起别名,假定上述`ConfigExample`类修改如下: - -```java -@ConfigTypeKey("config.example") -public class ConfigExample implements BaseConfig { - @ConfigFieldKey("stringField") - private String string; - private int intField; - // getter and setter -} -``` - -则对应的配置如: -```properties -# 全限定名别名.属性名别名=属性值 -config.example.stringField=value -config.example.intField=123456 -``` - -#### 值内省 - -`LoadPropertiesStrategy`中的属性值支持内省,可以使用`${}`去映射当前配置、系统变量、启动参数等元素。比如`ConfigExample`的配置可以设置为: -```properties -# appName映射启动参数,user.home映射系统变量,com.huawei.example.ConfigExample.intField映射当前配置内容 -com.huawei.example.ConfigExample.string=value, ${appName:test}, ${user.home}, ${com.huawei.example.ConfigExample.intField} -com.huawei.example.ConfigExample.intField=123456 -``` - -以`${appName:test}`为例,`appName`为内省的检索键,`test`则是内省失败后的默认取值。内省的检索优先级如下: - -- 启动参数(入参和启动配置) -- 当前配置文件(即`config.properties`) -- 环境变量 -- 系统变量 -- 默认值(即`':'`后内容) - -启动参数中包含的内容可参见[入口模块介绍](entrance-zh.md) - -#### 特殊键值对 - -`LoadPropertiesStrategy`支持优先使用启动参数中的键值对,启动参数中不存在时,才会使用配置文件中的配置。 - -假定有以下配置类: -```java -@ConfigTypeKey("env") -public class ConfigExample implements BaseConfig { - private String tag; - private String secret; - // getter and setter -} -``` - -则`tag`和`secret`两个属性优先使用启动配置`bootstrap.config`中的`env.tag`值和`env.secret`值。 - -### yaml策略详解 - -`LoadYamlStrategy`加载策略用于对*yaml*格式的配置文件进行加载,现在主要用于加载插件设定`plugins.yaml`和插件配置`config.yaml`。鉴于插件设定较为简单,后面我们仅对**插件配置类**做介绍。 - -**插件配置类**和**统一配置类**一样,是个**Java Pojo**,只不过后者实现`BaseConfig`接口,前者实现`PluginConfig`接口,详情可查阅[插件代码开发手册的插件配置一节](../dev-guide/dev_plugin_code-zh.md#插件配置),我们这里用`PluginConfig`接口举例。 - -假设有以下**插件配置类**: -```java -package com.huawei.example; -public class ConfigExample implements PluginConfig { - private String string; - private int intField; - // getter and setter -} -``` - -则对应的配置可能形如: -```yaml -com.huawei.example.ConfigExample: - string: value - intField: 123456 -``` - -#### 属性类型 - -`LoadYamlStrategy`支持的属性类型包括: - -- 布尔、数值类的基础类型及包装类型 -- 字符串类型 -- 枚举类型 -- 复杂对象类型 -- 上述类型构成的数组 -- 前四种类型构成的*List* -- 前四种类型构成的*Map* - -#### 起别名 - -`LoadYamlStrategy`支持使用`ConfigTypeKey`注解和`ConfigFieldKey`注解为全限定名和属性名起别名,假定上述`ConfigExample`类修改如下: -```java -@ConfigTypeKey("config.example") -public class ConfigExample implements PluginConfig { - @ConfigFieldKey("stringField") - private String string; - private int intField; - // getter and setter -} -``` - -则对应的配置如: -```yaml -config.example: - stringField: value - intField: 123456 -``` - -需要注意的是,对于数组、List和Map中涉及的复杂对象,不支持`ConfigFieldKey`修正属性名。换言之,`ConfigFieldKey`仅对**插件配置类**的属性,及其复杂对象类型属性的属性有效。 - -#### 值内省 - -`LoadYamlStrategy`中的属性值支持内省,可以使用`${}`去映射当前集合、系统变量、启动参数等元素。比如`ConfigExample`的配置可以设置为: -```yaml -com.huawei.example.ConfigExample: - string: value, ${appName:test}, ${user.home}, ${intField} - intField: 123456 -``` - -以`${appName:test}`为例,`appName`为内省的检索键,`test`则是内省失败后的默认取值。内省的检索优先级如下: - -- 启动参数(入参和启动配置) -- 当前集合(如案例中的`ConfigExample`类) -- 环境变量 -- 系统变量 -- 默认值(即`':'`后内容) - -需要注意的是,`LoadPropertiesStrategy`可以映射到整个配置文件,`LoadYamlStrategy`由于配置格式的限制,只能映射当前的`Map`或**复杂对象**。 - -如果映射当前集合(**复杂对象**)的**公共属性**时,且**公共属性**使用了`ConfigFieldKey`做别名修正,那么能否正确映射和属性定义顺序有关,比如下面的**插件配置类**: -```java -@ConfigTypeKey("config.example") -public class ConfigExample implements PluginConfig { - private String field1; - @ConfigFieldKey("stringField") - private String field2; - private String field3; - // getter and setter -} -``` - -如果`field1`和`field3`需要使用`field2`则对应的配置如: -```yaml -config.example: - field1: value1, ${stringField} - stringField: value2 - field3: value3, ${field2} -``` - -基于上述情况,建议开发者不要对**公共属性**起别名修正。如果实在需要其别名,那么建议将这些**公共属性**统一放在**插件配置类**的开头或结尾。 - -启动参数中包含的内容可参见[入口模块说明](entrance-zh.md#启动参数)。 - -#### 特殊键值对 - -`LoadYamlStrategy`不支持使用启动参数中的键值对对**插件配置类**的属性赋值。 - -### 插件设定配置 - -**插件设定配置**即`plugins.yaml`文件,在[**Sermant核心模块**](../../sermant-agentcore/sermant-agentcore-core)中存在三个这样的文件: - -- [agent/plugins.yaml](../../sermant-agentcore/sermant-agentcore-config/config/plugins.yaml): 默认编译场景下的**插件设定配置**,不含示例工程。 -- [all/plugins.yaml](../../sermant-agentcore/sermant-agentcore-config/config/all/plugins.yaml): 执行-Pall参数打包时的**插件设定配置**,较`agent`多了示例工程 -- [example/plugins.yaml](../../sermant-agentcore/sermant-agentcore-config/config/example/plugins.yaml): 执行-Pexample参数打包时的**插件设定配置**,仅含示例工程 - -`plugins.yaml`中,配置了**Sermant**启动后需要加载的插件目录,形如: - -```yaml -plugins: - - plugin1 - - plugin2 - - plugin3 -``` - -这些配置的插件目录将对应到`pluginPackage`目录下的内容。 - -另外,开发者还可以通过`profile`来定义不同场景需加载的插件。例如: - -```yaml -profiles: - scene1: - - plugin1 - - plugin2 - scene2: - - plugin3 - - plugin4 - scene3: - - plugin5 - - plugin6 -profile: scene1, scene2 -``` - -在`profiles`中可以自定义不同场景的插件加载配置,在`profile`中可以配置那哪些场景在应用启动后生效。 - -## 核心服务系统 - -**Sermant**的**核心服务系统**代码见于[service](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service)目录。 - -`service`目录下中主要包括: - -- [BaseService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/BaseService.java): [**核心服务类**](#核心服务类) -- [ServiceManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/ServiceManager.java): [**核心服务管理类**](#核心服务类) -- 核心服务实现目录 - -### 核心服务管理类 - -**核心服务管理类**`ServiceManager`中,使用者可以通过`getService`方法获取**核心服务类**实例: -```java -ServiceExample service = ServiceManager.getService(ServiceExample.class); -``` - -### 核心服务类 - -**核心服务系统**是一个将实现[BaseService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/BaseService.java)的**核心服务类**加载、管理的系统,其核心就是实现**核心服务类**。 - -我们假定有一个叫`example`的服务,为其编写如下接口: -```java -public interface ServiceExample extends BaseService { - void foo(); -} -``` - -这样就定义了带有`foo`行为的`example`服务接口,他可能有如下实现: -```java -public class ServiceExampleImpl implements ServiceExample { - @Override - public void start() { - // initialize - } - - @Override - public void stop() { - // shut down - } - - @Override - public void foo() { - // do something - } -} -``` - -接下来,把`ServiceExampleImpl`添加到`BaseService`的*SPI*配置中即可使用: - -- 在资源目录`resources`下添加`META-INF/services`文件夹。 -- 在`META-INF/services`中添加`com.huaweicloud.sermant.core.service.BaseService`配置文件。 -- 在上述文件中,以换行为分隔,键入插件包中所有的**核心服务类**实现(`ServiceExampleImpl`)。 - -这样就能通过`ServiceManager`的`getService`方法获取到**核心服务类**实例了。 - -## 插件管理系统 - -**Sermant**的**插件管理系统**代码见于[plugin](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin)目录。 - -`plugin`目录下主要包括: - -- [classloader/PluginClassLoader](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/classloader/PluginClassLoader.java)类,即[插件类加载器](#插件类加载器)。 -- [config](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config)目录,里面存放着[插件配置系统](#插件配置系统)相关代码。 -- [service](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service)目录,里面存放着[插件服务系统](#插件服务系统)相关代码。 -- [PluginManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/PluginManager.java)类,即[插件管理类](#插件管理类) - -### 插件管理类 - -在**插件管理类**类中,主要对插件设定文件`plugins.yaml`中配置的插件目录进行遍历,对每个插件目录来说: - -- 加载其所有**插件包**至系统类加载器`AppClassLoader`。 -- 自定义[插件类加载器](#插件类加载器)加载所有**插件服务包**。 -- 加载所有相关的[插件配置](#插件配置系统)。 -- 加载所有相关的[插件服务](#插件服务系统)。 - -### 插件类加载器 - -**插件类加载器**即`PluginClassLoader`类。`PluginClassLoader`是一个特殊的`URLClassLoader`,他将持有单个功能的所有插件服务包的*URL*。`PluginClassLoader`破坏了双亲委派机制,在加载*Class*的时候,优先使用自己的*Class*,再调用父类原生的加载方法,具体执行逻辑如下: - -- 尝试获取自身已加载过的*Class*。 -- 尝试加载自身持有*URL*的*Class*,并将其缓存。 -- 无法从自身获取*Class*时,再调用父类原生的加载方法。 - -### 插件配置系统 - -**插件配置系统**是[**统一配置系统**](#统一配置系统)的特例,主要用于读取插件配置文件`config.yaml`,因此遵循[yaml格式加载策略](#yaml策略详解)的规则,这里不做赘述。 - -更多**插件配置系统**相关内容,可以参见[插件代码开发手册的插件配置一节](../dev-guide/dev_plugin_code-zh.md#插件配置)。 - -### 插件服务系统 - -**插件服务系统**是[**核心服务系统**](#核心服务系统)的特例,主要用于加载插件服务`PluginService`,因此他遵循**核心服务系统**的规则,这里不做赘述。 - -更多**插件服务系统**相关内容,可以参见[插件代码开发手册的插件服务一节](../dev-guide/dev_plugin_code-zh.md#插件服务)。 - -## 相关文档 - -|文档名称| -|:-| -|[入口模块介绍](entrance-zh.md)| -|[后端模块介绍](backend-zh.md)| - -[返回**Sermant**说明文档](../README-zh.md) diff --git a/docs/user-guide/agentcore.md b/docs/user-guide/agentcore.md deleted file mode 100644 index 0336b56c48..0000000000 --- a/docs/user-guide/agentcore.md +++ /dev/null @@ -1,503 +0,0 @@ -# Sermant-agentcore-core - -[简体中文](agentcore-zh.md) | [English](agentcore.md) - -This document focuses on [**sermant-agentcore-core**](../../sermant-agentcore/sermant-agentcore-core), which provides important kernels for handling bytecode enhancements, unified configuration, core services, plugin management, etc. - -- [Version of Agentcore-core](#Version-of-Sermant-agentcore-core) -- [Directory Structure](#Directory-Structure) -- [Bytecode Enhancement](#Bytecode-Enhancement) -- [Unified Configuration System](#Unified-Configuration-System) - - [Unified Configuration Management Class](#Unified-Configuration-Management-Class) - - [Unified Configuration Classes](#Unified-Configuration-Classes) - - [Detailed Description for Properties Strategy](#Detailed-Description-for-Properties-Strategy) - - [Detailed Description for Yaml Strategy](#Detailed-Description-for-Yaml-Strategy) - - [Plugin Setup Configuration](#Plugin-Setup-Configuration) -- [Core Service System](#Core-Service-System) - - [Core Service Management Class](#Core-Service-Management-Class) - - [Core Service Class](#Core-Service-Class) -- [Plugin Management System](#Plugin-Management-System) - - [Plugin Management Class](#Plugin-Management-Class) - - [Plugin Classloader](#Plugin-Classloader) - - [Plugin Configuration System](#Plugin-Configuration-System) - - [Plugin Service System](#Plugin-Service-System) -- [Related Documents](#Related-Documents) - -This article is just a brief introduction to [**sermant-agentcore-core**](../../sermant-agentcore/sermant-agentcore-core) in the meaning of each directory. If the developers want a more detailed understanding of the code's service logic, please move to the related directory or class. - -## Version of Sermant-agentcore-core - -The package version of sermant-agentcore-core (also called core package version) is an intrinsic property of the package, so we encapsulate the version definition in the `manifest` file as meta-information for the JAR package. Core package Version information is encapsulated in the `sermant-version` parameter of the`manifest` file, which defaults to `project.version`. In the code, you can get the core package version by: -```java -String version = BootArgsIndexer.getCoreVersion(); -``` - -If you need to change the core package version, you can change the value of `project.version` directly. - -## Directory Structure - -[**Sermant-agentcore-core**](../../sermant-agentcore/sermant-agentcore-core) contains the following directories: - -- `agent`, contains the deprecated code related to bytecode enhancement. -- `common`, contains the common code. -- `config`, contains the code related to [Unified Configuration System](#Unified-Configuration-System). -- `exception`, contains custom exceptions. -- `plugin`, contains the code related to [Plugin Management System](#Plugin-Management-System) and [Bytecode Enhancement](#Bytecode-Enhancement). -- `service`, contains the code related to [Core Service System](#Core-Service-System). -- `util`, contains the code of common utility classes. -- `AgentCoreEntrance`, is the entrance of [**Sermant-agentcore-core**](../../sermant-agentcore/sermant-agentcore-core),which calls the `run` method and transfers **startup parameters** and *Instrumentation* object. - -The following resources are also included in [**Sermant-agentcore-core**](../../sermant-agentcore/sermant-agentcore-core): - -- `META-INF/services`, *SPI* configuration file directory. - - `com.huaweicloud.sermant.core.config.common.BaseConfig`, declares unified configuration classes. - - `com.huaweicloud.sermant.core.config.strategy.LoadConfigStrategy`, declares the configration loading policy. - - `com.huaweicloud.sermant.core.service.BaseService`, declares implementations of core service. - -## Bytecode Enhancement - -The **Bytecode Enhancement** code for **Sermant** could be found in [agent](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent). - -**Sermant** implements bytecode enhancements based on the `Byte-Buddy` framework. It mainly utilizes [**byte-buddy delegate**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/transformer/AdviceTransformer.java) to enhance classes. For the scene of native class enhancement, [**Advice template classes**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/template) with [**byte-buddy advice**](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/transformer/BootstrapTransformer.java) technology play a role. - -The main content of `plugin/agent` directory show as following items: - -- `declarer`, contains **enhancement definition interfaces** is something that plugin developers need to focus on. -- `interceptor`, contains the **interceptor interfaces**, which plugin developers need to focus on. -- `matcher`, contains the **matchers of enhanced classes**, which plugin developers need to focus on. -- `template`, contains the **Advice template class**. -- `transformer`, contains the **Bytecode Transformer**. -- `BufferedAgentBuilder`, entrance of bytecode enhancement. - -### Enhancement Definition - -When coding **enhancement definitions**, plugin developers should implement `getClassMatcher` and `getInterceptDeclarers` of [PluginDeclarer](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/agent/declarer/PluginDeclarer.java) , as detailed in the [Plugin Code Development Guide](../dev-guide/dev_plugin_code.md#Enhancement Definition). - - Don't forget to add the *SPI* configuration file for `PluginDeclarer`. - -### Interceptor - -When coding an **interceptor**, developers just need to implement `interceptor` of [interceptor](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/agent/interceptor) directory - -For details, refer to [Plugin Code Development Guide](../dev-guide/dev_plugin_code.md#Interceptor). - -## Unified Configuration System - -The **Unified Configuration System** for **Sermant** can be found in [config](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config) directory. - -`config` contains following contents: - -- `common`,contains common code. - - `BaseConfig`, common interface of **Unified Configuration Classes** . - - `ConfigFieldKey`,used for setting alias of fields for **Unified Configuration Classes**. - - `ConfigTypeKey`, used for setting alias for **Unified Configuration Classes**. -- `strategy`, contains the code of configuration loading strategy. - - `LoadConfigStrategy`, interface of the configuration loading strategy. - - `LoadPropertiesStrategy`, strategy that used to load the `properties` format configuration file, which is mainly applied to load the Unified configuration file `config.properties`. - - `LoadYamlStrategy`,, strategy that used to load the `yaml` format configuration file, which is mainly applied to load the plugin setup configuration and plugin configuration, detailed in [Plugin Configuration System](#Plugin-Configuration-System). -- `utils`,contains utility classes used by the Unified Configuration System. -- `ConfigManager`,Unified Configuration Management Class, which provides methods for loading and fetching unified configuration. - -### Unified Configuration Management Class - -In `ConfigManager`, which is called Unified Configuration Management Class, developers can get the instance of **Unified Configuration Classes** via the `getConfig` method: - -```java -ConfigExample config = ConfigManager.getConfig(ConfigExample.class); -``` - -### Unified Configuration Classes - -**Unified Configuration System** is a management system that loads **static configuration** as **Java Pojo**. Therefore, an **Unified Configuration Class** must be a **Java Pojo** that implement [BaseConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/BaseConfig.java) interface. The exact requirements for these **Unified Configuration Classes** are dictated by `LoadPropertiesStrategy`, as described in the [Detailed Description for Properties Strategy](#Detailed-Description-for-Properties-Strategy). As for plugin-related [plugin configuration](#Plugin-Configuration-System), this is related to the requirements of `LoadYamlStrategy`.See details in [Detailed Description for Yaml Strategy](#Detailed-Description-for-Yaml-Strategy). - -An **Unified Configuration Class** is a **Java Pojo**, whose `getter`and `setter` methods can be directly generated using Lombok's `Data`, `getter`, and `setter` annotations. - -Note that after coding the **Unified Configuration Class**, don't forget to add SPI configuration file of [BaseConfig](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/config/common/BaseConfig.java) interface: - -- Add `META-INF/services` folder under `resources` -- add configuration file `com.huaweicloud.sermant.core.config.common.BaseConfig` under `META-INF/services`. -- In the above file, type all the **Unified Configuration Classes** in the plugin package and split them with **LF**. - -### Detailed Description for Properties Strategy - -The `LoadPropertiesStrategy` is used to load configuration files in the *properties* format, which is now mainly used to load the unified configuration file `config.properties`. - -The idea of `LoadPropertiesStrategy` could be simply described as: take the full qualified class name or alias of the **Unified Configuration Class** as the prefix and the property name or alias of the **Unified Configuration Class** as the suffix, and concatenate into the key in the **properties** format, then convert to the type of the corresponding property and assign the value after getting the corresponding value. - -Suppose there is a following **Unified Configuration Class**: - -```java -package com.huawei.example; -public class ConfigExample implements BaseConfig { - private String string; - private int intField; - // getter and setter -} -``` - -The corresponding configuration might look like this: - -```properties -# formant: full-qualified-class-name.propertyName=propertyValue -com.huawei.example.ConfigExample.string=value -com.huawei.example.ConfigExample.intField=123456 -``` - -#### Property Type - -The property types that `LoadPropertiesStrategy`supports includes: - -- Primitive and wrapper types for Boolean and numeric classes -- String -- Enum -- Array that consist of the above types -- *List* that consist of the first three types -- *Map* that consist of the first three types - -There are two ways to config `array` and `List`, one is to split the string with `,`: -```properties -# Array -com.huawei.example.ConfigExample.stringArr=value1,value2,value3 -# List -com.huawei.example.ConfigExample.intList=100,200,300 -``` - -Another way is to use index: - -```properties -# Array -com.huawei.example.ConfigExample.stringArr[0]=value1 -com.huawei.example.ConfigExample.stringArr[1]=value2 -com.huawei.example.ConfigExample.stringArr[2]=value3 -# List -com.huawei.example.ConfigExample.intList[0]=100 -com.huawei.example.ConfigExample.intList[1]=200 -com.huawei.example.ConfigExample.intList[2]=300 -``` - -There are two ways to config `Map`, one is to split the key/value pairs with `,` and split the key and value with `':'` : - -```properties -# Map -com.huawei.example.ConfigExample.string2IntMap=key1:value1,key2:value2,key3:value3 -``` - -Another way is to add the key at the end of propertyName: - -```properties -# Map -com.huawei.example.ConfigExample.string2IntMap.key1=value1 -com.huawei.example.ConfigExample.string2IntMap.key2=value2 -com.huawei.example.ConfigExample.string2IntMap.key3=value3 -``` - -Note that `LoadPropertiesStrategy` does not support complex type properties. - -#### Alias - -`LoadPropertiesStrategy` supports setting alias for full qualified class name and property names using the `ConfigTypeKey` annotation and the `ConfigFieldKey` annotation. Assume the above `ConfigExample` class is modified as follows: - -```java -@ConfigTypeKey("config.example") -public class ConfigExample implements BaseConfig { - @ConfigFieldKey("stringField") - private String string; - private int intField; - // getter and setter -} -``` - -Then the configuration file should be like this: -```properties -# alias for full-qualified-class-name.property=propertyValue -config.example.stringField=value -config.example.intField=123456 -``` - -#### Value of Introspection - -The property values in `LoadPropertiesStrategy'`support introspection. `${}` can be used to map the current configuration, system variables, startup parameters and other elements. For example, the `ConfigExample` configuration can be set to: - -```properties -# appName linked to startup parameters ,user.home linked to system variable,com.huawei.example.ConfigExample.intField linked to current configuration -com.huawei.example.ConfigExample.string=value, ${appName:test}, ${user.home}, ${com.huawei.example.ConfigExample.intField} -com.huawei.example.ConfigExample.intField=123456 -``` - -Take `${appName:test}` for example ,`appName` is the index key for introspection and `test` is the default value. The retrieval priority for introspection is as follows: - -- Startup parameters -- Current configuration file(`config.properties`) -- Environment variable -- System variable -- Default value(content at the right of `':'`) - -The contents contained in the startup parameters can be found in [Introduction to Entrance Module](entrance.md). - -#### Special Key/Value pairs - -`LoadPropertiesStrategy` allows you to use the key/value pairs in the startup parameter first. Otherwise it will use the config from the configuration file if the startup parameter does not exist. - -Suppose there is a configuration class like this: -```java -@ConfigTypeKey("env") -public class ConfigExample implements BaseConfig { - private String tag; - private String secret; - // getter and setter - -``` - -The `tag` and `secret` properties take precedence over the `env.tag` and `env.secret` values in the `bootstrap.config`. - -### Detailed Description for Yaml Strategy - -The `LoadYamlStrategy` is used to load configuration files in the *YAML* format, which is currently mainly used to load plugin setup configuration `plugins.yaml` and plugin configuration `config.yaml`. Since plugin setup configuration is relatively simple, we will only cover the **Plugin Configuration Class**. - -The **Plugin Configuration Class** is a **Java Pojo** just like the **Unified Configuration Class**, except that the latter implements the `BaseConfig` interface, while the former implements the `PluginConfig` interface. Refer to [Plugin Code Development Guide](../dev-guide/dev_plugin_code.md#Plugin-Configuration) for more information. We will take the `PluginConfig` interface as an example. - -Suppose there is a following **Plugin Configuration Class** : -```java -package com.huawei.example; -public class ConfigExample implements PluginConfig { - private String string; - private int intField; - // getter and setter -} -``` - -The corresponding configuration might look like this: - -```yaml -com.huawei.example.ConfigExample: - string: value - intField: 123456 -``` - -#### Property Type - -The property types that `LoadYamlStrategy`supports includes: - -- Primitive and wrapper types for Boolean and numeric classes -- String -- Enum -- Complex Object -- Array that consist of the above types -- *List* that consist of the first four types -- *Map* that consist of the first four types - -#### Alias - -`LoadYamlStrategy` supports setting alias for full qualified class name and property names using the `ConfigTypeKey` annotation and the `ConfigFieldKey` annotation. Assume the above `ConfigExample` class is modified as follows: - -```java -@ConfigTypeKey("config.example") -public class ConfigExample implements PluginConfig { - @ConfigFieldKey("stringField") - private String string; - private int intField; - // getter and setter -} -``` - -Then the configuration file should be like this:: -```yaml -config.example: - stringField: value - intField: 123456 -``` - -Note that fixing property names by `ConfigFieldKey` is not supported for complex objects involved in arrays, lists, and maps. In other words, `ConfigFieldKey` only applies to properties of the **Plugin Configuration Class** and its complex object type properties. - -#### Value of Introspection - -The property values in `LoadYamlStrategy'`support introspection. `${}` can be used to map the current configuration, system variables, startup parameters and other elements. For example, the `ConfigExample` configuration can be set to: - -```yaml -com.huawei.example.ConfigExample: - string: value, ${appName:test}, ${user.home}, ${intField} - intField: 123456 -``` - -Take `${appName:test}` for example ,`appName` is the index key for introspection and `test` is the default value. The retrieval priority for introspection is as follows: - -- Startup parameters -- Current configuration file -- Environment variable -- System variable -- Default value(content at the right of `':'`) - -Note that `LoadPropertiesStrategy` can map to the entire configuration file, and `LoadYamlStrategy` can only map to the current `Map` or **complex object** due to the configuration format. - -while mapping the **public properties** of the current collection (**complex objects**) and the **public properties** are aliasing with `ConfigFieldKey`, the correct mapping will depend on the order in which the properties are defined, like **Plugin Configuration Classes** below: -```java -@ConfigTypeKey("config.example") -public class ConfigExample implements PluginConfig { - private String field1; - @ConfigFieldKey("stringField") - private String field2; - private String field3; - // getter and setter -} -``` - -If `field1` and `field3` need to use `field2`, the corresponding configuration would look like this: -```yaml -config.example: - field1: value1, ${stringField} - stringField: value2 - field3: value3, ${field2} -``` - -Based on the above, it is recommended that developers do not set aliases for **public properties**. If you really need an alias, it is recommended to place these **public properties** at the beginning or end of the **Plugin Configuration Class**. - -The contents contained in the startup parameters can be found in [Introduction to Entrance Module](entrance.md#Startup-Parameters). - -#### Special Key/Value pairs - -`LoadYamlStrategy` does not support assigning properties to the **Plugin Configuration Class** using key/value pairs in the startup parameter. - -### Plugin Setup Configuration - -**Plugin Setup Configuration** is `plugins.yaml`. There are three such files in [**sermant-agentcore-core**](../../sermant-agentcore/sermant-agentcore-core): - -- [plugins.yaml](../../sermant-agentcore/sermant-agentcore-config/config/plugins.yaml): **Plugin Setup Configuration** for the default build scenario, without the example project. -- [all/plugins.yaml](../../sermant-agentcore/sermant-agentcore-config/config/all/plugins.yaml): **Plugin Setup Configuration ** when executing the -Pall to package, with extra example project than `agent`. -- [example/plugins.yaml](../../sermant-agentcore/sermant-agentcore-config/config/example/plugins.yaml): **Plugin Setup Configuration** when executing the -Pexample to package, including only the example project. - -In `plugins.yaml`, the plugins is configured to be loaded when **Sermant** starts, like this: - -```yaml -plugins: - - plugin1 - - plugin2 - - plugin3 -``` - -These configured plugins correspond to the contents of the `pluginPackage` directory. - -In addition, developers can use `profile` to define the plugins that need to be loaded for different scenarios. Such as: - -```yaml -profiles: - scene1: - - plugin1 - - plugin2 - scene2: - - plugin3 - - plugin4 - scene3: - - plugin5 - - plugin6 -profile: scene1, scene2 -``` - -In `Profiles` you can customize the plugin loading configuration for different scenarios, and in' profiles' you can configure which scenarios will take effect after the application launches. - -## Core Service System - -The **Core Service System** code for **Sermant** could be found in [service](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service). - -`service`includes: - -- [BaseService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/BaseService.java): [**Core Service Class**](#Core-Service-Class) -- [ServiceManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/ServiceManager.java): [**Core Service Management Class**](#Core-Service-Management-Class) -- Core service implementation directory - -### Core Service Management Class - -In the **Core Service Management Class** `ServiceManager`, developers can obtain the **core service class** instance via the `getService` method: - -```java -ServiceExample service = ServiceManager.getService(ServiceExample.class); -``` - -### Core Service Class - -The **Core Service System** is a system that loads and manages the services that implement the [BaseService](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/service/BaseService.java) **Core Service Class**. Its core is the implementation of **Core Service Class**.: - -Suppose there is a service called example and write an interface for this service: - -```java -public interface ServiceExample extends BaseService { - void foo(); -} -``` - -This defines the `Example` service interface with the `foo` method, which might be implemented as follows: -```java -public class ServiceExampleImpl implements ServiceExample { - @Override - public void start() { - // initialize - } - - @Override - public void stop() { - // shut down - } - - @Override - public void foo() { - // do something - } -} -``` - -Next, add `ServiceExampleImpl` to the *SPI* configuration of `BaseService`: - -- Add `META-INF/services` folder under `resources`. -- add configuration file `com.huaweicloud.sermant.core.service.BaseService` under `META-INF/services`. -- In the above file, type all the **Core Service Classes**(`ServiceExampleImpl`) in the plugin package and split them with **LF**. - -In this way you can fetch the instances of **Core Service Classes** via the `getService` method of the `ServiceManager`. - -## Plugin Management System - -The **Plugin Management system** code for **Sermant** can be found in [plugin](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin). - -`plugin` includes: - -- [classloader/PluginClassLoader](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/classloader/PluginClassLoader.java), describes in [Plugin Classloader](#Plugin-Classloader). -- [config](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/config), contains the code related to [Plugin Configuration System](#Plugin-Configuration-System). -- [service](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/service), contains the code related to [Plugin Service System](#Plugin-Service-System). -- [PluginManager](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/PluginManager.java),describes in [Plugin Management Class](#Plugin-Management-Class). - -### Plugin Management Class - -In the **Plugin Management Class**, we mainly traverse the plugin directories configured in the plugin configuration file `plugins.yaml`. For each plugin directory: - -- Load all its **plugin packages** into the system class loader `AppClassLoader`. -- Custom [Plugin Classloader](#Plugin-Classloader) loads all plugin packages. -- Load all related [Plugin Configuration](#Plugin-Configuration-System). -- Load all related [Plugin Service](#Plugin-Service-System). - -### Plugin Classloader - -**Plugin Classloader** is exactly `PluginClassLoader`. `PluginClassLoader` is a special `URLClassLoader`. It will hold all the *URL* of plugin service packages for a single feature. `PluginClassLoader` breaks the parent delegation mechanism. When loading a *Class*, it preferentially uses its own *Class*, and then calls the native loading method of its parent class if it can't find: - -- Try to get the *Class* that it has already loaded. -- Try to load the *Class* that itself holds the *URL* and cache it. -- When it can't get the *Class* from itself, it will call the native loading method of the parent class. - -### Plugin Configuration System - -**Plugin Configuration System** is a special case of [**Unified Configuration System**](#Unified-Configuration-System). It is mainly used to read the plugin configuration file `config.yaml`, so it follows the rules of the [YAML format loading strategy](#Detailed-Description-for-Yaml-Strategy). - -For more information on the **Plugin Configuration System**, refer to the [Plugin Code Development Guide](../dev-guide/dev_plugin_code.md#Plugin-Configuration). - -### Plugin Service System - -**Plugin Service System** is a special case of [**Core Service System**](#Core-Service-System), which is mainly used to load the PluginService `PluginService`. So it follows the rules of **Core Service System**. - -For more information on the **Plugin Service System**, refer to the [Plugin Code Development Guide](../dev-guide/dev_plugin_code.md#Plugin-Service). - -## Related Documents - -|Documents| -|:-| -|[Introduction to Entrance Module](entrance.md)| -|[Introduction to Backend Module](backend.md)| - -[Back to README of **Sermant** ](../README.md). - diff --git a/docs/user-guide/backend-zh.md b/docs/user-guide/backend-zh.md deleted file mode 100644 index 899dd91aa5..0000000000 --- a/docs/user-guide/backend-zh.md +++ /dev/null @@ -1,59 +0,0 @@ -# 后端模块介绍 - -[简体中文](backend-zh.md) | [English](backend.md) - -本文档主要介绍[**Sermant后端模块**](../../sermant-backend),其主要职能就是将`核心功能`运行过程中产生的消息传递给Kafka,起到将短连接转化为长连接的作用。 - -[定位]: - -- Sermant数据处理后端模块和前端信息展示模块 - -[能力]: -- 接受框架和插件的数据写入kafka -- 提供前端界面展示框架和插件的心跳信息 - -[使用方式]: -- backend运行环境依赖kafka, 默认kafka的配置如下,若kafka环境配置不同,需要修改[kafka环境配置](../../sermant-backend/src/main/resources/application.properties) - ```properties - spring.kafka.bootstrap-servers=127.0.0.1:9092 - ``` -- 框架运行依赖backend,backend的默认配置如下,若宿主应用和backend未运行在统一机器,需要修改[backend配置](../../sermant-agentcore/sermant-agentcore-premain/src/main/resources/config/bootstrap.properties) - ```properties - backendIp=127.0.0.1 - backendPort=6888 - ``` -- 运行backend模块之后,访问 `http://127.0.0.1:8900`查看框架和插件启动信息 - ![启动信息](../../docs/binary-docs/backend_sermant_info.png) -- backend默认后端监听端口为8900,若出现端口被占用或需要设置为其他端口,请修改[backend端口](../../sermant-backend/src/main/resources/application.properties) - ```properties - server.port=8900 - ``` -- backend前端采用vue框架开发,目前前端仅提供简单的展示框架运行状态信息,若前端不满足要求,请修改[backend前端](../../sermant-backend/src/main/webapp) -- backend要求框架和插件产生的数据存入不同的topic,若以下现有的topic配置不满足要求,则需要按照同样的格式添加topic配置,添加topic请修改[topic配置](../../sermant-backend/src/main/resources/application.properties) - ```properties - datatype.topic.mapping.0=topic-heartbeat - datatype.topic.mapping.1=topic-log - datatype.topic.mapping.2=topic-flowcontrol - datatype.topic.mapping.3=topic-flowrecord - datatype.topic.mapping.4=topic-server-monitor - datatype.topic.mapping.5=topic-open-jdk-jvm-monitor - datatype.topic.mapping.6=topic-ibm-jvm-monitor - datatype.topic.mapping.7=topic-agent-registration - datatype.topic.mapping.8=topic-agent-monitor - datatype.topic.mapping.9=topic-agent-span-event - datatype.topic.mapping.10=topic-druid-monitor - datatype.topic.mapping.11=topic-flowcontrol-metric - ``` -- backend不强依赖kafka服务,配置中默认心跳数据写入缓存中,如需要将数据写入kafka,则更改[backend配置文件](../../sermant-backend/src/main/resources/application.properties)中以下配置为`false`即可。 - ```properties - heartbeat.cache=true - ``` - -## 相关文档 - -|文档名称| -|:-| -|[核心模块介绍](agentcore-zh.md)| -|[入口模块介绍](entrance-zh.md)| - -[返回**Sermant**说明文档](../README-zh.md) diff --git a/docs/user-guide/backend.md b/docs/user-guide/backend.md deleted file mode 100644 index 3f92bbcc36..0000000000 --- a/docs/user-guide/backend.md +++ /dev/null @@ -1,61 +0,0 @@ -# Sermant-backend Module - -[简体中文](backend-zh.md) | [English](backend.md) - -This document focuses on the [**Sermant-backend**](../../sermant-backend). Its main function is to send messages generated during the `core function` execution to Kafka, which plays the role of turning short connections into long connections. - -**Positioning**: - -- Data processing backend module and frontend information display module for Sermant. - -**Functionality**: - -- Receive data from framework and plugin and write to Kafka. -- Provide frontend to display heartbeat information of framework and plugin. - -**How to Use**: - -- The runtime environment of backend requires Kafka. The default configuration of Kafka is as follows. If the environment configuration of Kafka is different, you need to modify the [kafka configuration](../../sermant-backend/src/main/resources/application.properties) - ```properties - spring.kafka.bootstrap-servers=127.0.0.1:9092 - ``` -- The framework depends on backend to run. The default configuration of backend is as follows. If the host application and backend are not running on the same machine, you need to modify the [backend configuration](../../sermant-agentcore/sermant-agentcore-config/config/config.properties) - ```properties - backendIp=127.0.0.1 - backendPort=6888 - ``` -- After running the backend module, check startup information of framework and plugin at http://127.0.0.1:8900 - ![启动信息](../../docs/binary-docs/backend_sermant_info.png) -- The default listening port of backend is 8900. If the port is occupied or needs to be set to another port, please modify [port of backend](../../sermant-backend/src/main/resources/application.properties) - ```properties - server.port=8900 - ``` -- The frontend of Backend frontend is developed by Vue framework. At present, the frontend only provides simple information to show the running status of the framework. If the frontend does not meet your requirements, please modify the [frontend](../../sermant-backend/src/main/webapp). -- Backend requires that the data generated by the framework and the plugin are stored in different topics of Kafka. If the following existing topic configuration does not meet the requirements, developers need to add topic configuration in the same format.To add topic, please modify [topic configuration](../../sermant-backend/src/main/resources/application.properties). - ```properties - datatype.topic.mapping.0=topic-heartbeat - datatype.topic.mapping.1=topic-log - datatype.topic.mapping.2=topic-flowcontrol - datatype.topic.mapping.3=topic-flowrecord - datatype.topic.mapping.4=topic-server-monitor - datatype.topic.mapping.5=topic-open-jdk-jvm-monitor - datatype.topic.mapping.6=topic-ibm-jvm-monitor - datatype.topic.mapping.7=topic-agent-registration - datatype.topic.mapping.8=topic-agent-monitor - datatype.topic.mapping.9=topic-agent-span-event - datatype.topic.mapping.10=topic-druid-monitor - datatype.topic.mapping.11=topic-flowcontrol-metric - ``` -- Backend does not strongly rely on Kafka service, the default configuration of heartbeat data is to write to the cache, if you need to write data to Kafka, just change the following configuration of [backend configuration file](../../sermant-backend/src/main/resources/application.properties) to `false`. - ```properties - heartbeat.cache=true - ``` - -## Related Documents - -|Documents| -|:-| -|[Introduction to Sermant-agentcore-core](agentcore.md)| -|[Introduction to Entrance Module](entrance.md)| - -[[Back to README of **Sermant** ](../README.md)] diff --git a/docs/user-guide/dynamic-config/document-zh.md b/docs/user-guide/dynamic-config/document-zh.md deleted file mode 100644 index d0110a711b..0000000000 --- a/docs/user-guide/dynamic-config/document-zh.md +++ /dev/null @@ -1,222 +0,0 @@ -## 动态配置插件介绍 - -[简体中文](document-zh.md) | [English](document.md) - -本文档主要介绍[动态配置插件](../../../sermant-plugins/sermant-dynamic-config)以及该插件的使用方法 - -## 功能 - -该插件基于Sermant配置中心能力实现动态配置,可在运行时将配置刷新到宿主应用,其优先级将高于环境变量配置。 - -当前插件插件支持[SpringCloud](https://github.com/spring-cloud)应用,需配合注解`@Value, @ConfigurationProperties以及@RefreshScope`使用 - -## 使用说明 - -### 版本要求 - -**SpringCloud:** `Edgware.SR2`及以上的版本 - -### 环境准备 - -(1)准备配置中心环境(Zookeeper/Kie) - -(2)打包编译Sermant,可参考[Sermant源码编译](../../QuickStart-zh.md#源码编译) - -### 配置插件 - -**(1)修改配置中心(可选)** - -修改配置文件`${javaagent路径}/config/config.properties`, 修改配置中心类型与地址,如下位置: - -```properties -# 配置中心地址, 根据配置中心地址配置 -dynamic.config.server_address=127.0.0.1:2181 -# 配置中心类型, 支持KIE与ZOOKEEPER -dynamic.config.dynamic_config_type=ZOOKEEPER -``` - -**(2)配置动态配置插件** - -修改配置文件`${javaagent路径}/pluginPackage/dynamic-config/config/config.yaml`, 配置如下: - -```yaml -dynamic.config.plugin: - enableCseAdapter: true # 是否开启适配CSE - enableDynamicConfig: true # 是否开启动态配置插件 - enableOriginConfigCenter: false # 是否开启原配置中心, 默认关闭 - #sourceKeys: sourceKey #针对指定键生效 -``` - -配置说明: - -| 配置项 | 配置说明 | -| ------------------------- | ------------------------------------------------------------ | -| enableCseAdapter | 当配置为true时, 会根据ServiceMeta指定的应用配置,服务配置以及自定义标签配置三种类型进行配置订阅;当为false时,只会根据服务名进行订阅,即对键为`service`, 值为"宿主服务名(即spring.application.name获取)" | -| enableDynamicConfig | 动态配置开关,仅当配置为true时,动态配置才会生效 | -| enableOriginConfigCenter | 是否开启原配置中心, 默认不开启。当前仅支持Zookeeper与Nacos配置中心(基于SpringCloud Config实现) | -| sourceKeys | 当需要指定的配置键生效时,可配置该值,例如只是想读取application.yaml,否则默认会读取所有的配置;多个键使用`,`隔开。 | - -### 发布配置 - -发布配置有以下两种方式: - -(1)通过Sermant后台服务发布配置 - -(2)直接通过配置中心发布配置 - -下面将分别介绍这两种发布方式操作流程 - -#### 通过Sermant后台服务发布配置 - -1、首先需编译启动`backend`模块 - -2、调用`backend`接口`/publishConfig`发布配置, 该接口参数如下: - -| 配置参数 | 说明 | -| -------- | ------------------------------------------------------ | -| key | 配置键 | -| group | 配置的标签组 | -| content | 配置内容,即具体的规则配置,配置插件仅支持**yaml**格式 | - -动态配置主要基于`group`进行匹配配置订阅,该标签组由多个键值对组成,根据适配开关配置`enableCseAdapter`的不同,`group`的值将会有所区别,如下: - -(1)若关闭适配,即`enableCseAdapter: false` - -​ 此时注册插件将根据宿主应用的服务名进行订阅, 即配置的`spring.applicaton.name`, 若此时配置的服务名为`DynamicConfigDemo`, 那么对应的`group`的值为`service=DynamicConfigDemo`, 其中键service是固定的, 值DynamicConfigDemo由宿主服务名决定 - -(2)若开启适配, 即`enableCseAdapter: true` - -​ 此时将根据**应用配置**,**服务配置**以及**自定义配置**三项数据进行配置**同时**订阅, 而这三类配置可参考`${javaagent路径}/pluginPackage/config.properties`, 相关配置如下: - -```properties -# 服务app名称 -service.meta.application=default -# 服务版本 -service.meta.version=1.0.0 -# serviceComb 命名空间 -service.meta.project=default -# 环境 -service.meta.environment=development -# 自定义标签,按需配置,用于后续的配置订阅 -service.meta.customLabel=public -service.meta.customLabelValue=default -``` -- 应用配置:由`service.meta.application`与`service.meta.environment`组成, 对应的`group`为`app=default&environment=development` -- 服务配置:由`service.meta.application`、`service.meta.environment`以及服务名组成,此处服务即`spring.application.name`, 对应的`group`为`app=default&environment=development&service=DynamicConfigDemo` -- 自定义配置:由`service.meta.customLabel`与`service.meta.customLabelValue`组成, 对应的`group`为`public=default` - -**以上为`group`的配置介绍**,下面说明`content`配置,当前动态配置仅支持yaml格式, 例如配置如下内容: - -```yaml -server: - port: 8004 -sermant: sermant -spring: - application: - name: DynamicConfigDemo - cloud: - zookeeper: - enabled: true - -``` - -针对`key`配置无特殊要求,但需要注意的是,若您配置了`sourceKeys`配置项,仅当`key`与`sourceKeys`匹配时才会生效 - -#### 通过配置中心发布配置 - -不同的配置中心配置方式都不同, 以下分别说明Zookeeper与Kie配置中心的配置方式 - -##### Kie配置中心 - -KIE发布配置需通过其自身API发布,其接口为`http://ip:30110/v1/default/kie/kv`, 配置内容如下: - -```json -{ - "key": "test", - "value": "limitRefreshPeriod: \"1000\"\nname: hello\nrate: \"2\"\n", - "labels": { - "app": "discovery", - "environment": "testing" - }, - "status": "enabled" -} -``` - -以上配置key与labels分别与[通过Sermant后台服务发布配置](#通过Sermant后台服务发布配置)的key与group相对应,若对KIE请求不了解,可参考[api文档](https://github.com/apache/servicecomb-kie/tree/master/docs) - -##### Zookeeper配置中心 - -Zookeeper配置发布则需基于命令行配置,即`zkServer`, 其路径由[通过Sermant后台服务发布配置](#通过Sermant后台服务发布配置)的key与group组成, 即/group/key, 其值即为content。例如发布一个配置: - -当前服务名为`DynamicConfigDemo`,对应的**group**为`service=DynamicConfigDemo`, 指定的**key**为`test`, **content**为`sermant: sermant`, 那么发布的命令为 - -```shell -# create /group/key content -create /service=DynamicConfigDemo/test "sermant: sermant" -``` - - - -### 部署应用 - -准备好demo应用,例如xxx.jar, 参考如下启动命令如下: - -```shell -#根据配置enableCseAdapter按需调整 -java -javaagent:${agent路径}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=DynamicConfigDemo -Dspring.application.name=DynamicConfigDemo -Ddynamic.config.plugin.enableDynamicConfig=true -Ddynamic.config.plugin.enableCseAdapter=false -jar xxx.jar -``` - -以下示范`@Value`注解使用,`@ConfigurationProperties`注解同理 - -```java -/** - * @Value配置示范 - * 需配合注解@RefreshScope - */ -@Component -@RefreshScope -public class ValueConfig { - @Value("${sermant}") - private Object sermant; - - @Value("${server.port}") - private int port; - - @Value("${spring.application.name}") - private String name; - - @Override - public String toString() { - return "ValueConfig{" + - "test=" + test + - ", dubbo=" + dubbo + - ", sermant=" + sermant + - ", port=" + port + - ", name='" + name + '\'' + - '}'; - } - - public Object getSermant() { - return sermant; - } - - public Object getDubbo() { - return dubbo; - } - - public Object getTest() { - return test; - } -} - -``` - - - -### 验证 - -尝试发布更新配置,再次访问demo应用,观察配置是否刷新,控制台是否有输出`Refresh Keys`日志。 - - - -[返回**Sermant**说明文档](../../README-zh.md) \ No newline at end of file diff --git a/docs/user-guide/dynamic-config/document.md b/docs/user-guide/dynamic-config/document.md deleted file mode 100644 index 1f8d12d2eb..0000000000 --- a/docs/user-guide/dynamic-config/document.md +++ /dev/null @@ -1,224 +0,0 @@ -## Dynamic Configuration - -[简体中文](document-zh.md) | [English](document.md) - -This document is used to introduce the usage of [dynamic configuration plugin](../../../sermant-plugins/sermant-dynamic-config) - -## Functions - -This plugin implements dynamic configuration based on the Sermant configuration center capability. During running, the configuration can be updated to the host application. The priority of the plugin is higher than that of the environment variable configuration. - -The current plugin supports SpringCloud applications and needs to be used together with the `@Value, @ConfigurationProperties, and @RefreshScope` annotations. - -## Usage - -### Version Required - -**SpringCloud:** `Edgware.SR2 `and later versions - -### Environment Preparation - -(1)Preparing the Configuration Center Environment (Zookeeper/Kie) - -(2)Compile the Sermant. For details, can referring [complie source code](../../QuickStart.md#Compile-Source-Code) - -### Configure Plugin - -**(1)Modify the config center(Optional)** - -Modify the `${javaagent path}/config/config.properties`, configuration file to change the configuration center type and address as follows: - -```properties -# IP address of the configuration center. Set this parameter based on the IP address of the configuration center. -dynamic.config.server_address=127.0.0.1:2181 -# Configuration center type. The options are KIE and ZOOKEEPER. -dynamic.config.dynamic_config_type=ZOOKEEPER -``` - -**(2)Configure Dynamic Configuratin plugin** - -Modify the `${javaagent path}/pluginPackage/dynamic-config/config/config.yaml`, configuration file as follows: - -```yaml -dynamic.config.plugin: - enableCseAdapter: true # Whether to enable CSE adaptation - enableDynamicConfig: true # Whether to enable the dynamic configuration plugin - enableOriginConfigCenter: false # Indicates whether to enable the original configuration center. By default, the configuration center is disabled. - #sourceKeys: sourceKeys # related the keys that can effect, default is null -``` - -Configuration description: - -| Configuration | Description | -| ------------------------- | ------------------------------------------------------------ | -| enableCseAdapter | If this parameter is set to true, subscription is performed based on the application configuration, service configuration, and customized tag configuration specified by ServiceMeta. If the value is false, subscription is performed only based on the service name. That is, the key is service and the value is "Host service name (obtained by spring.application.name)". | -| enableDynamicConfig | Indicates whether to enable dynamic configuration. The dynamic configuration takes effect only when this parameter is set to true. | -| enableOriginConfigCenter | Indicates whether to enable the original configuration center. This parameter is disabled by default. Currently, only ZooKeeper and Nacos configuration center (implemented based on SpringCloud Config) are supported. | -| sourceKeys | When the specified configuration key takes effect, you can set this parameter. For example, you only want to read the application.yaml file. Otherwise, all configurations are read by default. Use commas (,) to separate multiple keys. | - -### Publish Configuration - -You can publish configurations in either of the following ways: - -(1)Publish configurations through the Sermant Backend service - -(2)Release the configuration directly through the configuration center. - -The following describes the operation processes of the two publishing modes. - -#### Publish Configurations Through The Sermant Backend Service - -1、Compile and start the backend module. - -2、Invoke the backend interface `/publishConfig` to publish the configuration. The parameters of the interface are as follows: - -| Configuration | Description | -| ------------- | ------------------------------------------------------------ | -| key | configuration key | -| group | configuration group | -| content | Configuration content, that is, specific rule configuration. The configuration plugin supports only YAML format. | - -Dynamic configuration is performed based on a group. The tag group consists of multiple key-value pairs. The value of group varies with the adaptation switch enableCseAdapter, as shown in the following figure. - -(1)If the adaptation function is disabled(`enableCseAdapter: false`) - -​ In this case, the registration plugin performs subscription according to the service name of the host application, that is, the configured `spring.appplicaton.name`. If the configured service name is `DynamicConfigDemo`, the value of the corresponding `group` is `service=DynamicConfigDemo`, where the key service is fixed. The value DynamicConfigDemo is determined by the host service name. - -(2)If the adaptation function is enabled(`enableCseAdapter: true`) - -​ In this case, subscription is performed based on the **application configuration, service configuration, and customized configuration**. For details about the three types of configurations, see `${javaagent path}/pluginPackage/config.properties`, The related configurations are as follows: - -```properties -# application name -service.meta.application=default -# service version -service.meta.version=1.0.0 -# namespace just keep default -service.meta.project=default -# your environment, currently, development/testing/production are supported -service.meta.environment=development -# Customized tags, which are configured as required for subsequent configuration subscription. -service.meta.customLabel=public -service.meta.customLabelValue=default -``` -- **Application configuration**: consists of `service.meta.application` and `service.meta.environment`. The corresponding group is `app=default&environment=development`. -- **Service configuration**: consists of `service.meta.application`, `service.meta.environment`, and `service name. Here, the service is spring.application.name`, and the corresponding group is `app=default&environment=development&service=DynamicConfigDemo`. -- **Customized configuration**: consists of `service.meta.customLabel` and `service.meta.customLabelValue`. The corresponding group is `public=default`. - -The preceding describes the group configuration. The following describes the content configuration. Currently, the dynamic configuration supports only the YAML format. For example, the following content is configured: - -```yaml -server: - port: 8004 -sermant: sermant -spring: - application: - name: DynamicConfigDemo - cloud: - zookeeper: - enabled: true - -``` - -There is no special requirement for key configuration. Note that if you set the **sourceKeys** configuration item, the configuration item **takes effect only when the key matches the sourceKeys** configuration item. - -#### Publish Configurations by Config Center - -The configuration modes vary according to the config center. The following describes the configuration modes of the ZOOKEEPER and KIE config centers. - -##### KIE Config Center - -The KIE publish configuration needs to be released through its own API. The configuration content of the http://ip:30110/v1/default/kie/kv, interface is as follows: - -```json -{ - "key": "test", - "value": "limitRefreshPeriod: \"1000\"\nname: hello\nrate: \"2\"\n", - "labels": { - "app": "discovery", - "environment": "testing" - }, - "status": "enabled" -} -``` - -The preceding configuration keys and labels correspond to the keys and groups that are released [through the Sermant background service](#Publish-configurations-through-the-Sermant-Backend-service). If you are not familiar with KIE requests, see the [API document](https://github.com/apache/servicecomb-kie/tree/master/docs). - -##### ZOOKEEPER Config Center - -The ZOOKEEPER configuration publishment needs to be configured based on the command line, that is, zkServer. Its path consists of the key and group configured [through the Sermant background service](#Publish-configurations-through-the-Sermant-Backend-service) release, that is, /group/key, whose value is content. - -The following shows how to publish a configuration: - -If the current service name is **DynamicConfigDemo**, the corresponding **group is service=DynamicConfigDemo**, the specified **key is test**, and the content is **sermant: sermant**, the released command is as follows: - -```shell -# create /group/key content -create /service=DynamicConfigDemo/test "sermant: sermant" -``` - - - -### Deploy Application - -Prepare the demo application, for example, xxx.jar. Run the following command to start the application: - -```shell -#EnableCseAdapter based on the configuration -java -javaagent:${agent path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=DynamicConfigDemo -Dspring.application.name=DynamicConfigDemo -Ddynamic.config.plugin.enableDynamicConfig=true -Ddynamic.config.plugin.enableCseAdapter=false -jar xxx.jar -``` - -The @Value annotation is used as an example. The @ConfigurationProperties annotation is similar. - -```java -/** - * @Value example - * need use with @RefreshScope - */ -@Component -@RefreshScope -public class ValueConfig { - @Value("${sermant}") - private Object sermant; - - @Value("${server.port}") - private int port; - - @Value("${spring.application.name}") - private String name; - - @Override - public String toString() { - return "ValueConfig{" + - "test=" + test + - ", dubbo=" + dubbo + - ", sermant=" + sermant + - ", port=" + port + - ", name='" + name + '\'' + - '}'; - } - - public Object getSermant() { - return sermant; - } - - public Object getDubbo() { - return dubbo; - } - - public Object getTest() { - return test; - } -} - -``` - - - -### Verification - -Release the updated configuration, access the demo application again, and check whether the configuration is refreshed and whether `Refresh Keys` logs are generated on the console. - - - -[Back to README of **Sermant** ](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/entrance-zh.md b/docs/user-guide/entrance-zh.md deleted file mode 100644 index 8acde13787..0000000000 --- a/docs/user-guide/entrance-zh.md +++ /dev/null @@ -1,91 +0,0 @@ -# 入口模块介绍 - -[简体中文](entrance-zh.md) | [English](entrance.md) - -本文档主要介绍[**Sermant入口模块**](../../sermant-agentcore/sermant-agentcore-premain)。 - -## 组成部分 - -`source`文件夹下: - -- `common`目录,存放公共内容。 - - `BootArgsBuilder`类,用于加载启动配置。 - - `PathDeclarer`类,用于声明相关资源的路径。 -- `exception`目录,存放自定义异常。 -- `AgentPremain`类,为`JavaAgent`入口,详见[使用方式](#使用方式)。 - -`resources`文件夹下: - -- `config/bootstrap.properties`文件,为启动配置文件,将被[BootArgsBuilder](../../sermant-agentcore/sermant-agentcore-premain/src/main/java/com/huawei/sermant/premain/common/BootArgsBuilder.java)类加载出来,连同启动入参共同构成启动参数*Map*。 - -## 使用方式 - -**入口模块**打包输出*JavaAgent*入口包`sermant-agent.jar`,在执行*Java*命令时,可以添加如下参数带起**Sermant**: - -```shell --javaagent:sermant-agent.jar[=${options}] -``` - -其中`${options}`为启动入参,会作为`premain`方法的入参`agentArgs`传入。 - -```java -public static void premain(String agentArgs, Instrumentation inst); -``` - -参数`agentArgs`的格式要求形如`key1=value1,key1=value1[(,keyN=valueN)...]`,以`','`分割键值对,以`'='`分割键值,形成`Map`结构。 - -其中需要注意的是,`agentArgs`中必须包含一个`key`为`appName`的键值对,因此启动时添加的*Java*命令参数准确来说应该如下: - -```shell --javaagent:sermant-agent.jar=appName=${appName}[,${otherOptions}] -``` - -其中`${appName}`表示应用名称,`${otherOptions}`表示其他参数。 - -更多*JavaAgent*相关内容可以参见官方文档对[java.lang.instrument](https://docs.oracle.com/javase/8/docs/api/java/lang/instrument/package-summary.html)包的详解 - -## 功能解析 - -**入口模块**作为**Sermant**的入口,起到的是将程序带入**核心功能**的作用,入口类[AgentPremain](../../sermant-agentcore/sermant-agentcore-premain/src/main/java/com/huawei/sermant/premain/AgentPremain.java)所做的工作包括: - -- 防止**Sermant**被宿主多次带起(*JavaAgent*命令中添加了复数的**Sermant**入口包)。 -- 加载**核心功能**包,这里使用系统类加载器加载。 -- 将`agentArgs`和启动配置[bootstrap.properties](../../sermant-agentcore/sermant-agentcore-config/config/bootstrap.properties)封装为启动参数`Map`。 -- 调用**核心功能**入口[AgentCoreEntrance](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/AgentCoreEntrance.java)带起**核心功能**。 -- 注意,带起**核心功能**时需要将**路径相关参数**传递进去,这里将这些**路径相关参数**封装到启动参数`Map`中。这也说明**Sermant AgentCore Premain**需要做到对目录、文件位置的把控。 - -## 启动参数 - -**启动参数**指的是入参`agentArgs`和启动配置`bootstrap.properties`封装起来的配置`Map`,优先取前者的值。**启动参数**中固定内容如下: - -|入参键|启动配置键|启动参数键|含义|默认值|不为空|备注| -|:-|:-|:-|:-|:-:|:-|:-| -|appName|app.name|appName|应用名称|/|是|入参中必须存在| -|instanceName|instance.name|instanceName|实例名称|default|是|/| -|appType|app.type|appType|应用类型|0|是|/| -|env|env|env|/|/|否|/| -|envTag|env.tag|envTag|/|/|否|/| -|business|business|business|/|/|否|/| -|subBusiness|sub.business|subBusiness|/|/|否|/| -|envSecret|env.secret|envSecret|/|/|否|/| -|accessKey|access.key|access.key|/|/|否|/| -|secretKey|secret.key|secret.key|/|/|否|/| -|masterAddress|master.address|master.address|/|/|否|/| -|/|/|agentPath|入口包目录|入口包目录|是|无需配置| -|/|/|bootPath|/|/|是|已废弃| -|/|/|pluginsPath|/|/|是|已废弃| -|/|/|sermant.config.file|统一配置文件|统一配置文件|是|无需配置| -|/|/|sermant.plugin.setting.file|插件设定文件|插件设定文件|是|无需配置| -|/|/|sermant.plugin.package.dir|插件包目录|插件包目录|是|无需配置| -|/|/|sermant.log.setting.file|日志配置文件|日志配置文件|是|无需配置| - -入参`agentArgs`中可以为**启动参数**配置更多地值,他们可能会在[统一配置系统](agentcore-zh.md#统一配置系统)中使用到。 - -## 相关文档 - -|文档名称| -|:-| -|[核心模块介绍](agentcore-zh.md)| -|[后端模块介绍](backend-zh.md)| - -[返回**Sermant**说明文档](../README-zh.md) diff --git a/docs/user-guide/entrance.md b/docs/user-guide/entrance.md deleted file mode 100644 index 82a88c4b3f..0000000000 --- a/docs/user-guide/entrance.md +++ /dev/null @@ -1,91 +0,0 @@ -# Entrance of Sermant - -[简体中文](entrance-zh.md) | [English](entrance.md) - -This document is about [**Entrance of Sermant**](../../sermant-agentcore/sermant-agentcore-premain). - -## Components - -`source` contains: - -- `common`, contains the common code. - - `BootArgsBuilder`, is used to load the configuration at startup. - - `PathDeclarer`, defines the locations of resources in the sermant-agentcore. -- `exception`, contains custom exceptions. -- `AgentPremain`,the entrance of `JavaAgent`. Refer to [How to Use](#How to Use). - -`resources` contains: - -- `config/bootstrap.properties`,the bootstrap configuration file, loaded by [BootArgsBuilder](../../sermant-agentcore/sermant-agentcore-premain/src/main/java/com/huawei/sermant/premain/common/BootArgsBuilder.java), which forms the startup parameter *Map* together with the launch input parameter. - -## **How to Use** - -The **Entrance of Sermant** packages the *Java Agent* entrance package `sermant-agent.jar`. When you execute *Java* command, you can add the following parameters to bring up **Sermant** : - -```shell --javaagent:sermant-agent.jar[=${options}] -``` - -Where `${options}` is the launch input parameter, which will be transferred as the parameter `agentArgs` to the `premain` method. - -```java -public static void premain(String agentArgs, Instrumentation inst); -``` - -The format of the `agentArgs` parameter should look like `key1=value1,key2=value2[(,keyN=valueN)...]`, which splits key/value pairs with `','`, and splits between key and value with `'='` 'to form a `Map` structure. - -Note that `agentArgs` must contain a key/value pair whose `key` is `appName`. So the *Java* command argument added at startup should look exactly like this: - -```shell --javaagent:sermant-agent.jar=appName=${appName}[,${otherOptions}] -``` - -Where `${appName}` represents the appName and `${otherOptions}` represents other parameters. - -More *Java Agent* related content can be found in the official documentation for [java.lang.instrument](https://docs.oracle.com/javase/8/docs/api/java/lang/instrument/package-summary.html). - -## Function Explanation - -The **Entrance of Sermant** serves as the entry point to the **Sermant**, which brings the application to the **core functionality**. The functions of entry class [AgentPremain](../../sermant-agentcore/sermant-agentcore-premain/src/main/java/com/huawei/sermant/premain/AgentPremain.java) include: - -- Prevent **Sermant** from being fetched more than once by the host application (*Java Agent* command is added more than one **Sermant** entrance package). -- Load the packages of **core functionality**, using the system class loader. -- Encapsulate `agentArgs` and the bootstrap configuration [bootstrap.properties](../../sermant-agentcore/sermant-agentcore-config/config/bootstrap.properties)as startup parameter `Map`. -- Invoke the entrance of **core functionality** [AgentCoreEntrance](../../sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/AgentCoreEntrance.java) to bring up the core functionality. -- Note that **path-related parameters** are transferred to bring the **core functionality**. These **path-related parameters** are encapsulated in the startup parameters `Map`. This also means that **Sermant AgentCore Premain** needs to be able to control the directory and file location. - -## Startup Parameters - -**Startup Parameters** refer to the configuration `Map` encapsulated by the input parameter `agentArgs` and the bootstrap configuration `bootstrap.properties`, taking precedence to fetch the value from the former. The fixed contents of **startup parameters** are as follows: - -|Key in Input Parameters|Key in Bootstrap Configuration|Key in Startup Parameters|Explanation|Default Value|NotNull|Notes| -|:-|:-|:-|:-|:-:|:-|:-| -|appName|app.name|appName|The name of host application|/|True|Must present in startup parameters| -|instanceName|instance.name|instanceName|The name of the specific instance|default|True|/| -|appType|app.type|appType|The type of host application|0|True|/| -|env|env|env|/|/|False|/| -|envTag|env.tag|envTag|/|/|False|/| -|business|business|business|/|/|False|/| -|subBusiness|sub.business|subBusiness|/|/|False|/| -|envSecret|env.secret|envSecret|/|/|False|/| -|accessKey|access.key|access.key|/|/|False|/| -|secretKey|secret.key|secret.key|/|/|False|/| -|masterAddress|master.address|master.address|/|/|False|/| -|/|/|agentPath|The directory of Entrance package|The directory of Entrance package|True|No need to configure| -|/|/|bootPath|/|/|True|Deprecated| -|/|/|pluginsPath|/|/|True|Deprecated| -|/|/|sermant.config.file|Unified Configuration File|Unified Configuration File|True|No need to configure| -|/|/|sermant.plugin.setting.file|Plugin Setup Configuration|Plugin Setup Configuration|True|No need to configure| -|/|/|sermant.plugin.package.dir|The directory of plugin package|The directory of plugin package|True|No need to configure| -|/|/|sermant.log.setting.file|The directory of log configuration file|The directory of log configuration file|True|No need to configure| - -The `agentArgs` parameter allows you to configure more values for **startup parameters**, which may be used in the [Unified Configuration System](agentcore.md#Unified-Configuration-System). - -## Related Documents - -|Document| -|:-| -|[Introduction to Sermant-agentcore-core](agentcore.md)| -|[Introduction to Backend Module](backend.md)| - -[Back to README of **Sermant** ](../README.md) diff --git a/docs/user-guide/feature-list-zh.md b/docs/user-guide/feature-list-zh.md deleted file mode 100644 index 684c8f5edd..0000000000 --- a/docs/user-guide/feature-list-zh.md +++ /dev/null @@ -1,16 +0,0 @@ -# 当前功能列表 - -[简体中文](feature-list-zh.md) | [English](feature-list.md) - -|功能名称|状态|微服务框架组件支持列表|配置中心支持列表|注册中心支持列表|注意事项| -|:-:|:-:|:-----|:--|:--|:--| -|[限流降级](flowcontrol/flowcontrol-zh.md)|实验|SpringBoot 1.2.x - 2.6.x
SpringWebMvc 4.1.3.RELEASE - 5.3.x
Dubbo 2.6.x-2.7.x|servicecomb-kie
ZooKeeper|N/A|-| -|[服务注册](registry/document-zh.md)|GA|SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x|N/A|servicecomb-service-center|-| -|[服务双注册迁移](registry/spring-cloud-registry-migiration-zh.md)|实验|SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x|N/A|**目标注册中心**支持:servicecomb-service-center
**SpringCloud原注册中心**支持:Eureka、Nacos、Zookeeper、Consul
**Dubbo原注册中心**支持:Nacos、Zookeeper|-| -|[负载均衡](loadbalancer/document-zh.md)|开发中|SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0|servicecomb-kie
ZooKeeper|N/A|不同的版本所支持的负载均衡策略不同,具体请参考[负载均衡策略支持](loadbalancer/document.md#负载均衡策略支持一览)
当前暂不支持网关应用| -|[标签路由](router/document-zh.md)|实验|SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x|servicecomb-kie|servicecomb-service-center|不支持异步调用
不支持混合框架(Dubbo调SpringCloud或者SpringCloud调Dubbo)做路由| -|[区域路由](router/zone-router-zh.md)|实验|Dubbo 2.6.x-2.7.x|servicecomb-kie
ZooKeeper|servicecomb-service-center
ZooKeeper|-| -|[优雅上下线](graceful/document-zh.md)|实验|SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0|servicecomb-kie
ZooKeeper|N/A|该功能基于SpringCloud默认负载均衡实现,若实现自定义负载均衡,该能力将失效| -|[动态配置](dynamic-config/document-zh.md)|开发中|SpringBoot 1.5.x - 2.6.2
spring-cloud-starter-alibaba-nacos-config 1.5.0.RELEASE+
spring-cloud-starter-zookeeper-config 1.2.0.RELEASE+|servicecomb-kie
ZooKeeper|-|-| -|[服务监控](server-monitor/document-zh.md)|开发中|ALL|N/A|N/A|-| -|[服务注册与发现(SpringBoot)](springboot-registry/document-zh.md)|实验|SpringBoot 1.5.10.Release+|servicecomb-kie
ZooKeeper|Zookeeper 3.4.x+|-| diff --git a/docs/user-guide/feature-list.md b/docs/user-guide/feature-list.md deleted file mode 100644 index 189eb635ea..0000000000 --- a/docs/user-guide/feature-list.md +++ /dev/null @@ -1,17 +0,0 @@ -# Summary List of Current Plugin Features - -[简体中文](feature-list-zh.md) | [English](feature-list.md) - -|Feature|Status|Microservice Framework Supported|Configuration Center Supported|Registration Center Supported|Notice| -|:-:|:-:|:-----|:--|:--|:--| -|[FlowControl](flowcontrol/flowcontrol.md)|Experimental Stage|SpringBoot 1.2.x - 2.6.x
SpringWebMvc 4.1.3.RELEASE - 5.3.x
Dubbo 2.6.x-2.7.x|servicecomb-kie
ZooKeeper|N/A|-| -|[Service Registration](registry/document.md)|GA|SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x|N/A|servicecomb-service-center|-| -|[Service Dual Registration and Migration](registry/spring-cloud-registry-migiration.md)|Experimental Stage|SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x|N/A|**Target Registration Center** supported:servicecomb-service-center
**Original Registration Center of SpringCloud** supported:Eureka、Nacos、Zookeeper、Consul
**Original Registration Center of Dubbo** supported:Nacos、Zookeeper|-| -|[Loadbalancer](loadbalancer/document.md)|In Development|SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0|servicecomb-kie
ZooKeeper|N/A|Different versions support different load balancing policies. For details, refer to [Policies Supported in Loadbalance](loadbalancer/document.md#The-Strategy-Loadbalacne-Support)
Gateway applications are not supported at present.| -|[Tag Router](router/document.md)|Experimental Stage|SpringBoot 1.5.x - 2.6.2
SpringCloud Edgware.SR2 - 2021.0.0
Dubbo 2.6.x-2.7.x|servicecomb-kie|servicecomb-service-center|Asynchronous invocation is not supported.
Hybrid frameworks (SpringCloud or Dubbo) are not supported for routing| -|[Zone Router](router/zone-router.md)|Experimental Stage|Dubbo 2.6.x-2.7.x|servicecomb-kie
ZooKeeper|servicecomb-service-center
ZooKeeper|-| -|[Graceful Online/Offline](graceful/document.md)|Experimental Stage|SpringBoot 1.5.x - 2.6.2
SpringCloud -Edgware.SR2 - 2021.0.0|servicecomb-kie
ZooKeeper|N/A|This function is implemented based on the default loadbalance of SpringCloud. If user-defined loadbalance is implemented, this function won't work.| -|[Dynamic Configuration](dynamic-config/document.md)|In Development|SpringBoot 1.5.x - 2.6.2
spring-cloud-starter-alibaba-nacos-config 1.5.0.RELEASE+
spring-cloud-starter-zookeeper-config 1.2.0.RELEASE+|servicecomb-kie
ZooKeeper|-|| -|[Server Monitor](server-monitor/document.md)|In Development|ALL|N/A|N/A|-| -|[Service Registration and Discovery](springboot-registry/document.md)|Experimental Stage |SpringBoot 1.5.10.Release+|servicecomb-kie
ZooKeeper|Zookeeper 3.4.x+|-| \ No newline at end of file diff --git a/docs/user-guide/flowcontrol/FAQ-zh.md b/docs/user-guide/flowcontrol/FAQ-zh.md deleted file mode 100644 index 6e668f1fb5..0000000000 --- a/docs/user-guide/flowcontrol/FAQ-zh.md +++ /dev/null @@ -1,41 +0,0 @@ -# 流控常见问题 - -[简体中文](FAQ-zh.md) | [English](FAQ.md) - -本文档主要说明在使用流控插件时遇到的常见问题 - -## 关于业务场景的apiPath是如何定义的 - -- `apiPath`指需要作用的接口,针对不同框架定义会有所不同,当前支持http与dubbo协议请求: - - `http协议`: 指请求的路径,例如存在接口http://localhost:8080/test, 则其`apiPath`为`/test`; - - `dubbo协议`:由`"请求接口:接口版本.方法"`组成,如果无接口版本或者版本为0.0.0,则`apiPath`为`"请求接口.方法"`。 - -## 如何确定配置规则生效 - -- 首先需在配置中心上正确配置相关业务场景与治理策略,配置后可观察agent日志,一般在jar包启动路径的logs文件夹下,查看sermant-x.log文件, 搜索`has been`或者配置的键名, 若搜索到的日志与当前时间匹配,则说明规则已生效。 - -## 熔断策略未生效的可能原因 - -- 熔断生效有一定的前提,通常熔断从两个指标来判定: - - `异常比例`:即接口请求发生异常时所占比例,在规定时间内发生异常的比例大于配置的即会触发熔断; - - `慢调用比例`:即接口请求发生慢调用所占比例,设置熔断策略时需设置慢调用的阈值,例如100ms,则必须接口调用耗时超出100ms且超过配置的慢调用比例才可触发; -- 因此针对以上两项指标,首先排查应用接口是否满足以上其中一个条件,且规则时间内调用超过最小调用数(minimumNumberOfCalls配置)才可触发。 - -## 隔离仓规则未生效的可能原因 - -- 隔离仓规则需满足以下条件: - - `调用满足并发数`(maxConcurrentCalls配置)要求,例如配置的阈值为2,则确保并发数需大于2; - - `最大等待时间`(maxWaitDuration配置),即在达到最大并发数时,线程等待最大时间,超过该时间未拿到许可便会触发; -- 因此在实际测试时,若模拟该规则,建议确保业务接口耗时大于最大等待时间,并且并发数大于配置值。 - -## 重试规则未生效的可能原因 - -- 确保下游应用抛出的异常或者状态码符合重试策略要求,例如默认dubbo会检测下游是否抛出RpcException,Spring应用则可配置指定状态码检测。 - -## 启动报HttpHostConnectException异常的可能原因 - -- 出现该异常的原因是未启动`Sermant`后台服务`sermant-backhend`, 找到启动类`com.huawei.apm.backend.NettyServerApplication`启动后台服务,并重启应用即可。 - - - -[返回**Sermant**说明文档](../../README-zh.md) \ No newline at end of file diff --git a/docs/user-guide/flowcontrol/FAQ.md b/docs/user-guide/flowcontrol/FAQ.md deleted file mode 100644 index 075771f746..0000000000 --- a/docs/user-guide/flowcontrol/FAQ.md +++ /dev/null @@ -1,41 +0,0 @@ -# Flow Control FAQs - -[简体中文](FAQ-zh.md) | [English](FAQ.md) - -This document describes the common problems encountered when the flow control plug-in is used. - -## How Is The APIPath Defined In The Service Scenario? - -- `apiPath` indicates the interface to be used. The definition varies according to the framework. Currently, HTTP and Dubbo requests are supported: - - `http procotol`: Indicates the request path. For example, if the interface http://localhost:8080/test exists, the apiPath of the interface is `/test`. - - `dubbo procotol`:Request interface: `interface:version. Method`. If there is no interface version or the version is 0.0.0, the value of apiPath is Request `interface.Method`. - -## How Do I Determine Whether a Configuration Rule Takes Effect? - -- Configure service scenarios and governance policies correctly in the configuration center. After the configuration, you can view the agent logs. Generally, in the logs folder in the startup path of the JAR package, view the sermant-x.log file and search for `has been` or the configured key name. If the found logs match the current time, the rule has taken effect. - -## Possible Causes For The Failure Of The Circuit Breaker Policy To Take Effect - -- A circuit breaker takes effect only after the following conditions are met: - - `Error Rate`:The percentage of error interface requests. If the percentage of error interface requests within a specified period is greater than the configured value, the circuit breaker is triggered. - - `Slow Invoking Ratio`:The percentage of slow invoking requests. When setting the circuit breaker policy, you need to set the slow invoking threshold. For example, if the time required for invoking the interface exceeds 100 ms and exceeds the configured slow invoking ratio, the circuit breaker can be triggered only when the time required for invoking the interface exceeds 100 ms. -- Therefore, for the preceding two indicators, check whether the application interface meets either of the preceding conditions and whether the number of invoking requests within the rule period exceeds the minimum number specified by minimumNumberOfCalls. - -## Possible Reasons Why The Quarantine Rule Does Not Take Effect - -- The quarantine rules must meet the following conditions: - - `The number of concurrent calls meets the requirement` (configured by maxConcurrentCalls). For example, if the threshold is set to 2, ensure that the number of concurrent calls is greater than 2. - - `Maximum waiting time` (configured by maxWaitDuration), that is, the maximum waiting time of a thread when the number of concurrent connections reaches the maximum. If no permission is obtained after the maximum waiting time expires, the thread is triggered. -- Therefore, you are advised to ensure that the service interface duration is greater than the maximum waiting time and the number of concurrent requests is greater than the configured value. - -## Possible Causes For The Retry Rule Does Not Take Effect - -- Ensure that exceptions or status codes thrown by downstream applications meet the retry policy requirements. For example, by default, dubbo checks whether the downstream applications throw RpcException, and a specified status code can be configured for Spring applications. - -## Possible Causes Of The HttpHostConnectException Error Reported During Startup - -- The cause is that the Sermant background service sermant-backhend is not started. Find the startup class com.huawei.apm.backend.NettyServerApplication to start the background service and restart the application. - - - -[Back to README of **Sermant** ](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/flowcontrol/flowcontrol-zh.md b/docs/user-guide/flowcontrol/flowcontrol-zh.md deleted file mode 100644 index 1b108d6610..0000000000 --- a/docs/user-guide/flowcontrol/flowcontrol-zh.md +++ /dev/null @@ -1,441 +0,0 @@ -# FlowControl - -[简体中文](flowcontrol-zh.md) | [English](flowcontrol.md) - -本文档主要介绍[流控插件](../../../sermant-plugins/sermant-flowcontrol)以及该插件的使用方法 - -## 功能 - -流控插件基于[resilience4j](https://github.com/resilience4j)框架,以"流量"切入点,实现"无侵入式"流量控制;当前支持**限流**、**熔断**、**隔离仓**、**错误注入**与**重试**能力,并且支持配置中心动态配置规则,实时生效。 - -- **限流**:对指定接口限制1S秒内通过的QPS,当1S内流量超过指定阈值,将触发流控,限制请求流量。 -- **熔断**:对指定接口配置熔断策略,可从单位统计时间窗口内的错误率或者慢请求率进行统计,当请求错误率或者慢请求率达到指定比例阈值,即触发熔断,在时间窗口重置前,隔离所有请求。 -- **隔离仓**:针对大规模并发流量,对并发流量进行控制,避免瞬时并发流量过大导致服务崩溃。 -- **重试**:当服务遇到非致命的错误时,可以通过重试的方式避免服务的最终失败。 -- **错误注入:** 指在服务运行时,给指定服务配置错误注入策略,在客户端访问目标服务前,以指定策略模式返回。该策略多用于减少目标服务的访问负载,可作为降级的一种措施。 - -## 使用说明 - -### 环境准备 - -**(1)部署ServiceCenter环境与Kie环境** - -**(2)打包编译Sermant Agent** - - 参考[Sermant源码编译](../../QuickStart-zh.md#源码编译) - -### 配置agent - -**(1)修改服务注册信息** - -找到`${javaagent path}/agent/config/config.properties`,修改如下配置 - -```properties -# 服务app名称 -service.meta.application=default -# 服务版本 -service.meta.version=1.0.0 -# serviceComb 命名空间 -service.meta.project=default -# 环境 -service.meta.environment=development -# 自定义标签,按需配置,用于后续的配置订阅 -service.meta.customLabel=public -service.meta.customLabelValue=default -``` - -**提示**:以上配置均可通过环境变量指定,对应的键值即为环境变量键,例如服务app名称可由`-Dservice.meta.application=application`指定, 其他配置文件的所有键均可采用该方式配置。 - -##### **(2)修改配置中心** - -修改配置文件`${javaagent路径}/config/config.properties`, 修改配置中心类型与地址,如下位置: - -```properties -# 配置中心地址, 根据配置中心地址配置 -dynamic.config.server_address=127.0.0.1:30110 -# 配置中心类型, 支持KIE与ZOOKEEPER -dynamic.config.dynamic_config_type=KIE -``` - -**(3)配置流控插件** - -修改配置文件`${javaagent路径}/pluginPackage/flowcontrol/config/config.yaml` - -```yaml -flow.control.plugin: - useCseRule: true # 是否开启ServiceComb适配 -``` - -开启适配后,插件将根据应用配置,服务配置以及自定义标签订阅配置中心配置 - -> 此处若设置useCseRule为false,流控插件将基于当前实例的服务名进行配置订阅,例如:用户配置的spring.application.name=flowControlDemo, 则在实际订阅时会根据标签service=flowControlDemo接收配置。 - -### 部署应用 - -执行以下命令启动应用 - -```shell -# 其中agent路径指打包后的路径 -# serviceName值应用名 -# applicationName即对应app名称 -# environment即对应环境名称 -# xxx.jar值打包后应用jar包 -java -javaagent:${agent路径}/sermant-agent.jar=appName=${serviceName} -Dservice.meta.application=${applicationName} -Dservice.meta.environment=${environment} -jar xxx.jar -``` - -### 验证应用部署 - -登录[Service Center](localhost:30103)后台, 查看应用是否正确注册 - -### 流控规则介绍 - -流量治理采用流量标记+流控规则的方式对指定的流量进行流控,所谓流量标记,通俗讲为请求信息,例如接口路径、接口方法类型、请求头以及下游服务名。流控规则的是否生效取决与流量标记,仅当流量标记与请求相匹配,流控规则才会实际生效。而如何将流量标记对应上具体规则,则取决于业务场景名,通常流量标记与流控规则配置均要配置指定前缀,例如流量标记的键需以`servicecomb.MatchGroup`为前缀, 而限流规则则以`servicecomb.rateLimiting`为前缀,以一个具体的例子: - -流量标记配置键为:`servicecomb.MatchGroup.flow` - -限流规则配置键为:`servicecomb.rateLimiting.flow` - -如上,`flow`即为业务场景名,仅当两者业务场景名称一致,当请求匹配上流量标记时,限流规则才会生效 - -下面依次介绍相关配置: - -- **流量标记** - - ```yaml - matches: # 匹配器集合,可配置多个 - - apiPath: # 匹配的api路径, 支持各种比较方式,相等(exact)、包含(contains)等 - exact: /degrade # 具体匹配路径 - headers: # 请求头 - key: - exact: value # 请求头值,此处为key=value, 比较方式同apiPath - method: # 支持方法类型 - - GET - name: degrade # 可选,配置名 - ``` - - **流量标记解释:** - - - 请求路径为`/degrade`且方法类型为`GET`, 同时满足要求请求头包含`key=value`即匹配成功 - - 详细配置项可参考[ServiceComb开发文档](http://servicecomb.gitee.io/servicecomb-java-chassis-doc/java-chassis/zh_CN/references-handlers/governance.html#_2)流量标记部分 - - **流量标记请求路径(apiPath)配置说明** - - 流量标记的请求路径会因不同的请求协议配置而存在差异,当前主要为Http(Spring)与Rpc(Dubbo)协议,下面分别说明两种请求协议的配置方式: - - - Http协议 - - 该协议依据请求路径进行匹配,例如请求路径为localhost:8080/test/flow, 则实际拿到的路径为`/test/flow`,因此若需设置匹配规则,需依据该路径进行配置。 - - 值得注意的是,如果用户配置的contextPath, 则需要加上contextPath前缀才可生效。 - - - Rpc协议(Dubbo) - - 该协议调用需要基于接口+方法,例如请求的接口为com.demo.test, 其方法为flow, 则对应的请求路径为`com.demo.test.flow`, 特别的,如果用户有配置接口的版本,例如指定的version为1.0.0, 则请求路径为`com.demo.test:1.0.0.flow`。同时需要配置请求方法为`POST`, RPC协议仅支持POST类型。 - -- **限流** - - | 配置项 | 说明 | - | ------------------ | ------------------------------------------------------------ | - | limitRefreshPeriod | 单位统计时间,单位毫秒, 若需配置秒则可增加单位`S`, 例如`10S` | - | rate | 单位统计时间所能通过的**请求个数** | - -- **熔断** - - | 配置项 | 说明 | - | ------------------------- | ------------------------------------------------------------ | - | failureRateThreshold | 熔断所需达到的错误率 | - | minimumNumberOfCalls | 滑动窗口内的最小请求数, 超过最小请求数才开始判断熔断条件 | - | name | 配置项名称,可选参数 | - | slidingWindowSize | 滑动统计窗口大小,支持毫秒与秒,例如`1000`为1000毫秒, `10S`代表10秒 | - | slidingWindowType | 滑动窗口类型,目前支持`time`与`count`两种类型,前者基于时间窗口统计,后者基于请求次数 | - | slowCallDurationThreshold | 慢请求阈值,单位同滑动窗口配置 | - | slowCallRateThreshold | 慢请求占比,当慢调用请求数达到该比例触发通断 | - | waitDurationInOpenState | 熔断后恢复时间,默认`60S` | - -- **隔离** - - | 配置项 | 说明 | - | ------------------ | ------------------------------------------------------------ | - | maxConcurrentCalls | 最大并发数 | - | maxWaitDuration | 最大等待时间,若线程超过`maxConcurrentCalls`,会尝试等待,若超出等待时间还未获取资源,则抛出隔离仓异常 | - | name | 可选,配置名称 | - -- **重试** - - | 配置项 | 说明 | - | --------------------- | ------------------------------------------------------------ | - | waitDuration | 重试等待时间,默认毫秒;支持秒单位,例如2S | - | retryStrategy | 重试策略,当前支持两种重试策略:固定时间间隔(FixedInterval), 指数增长间隔(RandomBackoff) | - | maxAttempts | 最大重试次数 | - | retryOnResponseStatus | HTTP状态码,当前仅支持HTTP请求;针对dubbo请求,可通过配置异常类型确定是否需要重试,默认为RpcException | - -- **错误注入** - - | 配置项 | 说明 | - | ------------ | ------------------------------------------------------------ | - | type | 错误注入类型, 目前支持abort(请求直接返回)与delay(请求延时) | - | percentage | 错误注入触发概率 | - | fallbackType | 请求调用返回类型,仅`type=abort`生效。当前支持两种`ReturnNull`:直接返回空内容,状态码200;`ThrowException`: 按照指定错误码返回,关联配置`errorCode` | - | errorCode | 指定错误码返回, 默认500, 仅在`type=abort`且`fallbackType=ThrowException`生效 | - | forceClosed | 是否强制关闭错误注入能力, 当为true时,错误注入将不会生效。默认false | - -### 配置流控规则 - -#### 基于配置文件配置流控规则 - -如果您的应用**非**SpringBoot应用, 该方式将不适用。 - -流控插件在应用启动时,会尝试的从SpringBoot加载的配置源读取流控规则以及对应的流量标记,用户需要在启动之前进行配置。如下为配置示例, 示例配置直接基于`application.yml`进行配置 - -```yaml -servicecomb: - matchGroup: - demo-fault-null: | - matches: - - apiPath: - exact: "/flow" - demo-retry: | - matches: - - apiPath: - prefix: "/retry" - serviceName: rest-provider - method: - - GET - demo-rateLimiting: | - matches: - - apiPath: - exact: "/flow" - demo-circuitBreaker-exception: | - matches: - - apiPath: - exact: "/exceptionBreaker" - demo-bulkhead: | - matches: - - apiPath: - exact: "/flowcontrol/bulkhead" - rateLimiting: - demo-rateLimiting: | - rate: 1 - retry: - demo-retry: | - maxAttempts: 3 - retryOnResponseStatus: - - 500 - circuitBreaker: - demo-circuitBreaker-exception: | - failureRateThreshold: 44 - minimumNumberOfCalls: 2 - name: 熔断 - slidingWindowSize: 10000 - slidingWindowType: time - waitDurationInOpenState: 5s - bulkhead: - demo-bulkhead: | - maxConcurrentCalls: 1 - maxWaitDuration: 10 - faultInjection: - demo-fault-null: | - type: abort - percentage: 100 - fallbackType: ReturnNull - forceClosed: false -``` - -以上配置,配置当前支持的流控规则,具体配置项请根据实际需要进行变更。 - -#### 基于sermant-backend统一配置接口发布规则 - -[backend]()服务提供配置发布功能, 通过请求接口`/publishConfig`发布配置,请求参数如下: - -| 配置参数 | 说明 | -| -------- | ------------------------------------------------ | -| key | 配置键 | -| group | 配置的标签组 | -| content | 配置内容,即具体的规则配置,其格式均为`YAML`格式 | - -> 其中**group**的配置格式为k1=v1, 多个值使用"&"分隔,例如k1=v1&k2=v2, 代表该key绑定的标签组 - -**以下配置以`app=region-A`,` serviceName=flowControlDemo`, `environment=testing`举例** - -- #### 流量标记配置示例 - - ```json - { - "key":"servicecomb.matchGroup.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"alias: scene\nmatches:\n- apiPath:\n exact: /flow\n headers: {}\n method:\n - POST\n name: rule1\n" - } - ``` - - -**规则解释:** - -- 请求路径为`/flow`且方法类型为`GET`即匹配成功 -- 针对app为region-A,服务名为flowControlDemo且环境为testing的服务实例生效 - - - -> **注意事项:** -> -> - 流控配置首先需配置业务场景,再配置与业务场景绑定的流控规则 -> - `key`必须以`servicecomb.matchGroup.`为前置,`scene`则为业务名称 - -- #### **流控规则配置示例** - - ```json - { - "key":"servicecomb.rateLimiting.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"limitRefreshPeriod: \"1000\"\nname: flow\nrate: \"2\"\n" - } - ``` - **规则解释:** - - - 针对app为region-A,服务名为flowControlDemo且环境为testing的服务实例生效 - - 1秒内超过2个请求,即触发流控效果 - - - - > **注意事项:** - > - > `key`必须以`servicecomb.rateLimiting.`为前置,`scene`则为业务名称,确保与流量标记的业务场景名称一致 - -- #### **熔断规则配置示例** - - ```json - { - "key":"servicecomb.circuitBreaker.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"failureRateThreshold: 90\nminimumNumberOfCalls: 3\nname: degrade\nslidingWindowSize: 10S\nslidingWindowType: time\nslowCallDurationThreshold: \"1\"\nslowCallRateThreshold: 80\nwaitDurationInOpenState: 10s" - } - ``` - **规则解释:** - - - 针对app为region-A,服务名为flowControlDemo且环境为testing的服务实例生效 - - 10秒内,若请求接口`/flow`次数超过3次,且错误率超过90%或者慢请求占比超过80%则触发熔断 - - - - > **注意事项:** - > - > `key`必须以`servicecomb.circuitBreaker.`为前置,`scene`则为业务名称,确保与流量标记的业务场景名称一致 - -- #### 隔离仓规则配置示例 - - ```json - { - "key":"servicecomb.bulkhead.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"maxConcurrentCalls: \"5\"\nmaxWaitDuration: \"10S\"\nname: \"隔离仓\"\n" - } - ``` - - **规则解释:** - - - 针对app为region-A,服务名为flowControlDemo且环境为testing的服务实例生效 - - 针对接口`/flow`, 若最大并发数超过5,且新的请求等待10S,还未获取资源,则触发隔离仓异常 - - - - > **注意事项:** - > - > `key`必须以`servicecomb.bulkhead.`为前置,`scene`则为业务名称,确保与流量标记的业务场景名称一致 - -- #### 重试规则配置示例 - - ```json - { - "key":"servicecomb.retry.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"waitDuration: \"2000\"\nretryStrategy: FixedInterval\nmaxAttempts: 2\nretryOnResponseStatus:\n- 500" - } - ``` - - **规则解释:** - - - 针对app为region-A,服务名为flowControlDemo且环境为testing的服务实例生效 - - 针对接口`/flow`, 当请求抛出500异常时进行重试,直到重试成功或者达到最大重试次数 - - - - > **注意事项:** - > - > `key`必须以`servicecomb.retry.`为前置,`scene`则为业务名称,确保与流量标记的业务场景名称一致 - - **特别说明**:对于Dubbo重试, 流控插件采用替代原生的ClusterInvoker方式实现, 请求逻辑将采用流控插件自身实现的ClusterInvoker进行调用,而原宿主选择的将会失效(例如:dubbo默认的FailoverClusterInvoker)。如果此处仍需使用原来的ClusterInvoker,可通过添加环境变量`-Dflow.control.plugin.useOriginInvoker=true`实现, 但该方式可能存在少量的性能损失。 - -- #### 错误注入规则示例 - - ```json - { - "key":"servicecomb.faultInjection.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"type: abort\npercentage: 100\nfallbackType: ReturnNull\nforceClosed: false\nerrorCode: 503" - } - ``` - - **规则解释:** - - - 针对app为region-A,服务名为flowControlDemo且环境为testing的服务实例生效 - - 当请求接口`/flow`时,100%将返回空 - - - - > **注意事项:** - > - > `key`必须以`servicecomb.faultInjection.`为前置,`scene`则为业务名称,确保与流量标记的业务场景名称一致 - -## 快速开始 - -### 1、编译打包 - -通过[此处](https://github.com/huaweicloud/Sermant/releases)下载sermant软件包, 并下载[Demo源码](https://github.com/huaweicloud/Sermant-examples/tree/main/flowcontrol-demo/spring-cloud-demo/spring-provider) - -执行以下maven命令对Demo应用执行打包 - -```shell -mvn clean package -``` - -### 2、启动应用 - -```shell -java -javaagent:${agent路径}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=spring-flow-provider -Dservice.meta.application=region-A -Dservice.meta.environment=testing -Dspring.application.name=spring-flow-provider -jar spring-provider.jar -``` - -### 3、配置规则 - -参考[配置流控规则](#配置流控规则)配置**流量标记**与**流控规则** - -**流量标记:** - -```json -{ - "key": "servicecomb.matchGroup.sceneFlow", - "group": "app=sc&service=spring-flow-provider&environment=testing", - "content": "alias: scene\nmatches:\n- apiPath:\n exact: /flow\n headers: {}\n method:\n - POST\n name: flow\n" -} -``` - -**流控规则:** - -```json -{ - "key": "servicecomb.rateLimiting.scene", - "group": "app=region-A&service=spring-flow-provider&environment=testing", - "content": "limitRefreshPeriod: \"2S\"\nname: flow\nrate: \"4\"\n" -} -``` - -### 4、验证结果 - -多次请求`localhost:8003/flow`, 若在2秒内请求数超过4个时返回`rate limited`,则触发流控成功 - -## 其他 - -若使用过程中遇到问题请先参考[FAQ文档](./FAQ-zh.md) - - - -[返回**Sermant**说明文档](../../README-zh.md) diff --git a/docs/user-guide/flowcontrol/flowcontrol.md b/docs/user-guide/flowcontrol/flowcontrol.md deleted file mode 100644 index f21bb9f9b5..0000000000 --- a/docs/user-guide/flowcontrol/flowcontrol.md +++ /dev/null @@ -1,445 +0,0 @@ -# FlowControl - -[简体中文](flowcontrol-zh.md) | [English](flowcontrol.md) - -This document is used to introduce the usage of [Flow Control Plugin](../../../sermant-plugins/sermant-flowcontrol) - -## Functions - -The flow control plugin is based on the [resilience4j]((https://github.com/resilience4j)) framework and implements non-intrusive flow control based on the "traffic" entry point. Currently, **Traffic Limiting, Circuit Breaker, Bulkhead, Error Injection, and Retry** are supported. In addition, rules can be dynamically configured in the configuration center and take effect in real time. - -- **Traffic Limiting**:The number of QPS that pass through a specified interface within 1s is limited. When the traffic within 1s exceeds the specified threshold, flow control is triggered to limit the requested traffic. -- **Circuit Breaker**:Configure a circuit breaker policy for a specified interface to collect statistics on the error rate or slow request rate in a specified time window. When the error rate or slow request rate reaches a specified threshold, the circuit breaker is triggered. Before the time window is reset, all requests are isolated. -- **Bulkhead**:Controls concurrent traffic for a large number of concurrent traffic to prevent service breakdown caused by excessive instantaneous concurrent traffic. -- **Retry**:If a service encounters a non-fatal error, you can retry the service to prevent the service failure. -- **Error Injection:** An error injection policy is configured for a specified service when the service is running. Before the client accesses the target service, the error injection policy is used. This policy is mainly used to reduce the access load of the target service and can be used as a measure of downgrading the target service. - -## Usage - -### Environment Preparation - -**(1)Deploying the ServiceCenter and Kie environments** - -**(2)Package and compile Sermant Agent** - -The way that compile Sermant Agent referring [this article](../../QuickStart.md#Get-Compiled-Products) - -Compile by referring to the Sermant source code. - -### Configure Agent - -**(1)Modify Service Registration Information** - -Find the `${javaagent path}/agent/config/config.properties` and modify the content comply following configuration: - -```properties -# application name, you can keep default -service.meta.application=default -# service version -service.meta.version=1.0.0 -# serviceComb namespace, keep default -service.meta.project=default -# environment, it only support development/testing/production -service.meta.environment=development -# custom label, it use to subscribe the config of config center -service.meta.customLabel=public -service.meta.customLabelValue=default -``` - -**Notice**:The preceding configurations can be specified using environment variables. The corresponding key value is the environment variable key. For example, the service app name can be specified by `-Dservice.meta.application=application`. All keys in other configuration files can be configured using this method. - -##### **(2)Modify the Configuration Center** - -Modify the configuration file ${javaagent path}/config/config.properties and modify the configuration center type and address as follows: - -```properties -# IP address of the configuration center. Set this parameter based on the IP address of the configuration center. -dynamic.config.server_address=127.0.0.1:30110 -# Configuration center type. The options are KIE and ZOOKEEPER. -dynamic.config.dynamic_config_type=KIE -``` - -**(3)Configure the Flow Control Plugin** - -Modify the Configuration File`${javaagent path}/pluginPackage/flowcontrol/config/config.yaml` - -```yaml -flow.control.plugin: - useCseRule: true -``` - -If adaptation is enabled, the plugin subscribes to the configuration center based on the application configuration, service configuration, and customized tag configuration. - -> If useCseRule is set to false, the flow control plugin configures subscription based on the service name of the current instance. For example, if spring.application.name is set to flowControlDemo, the flow control plugin receives configuration based on the service=flowControlDemo tag during actual subscription. - -### Deploying Applications - -Run the following command to start the application: - -```shell -# agent path indicates the package path. -# serviceName indicates the name of your service -# applicationName indicates the app name -# environment indicates the environment of your service, support testing/producation/developing -# xxx.jar indicates the application packages of your service -java -javaagent:${agent path}/sermant-agent.jar=appName=${serviceName} -Dservice.meta.application=${applicationName} -Dservice.meta.environment=${environment} -jar xxx.jar -``` - -### Verify Application Deployment - -Login to the [Service Center](localhost:30103) background and check whether the application is correctly registered. - -### Flow Control Rules Specification - -Traffic governance uses traffic marking and flow control rules to control specified traffic. Traffic marking refers to request information, such as the interface path, interface method type, request header, and downstream service name. Whether a flow control rule takes effect depends on the traffic flag. A flow control rule takes effect only when the traffic flag matches the request. The mapping between traffic marks and specific rules depends on the service scenario name. Generally, a specified prefix must be configured for traffic marks and traffic control rules. For example, the key of traffic marks must be prefixed with `servicecomb.MatchGroup`. The traffic limiting rule is prefixed with `servicecomb.rateLimiting`. The following is an example: - -The traffic marking configuration key:`servicecomb.MatchGroup.flow` - -The key for configuring the traffic limiting rule:`servicecomb.rateLimiting.flow` - -In the preceding information, `flow `is the service scenario name. The traffic limiting rule takes effect only when the two service scenario names are the same and the request matches a traffic flag. - -The following describes the related configurations: - -- **Traffic Marking** - - ```yaml - matches: # Matcher set. Multiple matchers can be configured. - - apiPath: # Matched API path. Various comparison modes are supported, such as exact and contain. - exact: /degrade # Specific Matching Path - headers: # Request header - key: - exact: value # Request header value. The value is key=value. The comparison method is the same as that of apiPath. - method: # Supported Method Types - - GET - name: degrade # Configuration name, which is optional. - ``` - - **what traffic marking above can match :** - - - If the request path is `/degrade`, the method type is `GET`, and the request header contains `key=value`, the matching is successful. - - - - > For details about the configuration items, see the traffic marking section in the [ServiceComb development document](http://servicecomb.gitee.io/servicecomb-java-chassis-doc/java-chassis/zh_CN/references-handlers/governance.html#_2). - - **Traffic marking request path (apiPath) configuration description** - - The request path for traffic marking varies according to the request protocol configuration. Currently, HTTP (Spring) and RPC (Dubbo) protocols are used. The following describes how to configure the two request protocols: - - - **Http protocol** - - This protocol performs matching based on the request path. For example, if the request path is `localhost:8080/test/flow`, the actual path is `/test/flow`. Therefore, if you need to set a matching rule, you need to configure the matching rule based on the path. - - It should be noted that if the contextPath configured by the user is valid only after the contextPath prefix is added. - - - **Rpc protocol(Dubbo)** - - The protocol invoking needs to be based on an interface+method. For example, if the requested interface is `com.demo.test`, and the method is `flow`, a corresponding request path is `com.demo.test.flow`. Specially, if a user configures an interface version, for example, a specified version is `1.0.0`, The request path is `com.demo.test:1.0.0.flow`. In addition, set the request method to `POST`. The RPC protocol supports only POST. - -- **Traffic Limiting** - - | Configuration | Description | - | ------------------ | ------------------------------------------------------------ | - | limitRefreshPeriod | Unit of statistics time, in milliseconds. If you need to set this parameter, the unit can be set to `S`, for example, `10s`. | - | rate | Number of requests that can be processed in the unit of statistical time. | - -- **Circuit Breaker** - - | Configuration | Description | - | ------------------------- | ------------------------------------------------------------ | - | failureRateThreshold | Error rate required for fuse | - | minimumNumberOfCalls | Minimum number of requests in the sliding window. The fuse condition is determined only when the minimum number of requests is exceeded. | - | name | Specifies the name of a configuration item. This parameter is optional. | - | slidingWindowSize | Size of the sliding statistics window. The value can be milliseconds or seconds. For example, 1000 indicates 1000 milliseconds, and 10s indicates 10 seconds. | - | slidingWindowType | Sliding window type. Currently, `time` and `count` are supported. The former is based on the time window and the latter is based on the number of requests. | - | slowCallDurationThreshold | Slow request threshold. The unit is the same as that of the sliding window. | - | slowCallRateThreshold | Percentage of slow invoking requests. When the number of slow invoking requests reaches this percentage, connectivity is triggered. | - | waitDurationInOpenState | Recovery time after a circuit breaker. The default value is `60s`. | - -- **Bulkhead** - - | Configuration | Description | - | ------------------ | ------------------------------------------------------------ | - | maxConcurrentCalls | Maximum number of concurrent calls | - | maxWaitDuration | Maximum waiting time. If the thread exceeds maxConcurrentCalls, the thread attempts to wait. If the thread does not obtain resources after the waiting time expires, an isolation warehouse exception is thrown. | - | name | name of configuration, which is optional. | - -- **Retry** - - | Configuration | Description | - | --------------------- | ------------------------------------------------------------ | - | waitDuration | Retry wait time. The default value is milliseconds. The unit is second, for example, 2s. | - | retryStrategy | Retry policy. Currently, two retry policies are supported: fixed interval (FixedInterval) and exponential increase interval (RandomBackoff). | - | maxAttempts | Maximum number of retries | - | retryOnResponseStatus | HTTP status code. Currently, only HTTP requests are supported. For dubbo requests, you can configure the exception type to determine whether to retry. The default value is RpcException. | - -- **Error Injection** - - | Configuration | Description | - | ------------- | ------------------------------------------------------------ | - | type | Error injection type. Currently, `abort (request response)` and `delay (request delay)` are supported. | - | percentage | Error Injection triggering probability | - | fallbackType | Return type of the request invoking. This parameter is valid only when `type is set to abort`. Currently, two types are supported, `ReturnNull`: empty content is directly returned and the status code is 200. `ThrowException`: The error code is returned based on the specified error code.` | - | errorCode | Specifies the returned error code. The default value is 500. This parameter is valid only `when type is abort and fallbackType is ThrowException`. | - | forceClosed | Indicates whether to forcibly disable the error injection capability. If this parameter is set to true, error injection does not take effect. The default value is false. | - -### Configuring Flow Control Rule - -#### Configuring Flow Control Rules Based On The Configuration File - -If your application is not a SpringBoot application, this method is not applicable. - -When an application is started, the flow control plugin attempts to read the flow control rules and corresponding traffic flags from the configuration source loaded by SpringBoot. You need to configure the flow control rules before starting the application. The following is a configuration example. The example configuration is based on the `application.yml` file. - -```yaml -servicecomb: - matchGroup: - demo-fault-null: | - matches: - - apiPath: - exact: "/flow" - demo-retry: | - matches: - - apiPath: - prefix: "/retry" - serviceName: rest-provider - method: - - GET - demo-rateLimiting: | - matches: - - apiPath: - exact: "/flow" - demo-circuitBreaker-exception: | - matches: - - apiPath: - exact: "/exceptionBreaker" - demo-bulkhead: | - matches: - - apiPath: - exact: "/flowcontrol/bulkhead" - rateLimiting: - demo-rateLimiting: | - rate: 1 - retry: - demo-retry: | - maxAttempts: 3 - retryOnResponseStatus: - - 500 - circuitBreaker: - demo-circuitBreaker-exception: | - failureRateThreshold: 44 - minimumNumberOfCalls: 2 - name: circuit breaker - slidingWindowSize: 10000 - slidingWindowType: time - waitDurationInOpenState: 5s - bulkhead: - demo-bulkhead: | - maxConcurrentCalls: 1 - maxWaitDuration: 10 - faultInjection: - demo-fault-null: | - type: abort - percentage: 100 - fallbackType: ReturnNull - forceClosed: false -``` - -The preceding configurations are used to configure the supported flow control rules. Change the configuration items based on the site requirements.。 - -#### Configuring Interface Advertisement Rules Based on Sermant Backend - -The backend service provides the function of publishing configurations through the /publishConfig request interface. The request parameters are as follows: - -| Configuration | Description | -| ------------- | ------------------------------------------------------------ | -| key | Configuration key | -| group | Configured tag group | -| content | Configuration content, that is, specific rule configuration, is in YAML format. | - -> The format of group is k1=v1, and multiple values are separated by ampersands (&). For example, k1=v1&k2=v2, indicating the label group bound to the key. - -**The following uses `app=region-A,serviceName=flowControlDemo, environment=testing` as an example.** - -- #### The Example Configuration For Traffic Marking Rule - - ```json - { - "key":"servicecomb.matchGroup.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"alias: scene\nmatches:\n- apiPath:\n exact: /flow\n headers: {}\n method:\n - POST\n name: rule1\n" - } - ``` - - -**Rule Interpretation:** - -- If the request path is `/flow` and the method type is `GET`, the matching is successful. -- This parameter takes effect for the service instance whose app is `region-A`, service name is `flowControlDemo`, and environment is `testing`. - - - -> **Notices:** -> -> - To configure flow control, you need to configure the service scenario and then configure the flow control rule bound to the service scenario. -> - The `key` must be preceded by `servicecomb.matchGroup`. and the scene indicates the service name. - -- #### The Example Configuration For Traffic Limiting Rule - - ```json - { - "key":"servicecomb.rateLimiting.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"limitRefreshPeriod: \"1000\"\nname: flow\nrate: \"2\"\n" - } - ``` - **Rule Interpretation:** - - - This parameter takes effect for the service instance whose app is region-A, service name is flowControlDemo, and environment is testing. - - If more than two requests are received within one second, flow control is triggered. - - - - > **Notices:** - > - > The `key` must be preceded by `servicecomb.rateLimiting`. and scene indicates the service name. Ensure that the value is the same as the service scenario name of the traffic tag. - -- #### The Example Configuration For Circuit Breaker Rule - - ```json - { - "key":"servicecomb.circuitBreaker.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"failureRateThreshold: 90\nminimumNumberOfCalls: 3\nname: degrade\nslidingWindowSize: 10S\nslidingWindowType: time\nslowCallDurationThreshold: \"1\"\nslowCallRateThreshold: 80\nwaitDurationInOpenState: 10s" - } - ``` - **Rule Interpretation:** - - - This parameter takes effect for the service instance whose app is region-A, service name is flowControlDemo, and environment is testing. - - If the number of interface or flow requests exceeds three within 10 seconds and the error rate exceeds 90% or the percentage of slow requests exceeds 80%, the circuit breaker is triggered. - - - - > **Notices:** - > - > The key must be preceded by servicecomb.circuitBreaker. and scene indicates the service name. Ensure that the value is the same as the service scenario name of the traffic tag. - -- #### The Example Configuration For Bulkhead Rule - - ```json - { - "key":"servicecomb.bulkhead.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"maxConcurrentCalls: \"5\"\nmaxWaitDuration: \"10S\"\nname: \"bulkhead\"\n" - } - ``` - - **Rule Interpretation:** - - - This parameter takes effect for the service instance whose app is region-A, service name is flowControlDemo, and environment is testing. - - For an interface `/flow`, if the maximum number of concurrent requests exceeds 5 and a new request waits for 10 seconds and resources are not obtained, an exception occurs in the isolation repository. - - - - > **Notices:** - > - > The key must be preceded by servicecomb.bulkhead. and scene indicates the service name. Ensure that the value is the same as the service scenario name of the traffic tag. - -- #### The Example Configuration For Retry Rule - - ```json - { - "key":"servicecomb.retry.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"waitDuration: \"2000\"\nretryStrategy: FixedInterval\nmaxAttempts: 2\nretryOnResponseStatus:\n- 500" - } - ``` - - **Rule Interpretation:** - - - This parameter takes effect for the service instance whose app is region-A, service name is flowControlDemo, and environment is testing. - - For an interface `/flow`, when the 500 exception is thrown, the request is retried until the retry succeeds or the maximum number of retry times is reached. - - - - > **Notices**: - > - > The key must be preceded by servicecomb.retry. and scene indicates the service name. Ensure that the value is the same as the service scenario name of the traffic tag. - - **Notices**: For Dubbo retry, the flow control plugin will replace the original ClusterInvoker. The request logic is invoked by the ClusterInvoker implemented by the flow control plugin, and the original ClusterInvoker will become invalid (for example: Default FailoverClusterInvoker for dubbo. If you need to use original ClusterInvoker, you can add the environment variable `-Dflow.control.plugin.useOriginInvoker=true`. However, this method may cause a small performance loss. - -- #### The Example Configuration For Error Injection Rule - - ```json - { - "key":"servicecomb.faultInjection.scene", - "group":"app=region-A&service=flowControlDemo&environment=testing", - "content":"type: abort\npercentage: 100\nfallbackType: ReturnNull\nforceClosed: false\nerrorCode: 503" - } - ``` - - **Rule Interpretation:** - - - This parameter takes effect for the service instance whose app is region-A, service name is flowControlDemo, and environment is testing. - - When the interface /flow is requested, 100% returns null. - - - - > **Notices**: - > - > The key must be preceded by servicecomb.faultInjection. and scene indicates the service name. Ensure that the value is the same as the service scenario name of the traffic tag. - -## Quick Start - -### 1、Compile And Package - -Download the [sermant release package](https://github.com/huaweicloud/Sermant/releases) and [demo source code](https://github.com/huaweicloud/Sermant-examples/tree/main/flowcontrol-demo/spring-cloud-demo/spring-provider). - -Run the following maven command to package the demo application: - -```shell -mvn clean package -``` - -### 2、Start Application - -```shell -java -javaagent:${agent path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=spring-flow-provider -Dservice.meta.application=region-A -Dservice.meta.environment=testing -Dspring.application.name=spring-flow-provider -jar spring-provider.jar -``` - -### 3、Configure The Rule - -Configure traffic marking and traffic limiting rules by referring to [Configuring Flow Control Rules](#Configuring-Flow-Control-Rule). - -**Traffic Marking:** - -```json -{ - "key": "servicecomb.matchGroup.sceneFlow", - "group": "app=sc&service=spring-flow-provider&environment=testing", - "content": "alias: scene\nmatches:\n- apiPath:\n exact: /flow\n headers: {}\n method:\n - POST\n name: flow\n" -} -``` - -**Traffic Limiting Rule:** - -```json -{ - "key": "servicecomb.rateLimiting.scene", - "group": "app=region-A&service=spring-flow-provider&environment=testing", - "content": "limitRefreshPeriod: \"2S\"\nname: flow\nrate: \"4\"\n" -} -``` - -### 4、Verify Result - -Request `localhost:8003/flow` for multiple times. If `rate limited` is returned when the number of requests exceeds 4 within 2 seconds, flow control is triggered successfully. - -## Others - -If you encounter any problems, refer to the [FAQ document](./FAQ.md). - - - -[Back to README of **Sermant** ](../../README.md) diff --git a/docs/user-guide/graceful/document-zh.md b/docs/user-guide/graceful/document-zh.md deleted file mode 100644 index f9b8f1f596..0000000000 --- a/docs/user-guide/graceful/document-zh.md +++ /dev/null @@ -1,191 +0,0 @@ -# Graceful Online/Offline - -[简体中文](document-zh.md) | [English](document.md) - -该文档主要介绍优雅上下线能力以及其使用方法,该功能当前集成在[注册插件](../../../sermant-plugins/sermant-service-registry) 中, 但功能可独立使用。 - -## 功能 - -应用的重启、升级、扩容等操作无法避免,而该过程中时常会遇到以下问题: - -- 刚上线的实例,由于流量过大,该实例在初始化时便被大量流量访问,导致请求阻塞,甚至宕机。例如存在懒加载的场景 -- 实例下线时,因注册发现延迟刷新问题,无法及时告知上游,导致流量丢失或者错误。 - -为解决上述问题,优雅上下线应运而生,针对以上两个问题,插件提供**预热**与**优雅下线**能力,对上述场景问题提供保护。 - -**预热**, 顾名思义,即先用少部分流量对实例访问,后续根据时间推移,逐渐增加增加流量,确保新启动实例能成功过渡。 - -**优雅下线**,即对下线的实例提供保护,插件基于**实时通知**+**刷新缓存的机制**快速更新上游缓存,同时基于流量统计的方式,确保即将下线的实例尽可能的将流量处理完成,最大程度避免流量丢失。 - -## 版本支持 - -当前优雅上下线能力**仅支持SpringCloud应用**,需确保SpringCloud版本在`Edgware.SR2`及以上。 - -注册中心支持:Zookeeper、Consul、Naocs、Eureka、ServiceCenter - -**特别说明**:优雅上下线能力基于SpringCloud的默认负载均衡能力开发,若您实现了自定义负载均衡能力,该能力将不再适用。 - -## 使用说明 - -### 开启优雅上下线 - -若需要使用优雅上下线能力,首先需开启该能力,相关配置见[配置文件](../../../sermant-plugins/sermant-service-registry/config/config.yaml), 若您已完成Sermant打包,则配置文件路径为`${agent path}/agent/pluginPackge/service-registry/config/config.yaml` - -```yaml -grace.rule: - enableSpring: true # springCloud优雅上下线开关 - startDelayTime: 0 # 优雅上下线启动延迟时间, 单位S - enableWarmUp: true # 是否开启预热 - warmUpTime: 120 # 预热时间, 单位S - enableGraceShutdown: true # 是否开启优雅下线 - shutdownWaitTime: 30 # 关闭前相关流量检测的最大等待时间, 单位S. 需开启enabledGraceShutdown才会生效 - enableOfflineNotify: true # 是否开启下线主动通知 - httpServerPort: 16688 # 开启下线主动通知时的httpServer端口 - upstreamAddressMaxSize: 500 # 缓存上游地址的默认大小 - upstreamAddressExpiredTime: 60 # 缓存上游地址的过期时间 -``` - -除上述配置文件方式外,您还可基于环境变量或者系统参数进行配置,以开启优雅上下线开关为例,此处可配置环境变量`-Dgrace.rule.enableSpring=true`开启开关。 - -### 使用优雅上下线 - -#### 虚机场景 - -根据OS,携带agent并配置优雅上下线相关参数启动即可。 - -```shell -# windows -java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -jar xxx.jar - -# mac, linux -java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=default -jar xxx.jar -``` - -相关标识符说明: - -- ${path}: 此处路径(path)为实际打包的agent路径,请替换为实际路径 -- sermant-agent-x.x.x: x.x.x请换成实际打包的Sermant版本, 例如1.0.0 -- xxx.jar: 为您的应用包,请根据你的应用包名进行替换 - -#### 容器场景 - -容器场景可基于`Sermant-Injector`快速启动, 参考[容器化部署](../injector-zh.md)。 - -同时需修改[Deployment编排文件](../injector-zh.md#部署),添加优雅上下线环境变量,修改后的编排文件如下: - -```yaml -apiVersion: v1 -kind: Deployment -metadata: - name: demo-test - labels: - app: demo-test -spec: - replicas: 1 - selector: - app: demo-test - matchLabels: - app: demo-test - template: - metadata: - labels: - app: demo-test - sermant-injection: enabled - spec: - containers: - - name: image - # 请替换成您的应用镜像 - image: image:1.0.0 - ports: - - containerPort: 8080 - env: - - name: "grace_rule_enableSpring" - value: "true" - - name: "grace.rule.enableWarmUp" - value: "true" - - name: "grace_rule_enableGraceShutdown" - value: "true" - - name: "grace.rule.enableOfflineNotify" - value: "true" - ports: - - port: 443 - targetPort: 8443 -``` - -随后按照容器化流程启动即可。 - -## 快速入门 - -下面以一个简单demo演示如何在虚机场景验证优雅上下线 - -1. 环境准备 - - (1)下载JDK,并配置JDK环境,JDK需在1.8及以上;下载Maven,并配置Maven环境 - - (2)下载最新Sermant release包,点击[此处](https://github.com/huaweicloud/Sermant/releases)下载 - - (3)下载[Demo 源码](https://github.com/huaweicloud/Sermant-examples/tree/main/grace-demo/spring-grace-nacos-demo) - - (4)编译Demo - - ​ 执行以下命令打包demo - - ​ `mvn clean package` - - (5)下载nacos,并启动 - - (6)下载zookeeper,并启动(作为sermant配置中心) - -2. 部署 - - 我们将部署一个consumer实例,2个provider实例, 一个data实例。如下: - - `consumer -----------> provider(两实例) -------------> data` - - 其中consumer开启优雅上下线能力,一个provider实例开启预热与优雅下线能力, 另一个provider实例仅开启优雅下线能力。 - - (1)启动data - - ```shell - java -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -jar nacos-rest-data-2.2.0.RELEASE.jar - ``` - - (2)启动第一个provider实例(端口8880, **关闭预热功能**) - - ```shell - # windows - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=false -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8880 -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -jar nacos-rest-provider-2.2.0.RELEASE.jar - - # mac, linux - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=false -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8880 -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=default -jar nacos-rest-provider-2.2.0.RELEASE.jar - ``` - - (3)启动第二个provider实例(端口8890, **开启预热能力**) - - ```shell - # windows - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8890 -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -jar nacos-rest-provider-2.2.0.RELEASE.jar - - # mac, linux - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8890 -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=default -jar nacos-rest-provider-2.2.0.RELEASE.jar - ``` - - (4)启动consumer - - ```shell - # windows - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8800 -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -jar nacos-rest-consumer-2.2.0.RELEASE.jar - - # mac, linux - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8800 -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=default -jar nacos-rest-consumer-2.2.0.RELEASE.jar - ``` - -3. 验证预热能力 - - 访问接口`localhost:8800/graceHot`, 根据接口返回的ip与port判断预热是否生效。若预热时间段内(默认120s)访问偏向8880,随时间推移流量逐渐平均,则说明预热生效。 - -4. 验证优雅下线 - - 持续访问接口`localhost:8800/graceDownOpen`, 此时下线其中一个provider实例,观察请求是否出现错误,若未出现错误,则优雅下线能力验证成功。 - -[返回**Sermant**说明文档](../../README-zh.md) \ No newline at end of file diff --git a/docs/user-guide/graceful/document.md b/docs/user-guide/graceful/document.md deleted file mode 100644 index 5f6670b319..0000000000 --- a/docs/user-guide/graceful/document.md +++ /dev/null @@ -1,191 +0,0 @@ -# Graceful Online/Offline - -[简体中文](document-zh.md) | [English](document.md) - -The document is used to introduce the usage of graceful online/offline, it is currently integrated in the [Service Registration Plugin](../../../sermant-plugins/sermant-service-registry), but can be used independently. - -## Functions - -Operations such as restarting, upgrading, and capacity expansion of applications cannot be avoided. During these operations, the following problems may occur: - -- Due to heavy traffic, the instance is accessed by a large amount of traffic during initialization. As a result, requests may be blocked or even broken down. For example, lazy loading. -- When an instance goes offline, the upstream application cannot be notified in real time due to it's refresh mechanism which need refresh instances at schedule time. As a result, traffic is lost or incorrect. - -To solve the preceding problems, graceful online/offline is developed. To solve the preceding problems, the plug-in provides the **warm up** and **graceful offline** capabilities to protect against the preceding problems. - -**Warm up**, as the name suggests, uses a small amount of traffic to access the instance first, and gradually increases the traffic based on time to ensure that the newly started instance can successfully transition. - -**Graceful offline**, The plugin quickly updates the upstream cache based on the **real-time notification** + **cache update mechanism**. In addition, traffic statistics are collected to ensure that the instances that are about to go offline can process traffic as much as possible, preventing traffic loss to the greatest extent. - -## Support Versions - -Currently, the graceful online/offline capability **supports only SpringCloud applications**. Ensure that the SpringCloud version is `Edgware.SR2` or later. - -Regitry Center Support:Zookeeper、Consul、Naocs、Eureka、Service Center - -**Notice**:The graceful online/offline capability is developed based on the default load balancing capability of SpringCloud. If you have implemented the custom load balancing capability, this capability is no longer applicable. - -## Usage - -### Enabling Graceful Online and Offline - -To use the graceful Online and Offline capability, you need to enable the capability. For details, see the [configuration file](../../../sermant-plugins/sermant-service-registry/config/config.yaml). If you have packed the Sermant or download Release package, the configuration file path is `${agent path}/agent/pluginPackge/service-registry/config/config.yaml` - -```yaml -grace.rule: - enableSpring: true # SpringCloud graceful online/offline switch - startDelayTime: 0 # Graceful online/offline start delay, unit is seconds - enableWarmUp: true # Whether to enable warm up - warmUpTime: 120 # Warm up time unit is seconds - enableGraceShutdown: true # Whether to enable graceful offline - shutdownWaitTime: 30 # The maximum waiting time before traffic detection is disabled. Unit: s. This parameter takes effect only after enabledGraceShutdown is enabled. - enableOfflineNotify: true # Whether to enable proactive offline notification. - httpServerPort: 16688 # Enable the http server port for proactive offline notification. - upstreamAddressMaxSize: 500 # Default size of the cache upstream address - upstreamAddressExpiredTime: 60 # Expiration time of the cached upstream address -``` - -In addition to the preceding configuration file mode, you can also configure environment variables or system parameters. For example, you can set the environment variable `-Dgrace.rule.enableSpring=true to enable` for configuration 'enableSpring'. - -### Use Graceful Online and Offline - -#### Virtual Machine Scenario - -Based your OS, start application with agent, in addition configure configuration which to enable graceful online/offline. - -```shell -# windows -java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -jar xxx.jar - -# mac, linux -java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=default -jar xxx.jar -``` - -Description of relevant identifiers: - -- ${path}: path indicates the actual agent path. Please replace it with the actual path. -- sermant-agent-x.x.x: x.x.x need be replaced with the actual Sermant version, for example, 1.0.0. -- xxx.jar: is your app package. Please replace it with your app package name. - -#### Container Scenario - -In container scenarios, you can quickly start using the `Sermant-Injector`. For details, see [Container-based Deployment](../injector.md). - -In addition, you need to modify the [deployment orchestration file](../injector.md#Deployment) by adding environment variables for graceful login and logout. The modified orchestration file is as follows: - -```yaml -apiVersion: v1 -kind: Deployment -metadata: - name: demo-test - labels: - app: demo-test -spec: - replicas: 1 - selector: - app: demo-test - matchLabels: - app: demo-test - template: - metadata: - labels: - app: demo-test - sermant-injection: enabled - spec: - containers: - - name: image - # Please replace it with own image - image: image:1.0.0 - ports: - - containerPort: 8080 - env: - - name: "grace_rule_enableSpring" - value: "true" - - name: "grace.rule.enableWarmUp" - value: "true" - - name: "grace_rule_enableGraceShutdown" - value: "true" - - name: "grace.rule.enableOfflineNotify" - value: "true" - ports: - - port: 443 - targetPort: 8443 -``` - -Then start application according to the containerization process . - -## Quick Start - -The following uses a simple demo to demonstrate how to verify graceful online/offline in a VM scenario. - -1. Environment Preparation - - (1)Download the JDK and configure the JDK environment. The JDK version must be 1.8 or later. Download the Maven and configure the Maven environment. - - (2)Download the latest Sermant release package. Click [here](https://github.com/huaweicloud/Sermant/releases) to download it. - - (3)Download the [Demo Source Code](https://github.com/huaweicloud/Sermant-examples/tree/main/grace-demo/spring-grace-nacos-demo) - - (4)Compile Demo - - ​ Run the following command to package the demo: - - ​ `mvn clean package` - - (5)Download nacos and start - - (6)Download and start the ZooKeeper (the sermant configuration center). - -2. Deploy - - We will deploy one consumer instance, two provider instances, and one data instance, as shown in the following figure: - - `consumer -----------> provider(two instances) -------------> data` - - The graceful online/offline are enabled for the consumer, the warm up and graceful offline are enabled for one provider instance, and only the graceful offline are enabled for the other provider instance. - - (1)Startup data - - ```shell - java -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -jar nacos-rest-data-2.2.0.RELEASE.jar - ``` - - (2)Start the first provider instance (port is 8880, with the **warm up disabled**). - - ```shell - # windows - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=false -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dgrace.rule.httpServerPort=16688 -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8880 -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -jar nacos-rest-provider-2.2.0.RELEASE.jar - - # mac, linux - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=false -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dgrace.rule.httpServerPort=16688 -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8880 -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=default -jar nacos-rest-provider-2.2.0.RELEASE.jar - ``` - - (3)Start the second provider instance (port is 8890, with the **warm up enabled**). - - ```shell - # windows - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dgrace.rule.httpServerPort=16689 -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8890 -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -jar nacos-rest-provider-2.2.0.RELEASE.jar - - # mac, linux - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dgrace.rule.httpServerPort=16689 -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8890 -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=default -jar nacos-rest-provider-2.2.0.RELEASE.jar - ``` - - (4)Startup consumer - - ```shell - # windows - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dgrace.rule.httpServerPort=16690 -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8800 -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -jar nacos-rest-consumer-2.2.0.RELEASE.jar - - # mac, linux - java -Dgrace.rule.enableSpring=true -Dgrace.rule.enableWarmUp=true -Dgrace.rule.enableGraceShutdown=true -Dgrace.rule.enableOfflineNotify=true -Dgrace.rule.httpServerPort=16690 -Dspring.cloud.nacos.discovery.server-addr=localhost:8848 -Dserver.port=8800 -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=default -jar nacos-rest-consumer-2.2.0.RELEASE.jar - ``` - -3. Verify warm up - - Request the `localhost:8800/graceHot` interface and check whether the preheating takes effect based on the IP address and port number returned by the interface. If the response contains port 8880 in the majority during the warm up period (120s by default), and the traffic is averaged over time, the warm up has taken effect. - -4. Verify graceful offline - - Continuously request the `localhost:8800/graceDownOpen` interface. Make one of the provider instances offline. Check whether occurs error in the request. If no error occurs, the graceful offline verification is successful. - -[Back to README of **Sermant** ](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/injector-zh.md b/docs/user-guide/injector-zh.md deleted file mode 100644 index d02ae8d066..0000000000 --- a/docs/user-guide/injector-zh.md +++ /dev/null @@ -1,180 +0,0 @@ -# 容器化部署指导手册 - -[简体中文](injector-zh.md) | [English](injector.md) - -k8s环境下,Sermant支持通过sermant-injector组件实现宿主应用自动挂载sermant-agent包的快速部署方式。本文档主要介绍sermant-injector模块以及上述部署方式的具体流程。 - -## sermant-injector模块介绍 -sermant-injector是基于Kubernetes准入控制器(Admission Controllers)特性开发而来。准入控制器位于k8s API Server中,能够拦截对API Server的请求,完成身份验证、授权、变更等操作。 - -sermant-injector属于变更准入控制器(MutatingAdmissionWebhook), 能够在创建容器资源前对请求进行拦截和修改。sermant-injector部署在k8s后,只需在宿主应用部署的YAML文件中`spec > template > metadata> labels`层级加入`sermant-injection: enabled`即可实现自动挂载sermant-agent。 - -### 组成部分 -`sermant-injector`文件夹下 - -- `deployment`,部署sermant-injector应用的helm包文件 - - `release` - - `injector` helm包,支持k8s 1.15版本及以上环境部署 -- `images` - - `injector` sermant-injector Dockerfile及镜像构建脚本 - - `sermant-agent` sermant-agent Dockerfile及镜像构建脚本 -- `scripts` 包含证书生成脚本等 -- `src` 项目代码 - -## 容器化部署流程 - -### 运行环境 -[Kubernetes 1.15+](https://kubernetes.io/) - -[Helm v3](https://helm.sh/) - -### 生成证书 -Kubernetes webhook只能通过HTTPS(SSL/TLS)调用,因此需要为sermant-injector生成ssl key和证书。 - -在k8s任一节点上任一目录下执行`scripts`下的`certificate.sh`脚本。 - -> 注意:脚本中`NAMESPACE`参数必须和`deployment/release`下的`values.yaml`中的`namespace.name`保持一致。其他参数无需修改 - -### 构建镜像 - -在部署sermant-injector前需要先构建sermant-agent镜像以及sermant-injector镜像。 - -#### sermant-agent镜像 - -##### 下载release包 - -点击 [here](https://github.com/huaweicloud/Sermant/releases)下载release包。 - -你也可以在项目中执行以下命令来打包: - -```shell -mvn clean package -Dmaven.test.skip -``` - -##### 制作镜像 - -修改文件夹 `images/sermant-agent`下`build-sermant-image.sh` 脚本中`sermantVersion`,`imageName`和`imageVerison`的值: - -> 1. `sermantVersion`为release包的版本 -> -> 2. `imageName`为构建的sermant-agent镜像名称 -> -> 3. `imageVerison`为构建的sermant-agent镜像版本 - -在k8s节点下,将`build-sermant-image.sh`和`Sermant.Dockerfile`置于release包`sermant-agent-xxx.tar.gz`同一目录下,执行`build-sermant-image.sh`脚本,完成sermant-agent镜像制作。 - -```shell -sh build-sermant-image.sh -``` - -#### sermant-injector镜像 - -##### sermant-injector打包 - -在sermant-injector项目下执行`mvn clean package`命令,在项目目录下生成`sermant-injector.jar`文件 - -##### 制作镜像 - -修改文件夹 `images/injector`下`build-injector-image.sh` 脚本中`imageName`和`imageVerison`的值: - -> 1. `imageName`为构建的sermant-injector镜像名称 -> 2. `imageVerison`为构建的sermant-injector镜像版本 - -在k8s节点下,将`build-injector-image.sh`、`start.sh`和`Injector.Dockerfile`置于sermant-injector包`sermant-injector.jar`同一目录下,执行`build-injector-image.sh`脚本,完成sermant-injector镜像制作。 - -```shell -sh build-injector-image.sh -``` - -### 部署sermant-injector实例 - -在宿主应用容器化部署前,需要先部署sermant-injector实例。本项目采用Helm进行Kubernetes包管理。 - -使用`deploment/release`下的`injector`Chart模版。 - -按实际环境修改`values.yaml`中的模版变量: - -> 1. `namespace.name`变量与`certificate.sh`中的`NAMESPACE`参数必须保持一致 -> -> 2. `agent.image.addr`和`injector.image.addr`变量与构建镜像时的镜像地址保持一致 -> -> 3. `injector.webhook.caBundle`变量为k8s证书,可在k8s节点执行以下命令获取: -> -> ```shell -> kubectl config view --raw --minify --flatten -o jsonpath='{.clusters[].cluster.certificate-authority-data}' -> ``` - -完成后,执行`helm install`命令在k8s中部署sermant-injector实例: - -```shell -helm install sermant-injector ../injector -``` - -检查sermant-injector部署pod状态为running。 - -至此,宿主应用部署前的环境配置工作完成。 - -### 部署宿主应用 - -#### 部署 - -在完成上述sermant-injector部署后,用户根据实际应用编写YAML部署K8s Deployment资源,只需在`spec > template > metadata> labels`层级加入`sermant-injection: enabled`即可实现自动挂载sermant-agent。(如后续不希望挂载,删除后重新启动应用即可) - -```yaml -apiVersion: v1 -kind: Deployment -metadata: - name: demo-test - labels: - app: demo-test -spec: - replicas: 1 - selector: - app: demo-test - matchLabels: - app: demo-test - template: - metadata: - labels: - app: demo-test - sermant-injection: enabled - spec: - containers: - - name: image - # 请替换成您的应用镜像 - image: image:1.0.0 - ports: - - containerPort: 8080 - ports: - - port: 443 - targetPort: 8443 -``` - -若pod无法创建,请检查sermant-injector是否正确部署以及sermant-agent镜像是否正确构建。 - -#### 验证 - -pod创建成功后,执行如下命令,其中`${pod_name}`为宿主应用的pod名称 - -```shell -kubectl get po/${pod_name} -o yaml -``` - -1. 查看上述命令输出内容`spec > containers > - env`下是否包含环境变量:name为`JAVA_TOOL_OPTIONS`,value为 `-javaagent:/home/sermant-agent/agent/sermant-agent.jar=appName=default`。 - -2. 查看上述命令输出内容`spec > containers > initContainers > image` 的值是否为构建sermant-agent镜像时的镜像地址。 - -执行如下命令,其中`${pod_name}`为用户应用的pod名称,`${namespace}`为用户部署应用的namespace名称 - -```shell -kubectl logs ${pod_name} -n ${namespace} -``` - -3. 查看上述命令输出内容pod日志开头部分是否包含: - -``` -[INFO] Loading sermant agent... -``` - -如果上述信息无误,则表明sermant-agent已成功挂载至用户应用中。 - diff --git a/docs/user-guide/injector.md b/docs/user-guide/injector.md deleted file mode 100644 index 2960b0ddd1..0000000000 --- a/docs/user-guide/injector.md +++ /dev/null @@ -1,180 +0,0 @@ -# Containerized Deployment Guide - -[简体中文](injector-zh.md) | [English](injector.md) - -In Kubernetes environment, Sermant supports quickly deployment by using **sermant-injector** module to automatically mount sermant-agent package for host application. This document describes the **sermant-injector** module and how to deploy **sermant-injector** and **host application with sermant-agent** in k8s environment. - -## Sermant-injector -Sermant-injector is based on the **Kubernetes Admission Controllers.** The admission controller is located in the K8s API Server and is able to intercept requests to the API Server to complete operations such as authentication, authorization, and mutation. - -Sermant-injector is a MutatingAdmissionWebhook that can intercept and modify requests before creating container resources. After sermant-injector is deployed on K8s, just add `sermant-injection:Enabled` to the YAML file of the host application deployment configuration at the `spec > Template > metadata> labels` ' then the host application can automatically mount the sermant-agent package. - -### Components -`sermant-injector` contains: - -- `deployment`, contains helm package file for deploying the sermant-injector application. - - `release` - - `injector` contains helm package file for K8S 1.15+. -- `images` - - `injector`, contains dockerfile and image build script of **sermant-injector**. - - `sermant-agent`, contains dockerfile and image build script of **sermant-agent**. -- `scripts`, contains certificate generation scripts, etc. -- `src`, contains source code. - -## Containerized Deployment Steps - -### **Runtime Environment** -[Kubernetes 1.15+](https://kubernetes.io/) - -[Helm v3](https://helm.sh/) - -### Generate a Certificate for Sermant-injector - -The Kubernetes webhook can only be invoked over HTTPS(SSL/TLS), so the SSL key and certificate need to be generated for the sermant-injector. - -Execute the `certificate.sh` script under `scripts` in any directory of any K8s node. - -> NOTE:The parameter `NAMESPACE` must be set as the same value as `namespace.name` in `values.yaml` under `deployment/release`. No need to modify other parameters. - -### Build Images - -Before deploying **sermant-injector**, you need to build the **sermant-agent** image and the **sermant-injector** image. - -#### Image of Sermant-agent - -##### Download release package - -Click [here](https://github.com/huaweicloud/Sermant/releases) to download latest release package `sermant-agent-x.x.x.tar.gz`. - -Or you can get above package by executing the following command in the project. - -```shell -mvn clean package -Dmaven.test.skip -``` - -##### Build Image - -Modify the values of `sermantVersion`, `imageName` and `imageVerison` in the `build-sermant-image.sh` under `images/sermant-agent` folder: - -> 1. `sermantVersion` is the version of the release package. -> -> 2. `imageName` is the name of the built sermant-agent image. -> -> 3. `imageVerison` is the version for the built sermant-agent image. - -Move `build-sermant-image.sh` and `Sermant.dockerfile` to the same directory as the release package `sermant-agent-xxx.tar.gz` in one of K8s nodes. Run `build-sermant-image.sh` to build the sermant-agent image. - -```shell -sh build-sermant-image.sh -``` - -#### Image of Sermant-injector - -##### Package Sermant-injector - -Execute the `mvn clean package` command to generate the `sermant-injector.jar` file in the directory of sermant-injector project. - -##### Build Image - -Modify the values of `imageName` and `imageVerison` in the `build-injector-image.sh` script under `images/injector` folder: - -> 1. `imageName` is the name of the built image of sermant-injector. -> 2. `imageVerison` is the version of the built image of sermant-injector. - -Move `build-injector-image.sh`, `start.sh` and `Injector.Dockerfile` to the same directory as the package `sermant-injector.jar`. Run `build-injector-image.sh` to create the sermant-injector image. - -```shell -sh build-injector-image.sh -``` - -### Deploy Workload of Sermant-injector - -Before the host application can be containerized, the workload of sermant-injector needs to be deployed. This project adopts Helm for Kubernetes package management. - -Use Chart template in`injector` under `deploment/release`. - -Modify the template variable in `values.yaml` according to the actual environment: - -> 1. The value of `namespace.name` must be identical to the `NAMESPACE` in `certificate.sh` -> -> 2. The values of `agent.image.addr` and `injector.image.addr` are the same as the image address when the images are built -> -> 3. `injector.webhook.caBundle` is the K8s certificate, which can be obtained from the K8s node by executing the following command: -> -> ```shell -> kubectl config view --raw --minify --flatten -o jsonpath='{.clusters[].cluster.certificate-authority-data}' -> ``` - -Once this is done, execute `helm install` to deploy the sermant-injector workload in K8s: - -```shell -helm install sermant-injector ../injector -``` - -Check that the status of the deployed pod of sermant-injector is running. - -At this point, the environment configuration of the host application before deployment is complete. - -### Deploy Host Application - -#### Deployment - -After the deployment of above sermant-injector, developers should write YAML file to deploy K8s Deployment resources according to the actual application. Simply add `sermant-injection: enabled` at the `spec > Template > Metadata > Labels` to automatically mount the sermant-agent. (If you do not want to mount it later, just delete it and restart the application) - -```yaml -apiVersion: v1 -kind: Deployment -metadata: - name: demo-test - labels: - app: demo-test -spec: - replicas: 1 - selector: - app: demo-test - matchLabels: - app: demo-test - template: - metadata: - labels: - app: demo-test - sermant-injection: enabled - spec: - containers: - - name: image - # Please replace it with own image - image: image:1.0.0 - ports: - - containerPort: 8080 - ports: - - port: 443 - targetPort: 8443 -``` - -If the pod cannot be created, check that the sermant-injector is deployed correctly and that the sermant-agent image is built correctly. - -#### Verification - -Once the pod is created, execute the following command, where `${pod_name}` is the pod name of host application. - -```shell -kubectl get po/${pod_name} -o yaml -``` - -1. Check if the output contains the environment variable whose name is `JAVA_TOOL_OPTIONS`and value is `-javaagent:/home/sermant-agent/agent/sermant-agent.jar=appName=default` in `spec > containers > - env`. - -2. Check if the value of `spec > containers > initContainers > image` is the image address used to build the sermant-agent image. - -Execute the following command, where `${pod_name}` is the pod name of host application and `${namespace}` is the namespace name of deployed host application. - -```shell -kubectl logs ${pod_name} -n ${namespace} -``` - -3. Check if the beginning of the pod log in the output of the above command contains: - -``` -[INFO] Loading sermant agent... -``` - -If the above information is correct, the sermant-agent has been successfully mounted into the host application. diff --git a/docs/user-guide/loadbalancer/document-zh.md b/docs/user-guide/loadbalancer/document-zh.md deleted file mode 100644 index 35740b2522..0000000000 --- a/docs/user-guide/loadbalancer/document-zh.md +++ /dev/null @@ -1,181 +0,0 @@ -# 负载均衡 - -[简体中文](document-zh.md) | [English](document.md) - -该文档主要介绍[负载均衡插件](../../../sermant-plugins/sermant-loadbalancer)的使用方法 - -## 功能: - -根据配置中心的配置,无侵入地动态修改宿主应用的负载均衡策略。 - -## 负载均衡策略支持一览 - -| 框架类型 | 策略名 | 配置值 / 负载均衡策略 | 版本支持 | -| --------------------------- | ---------------------------- | ---------------------------------------------- | ------------------------------------------------------------ | -| dubbo | 随机(dubbo默认) | Random / RANDOM | 2.6.x, 2.7.x | -| dubbo | 轮询 | RoundRobin / ROUNDROBIN | 2.6.x, 2.7.x | -| dubbo | 最少活跃 | leastActive / LEASTACTIVE | 2.6.x, 2.7.x | -| dubbo | 一致性HASH | consistentHash / CONSISTENTHASH | 2.6.x, 2.7.x | -| dubbo | 最短响应时间 | shortestResponse / SHORTESTRESPONSE | 2.7.7+ | -| spring-cloud-netflix-ribbon | 区域权重(ribbon默认) | zoneAvoidance / ZONE_AVOIDANCE | ZONE_AVOIDANCEspring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | 随机 | Random / RANDOM | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | 轮询 | RoundRobin / ROUND_ROBIN | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | 重试 | retry / RETRY | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | 最低并发 | bestAvailable / BEST_AVAILABLE | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | 筛选过滤轮询 | availabilityFiltering / AVAILABILITY_FILTERING | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | 响应时间加权重(Deprecated) | ResponseTimeWeighted / RESPONSE_TIME_WEIGHTED | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | 响应时间加权重 | weightedResponseTime / WEIGHTED_RESPONSE_TIME | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-loadbalancer | 轮询(loadbalancer默认) | RoundRobin / ROUND_ROBIN | spring cloud Hoxton.SR10+, spring cloud 2020.0.x, spring cloud 2021.0.x | -| spring-cloud-loadbalancer | 随机 | Random / RANDOM | spring cloud Hoxton.SR10+, spring cloud 2020.0.x, spring cloud 2021.0.x | - -## 配置说明 - -负载均衡基于配置中心进行动态配置,因此使用该能力需在配置中心配置对应负载均衡策略。负载均衡插件采用**流量标记+负载均衡规则**的方式规则,即配置一条规则需**同时配置两者**,下面分别介绍两项配置: - -### 流量标记 - -流量标记用于标记当前针对那些服务生效,若服务为空,则会应用与所有微服务,配置示例如下: - -**配置key:** `servicecomb.matchGroup.testLb` - -> 配置键说明: -> -> `servicecomb.matchGroup. `:流量标记的固定前缀,所有key均需已此为前缀配置流量标记 -> -> `testLb`:业务场景名,对应的负载均衡规则需配置相同的业务场景名 - -**配置content:** - -```yaml -alias: loadbalancer-rule -matches: -- serviceName: zk-rest-provider # 目标服务名 -``` - -示例规则说明: `serviceName`为下游服务名,即针对请求微服务`zk-rest-provider`将应用匹配的负载均衡规则;若配置项`serviceName`未配置,则应用于所有微服务。需要注意的是,该配置仅需配置`serviceName`配置项,其他的格式需保持不变。 - -> 优先级说明:若同时配置了多个负载均衡规则,插件会优先匹配配置服务名的负载均衡规则,否则采用未配置服务名的匹配的负载均衡规则。 - -### 负载均衡规则 - -负载均衡规则需为应用配置具体的负载均衡策略,负载均衡策略目前完全依赖与宿主本身存在的负载均衡策略,即宿主本身支持才可配置,支持列表见[负载均衡策略支持一览](#负载均衡策略支持一览)。 - -**配置key:**`servicecomb.loadbalance.testLb` - -> 配置键说明: -> -> `servicecomb.loadbalance. `:负载均衡规则配置的固定前缀,所有key均需已此为前缀配置负载均衡规则 -> -> `testLb`:业务场景名,需与流量标记的业务场景相同才可生效 - -**配置content:** - -```yaml -rule: Random -``` - -示例配置项说明: 即配置**随机负载均衡规则**, 配置值见表[负载均衡策略支持一览](#负载均衡策略支持一览)的**配置值** - -> 以上需确认宿主自身应用的框架版本,确定当前支持的负载均衡策略。 - -### 发布配置 - -Sermant backend提供api的方式发布配置, 使用前需启动backend后台应用,如下为配置发布接口: - -**URL** - -POST /publishConfig - -**请求Body** - -| 参数 | 是否必填 | 参数类型 | 描述 | -| ------- | -------- | -------- | ---------------------- | -| key | √ | String | 配置键 | -| group | √ | String | 配置组,用于配置订阅 | -| content | √ | String | 配置文本,即为具体规则 | - -其中上表中`key`与`content`对应流量标记与负载均衡规则的配置key与配置content,而group则是针对指定服务的标签,group的配置采用标签对的模式进行配置,例如app=default&environment=development即对同时订阅该标签的微服务发布配置。 - -负载均衡插件默认会存在三种订阅标签: - -- 自定义标签:默认会订阅标签`public=default`,您也可以通过设置环境变量修改自定义标签,启动参数添加如下参数:`-Dservice.meta.customLabel=public -Dservice.meta.customLabelValue=default` -- 微服务标签: 默认会订阅标签`app=default&service=${yourServiceName}&environment=`,其中`${yourServiceName}`为微服务的名称,`environment`默认为空。当然同样可以采用环境变量进行变更,启动参数添加如下参数:`-Dservice.meta.application=default -Dservice.meta.environment=${yourEnvironment}`, 分别对应`app`与`envrionment`,而服务名为动态获取。 -- 应用标签:默认会订阅标签`app=default&&environment=`, `environment`默认为空, 环境变量配置方式同**微服务标签**。 - -### 版本说明 - -- 在spring cloud 2020.0.x之前,spring cloud负载均衡默认使用的核心组件为spring-cloud-netflix-ribbon(宿主应用可通过排除ribbon相关的组件使用spring-cloud-loadbalancer组件),从spring cloud 2020.0.x开始,负载均衡的核心组件为spring-cloud-loadbalancer。 - -- 在spring cloud Hoxton.SR10之前,spring-cloud-loadbalancer的负载均衡策略只有轮询(ROUND_ROBIN),所以插件并不支持修改Hoxton. SR10之前的spring-cloud-loadbalancer组件的负载均衡策略,spring cloud Hoxton.SR10之前版本建议使用spring-cloud-netflix-ribbon组件进行负载均衡。 - -## 结果验证 - -1. 前提条件[已下载Sermant RELEASE包](https://github.com/huaweicloud/Sermant/releases), [已下载demo源码](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-register),[已下载zookeeper](https://zookeeper.apache.org/releases.html#download) - -2. 启动zookeeper - -3. 启动backend, 参考[后端模块介绍](../backend-zh.md) - -4. 编译demo应用 - - ``` - mvn clean package - ``` - - - -5. 发布流量标记 - - 调用接口`localhost:8900/publishConfig`, 请求参数如下: - - ```json - { - "content": "alias: loadbalancer-rule\nmatches:\n- serviceName: zk-rest-provider", - "group": { - "app": "default", - "environment": "", - "service": "zk-rest-consumer" - }, - "key": "servicecomb.matchGroup.testLb" - } - ``` - - - -6. 发布匹配的负载均衡规则(以Random为例) - - 调用接口`localhost:8900/publishConfig`, 请求参数如下: - - ```json - { - "content": "rule: Random", - "group": { - "app": "default", - "environment": "", - "service": "zk-rest-consumer" - }, - "key": "servicecomb.loadbalance.testLb" - } - ``` - - - -7. 启动生产者(两个实例) - - ```shell - java -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -Dserver.port=${port} -jar zk-rest-provider.jar - ``` - - 其中`path`需要替换为Sermant实际打包路径, `port`为生产者端口,这里需要启动两个实例, 请分别配置不同的端口,有利于结果观察 - -8. 启动消费者(一个实例即可) - - ```shell - java -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -Dserver.port=8005 -jar zk-rest-consumer.jar - ``` - -9. 测试 - - 上面步骤全部完成后,访问接口`localhost:8005/hello`, 通过返回的端口判断随机负载均衡规则(默认为轮询)是否生效。 - -[返回**Sermant**说明文档](../../README-zh.md) diff --git a/docs/user-guide/loadbalancer/document.md b/docs/user-guide/loadbalancer/document.md deleted file mode 100644 index 2e0210a6e6..0000000000 --- a/docs/user-guide/loadbalancer/document.md +++ /dev/null @@ -1,181 +0,0 @@ -# Loadbalancer - -[简体中文](document-zh.md) | [English](document.md) - -This document is used to introduce the usage of [loadbalancer](../../../sermant-plugins/sermant-loadbalancer) - -## Functions: - -Based on the configuration in the configuration center, the loadbalance rules of the host application can be dynamically modified without intrusion. - -## The Strategy Loadbalacne Support - -| Framework | Strategy | Configuration value/Loadbalance Strategy | version support | -| --------------------------- | ------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------ | -| dubbo | Random (Dubbo default) | Random / RANDOM | 2.6.x, 2.7.x | -| dubbo | RoundRobin | RoundRobin / ROUNDROBIN | 2.6.x, 2.7.x | -| dubbo | leastActive | leastActive / LEASTACTIVE | 2.6.x, 2.7.x | -| dubbo | Consistent hash | consistentHash / CONSISTENTHASH | 2.6.x, 2.7.x | -| dubbo | Minimum response time | shortestResponse / SHORTESTRESPONSE | 2.7.7+ | -| spring-cloud-netflix-ribbon | Area weight (default value) | zoneAvoidance / ZONE_AVOIDANCE | ZONE_AVOIDANCEspring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | Random | Random / RANDOM | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | RoundRobin | RoundRobin / ROUND_ROBIN | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | retry | retry / RETRY | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | bestAvailable | bestAvailable / BEST_AVAILABLE | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | availabilityFiltering | availabilityFiltering / AVAILABILITY_FILTERING | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | Response Time Weighting (Deprecated) | ResponseTimeWeighted / RESPONSE_TIME_WEIGHTED | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-netflix-ribbon | Response time weighting | weightedResponseTime / WEIGHTED_RESPONSE_TIME | spring cloud Edgware.x, spring cloud Finchley.x, spring cloud Greenwich.x, spring cloud Hoxton.x | -| spring-cloud-loadbalancer | RoundRobin(default) | RoundRobin / ROUND_ROBIN | spring cloud Hoxton.SR10+, spring cloud 2020.0.x, spring cloud 2021.0.x | -| spring-cloud-loadbalancer | Random | Random / RANDOM | spring cloud Hoxton.SR10+, spring cloud 2020.0.x, spring cloud 2021.0.x | - -## How to Configure - -Load balancing is dynamically configured based on the configuration center. To use this capability, you need to configure the corresponding load balancing policy in the configuration center. The loadbalance plugin uses **traffic marking + loadbalance rules**. To configure a rule, you **need to configure both of them**. The following describes the two configurations: - -### Traffic Marking - -Traffic marking is used to mark the services that take effect. If the service is empty, the traffic marking is applied to all microservices. The configuration example is as follows: - -**Configuring key:** `servicecomb.matchGroup.testLb` - -> description of key: -> -> `servicecomb.matchGroup. `:Fixed prefix of traffic marking. Traffic marking must be configured for all keys. -> -> `testLb`:Service scenario name. The corresponding load balancing rule must be configured with the same service scenario name. - -**configure content:** - -```yaml -alias: loadbalancer-rule -matches: -- serviceName: zk-rest-provider # downstream service name -``` - -Example rule description: serviceName indicates the name of the downstream service, that is, the loadbalance rule to be applied to the requested microservice zk-rest-provider. If the serviceName configuration item is not set, the configuration item applies to all microservices. Note that only the serviceName configuration item needs to be configured in this configuration. Other formats remain unchanged. - -> Priority: If multiple load balancing rules are configured, the plugin preferentially matches the load balancing rule with the service name configured. Otherwise, the plugin uses the load balancing rule with no service name configured. - -### Loadbalance Rule - -Load balancing rules must be configured for applications. Load balancing policies depend on the existing load balancing policies of the host. That is, load balancing policies can be configured only when the host supports the load balancing policies. For details about the supported load balancing policies, see the [The Strategy Loadbalacne Support](#The-Strategy-Loadbalacne-Support). - -**configure key:**`servicecomb.loadbalance.testLb` - -> configuration item description: -> -> `servicecomb.loadbalance. `:Fixed prefix configured for the loadbalancer rule. Loadbalancer rules must be configured for all keys. -> -> `testLb`:Service scenario name, which takes effect only when it is the same as the service scenario of the traffic flag. - -**configure content:** - -```yaml -rule: Random -``` - -Example configuration item description: Configure a random load balancing rule. For details about the configuration values, see the [The Strategy Loadbalacne Support](#The-Strategy-Loadbalacne-Support). - -> Check the framework version of the host application and determine the supported load balancing strategy. - -### Publish Loadbalance Rule - -The Sermant Backend provides APIs for releasing configurations. Before using the API, you need to start the backend application. The following describes the configuration publishing interface: - -**URL** - -POST /publishConfig - -**Request Body** - -| Params | Mandatory or not | Param type | Description | -| ------- | ---------------- | ---------- | ------------------------------------------------------------ | -| key | √ | String | configuration key | -| group | √ | String | Configuration group, which is used to configure subscriptions | -| content | √ | String | Configuration text, that is, specific rules | - -In the preceding table, the key and content correspond to the key and content of the traffic tag and load balancing rule. The group refers to the tag of the specified service. The group is configured in the tag pair mode. For example, app=default&environment=development indicates publishing configurations for microservices that subscribe to this tag. - -The loadbalance plugin has three subscription tags by default.: - -- custom tag:By default, the tag `public=defaul`t is subscribed to. You can also modify the customized tag by setting environment variables and add the following parameters to the startup parameter: `-Dservice.meta.customLabel=public -Dservice.meta.customLabelValue=default` -- microservice tag: By default, the `app=default&service=${yourServiceName}&environment= tag is subscribed. ${yourServiceName}` indicates the microservice name and environment is empty by default. You can also use environment variables to change the startup parameters. Add the following parameters to the startup parameters: `-Dservice.meta.application=default -Dservice.meta.environment=${yourEnvironment}`, corresponds to app and envrionment, and the service name is dynamically obtained. -- application tag:By default, the tag `app=default&environment=` is subscribed. The environment variable configuration method is the same as that of the microservice tag. - -### Version Notices - -- In versions earlier than spring cloud 20200.0.x, the core component used by spring cloud load balancers is spring-cloud-netflix-ribbon by default. (The host application can use the spring-cloud-loadbalancer component by excluding ribbon-related components.) From spring cloud 20200.0.x, the core component of load balancing is spring-cloud-loadbalancer. - -- In versions earlier than spring cloud Hoxton.SR10, the load balancing policy of spring-cloud-loadbalancer can only be round robin (ROUND_ROBIN). Therefore, the plugin does not support modifying the load balancing policy of spring-cloud-loadbalancer components earlier than Hoxton.SR10. For versions earlier than spring cloud Hoxton.SR10, you are advised to use the spring-cloud-netflix-ribbon component for load balancing. - -## Verify Result - -1. Prerequisites: [sermant has been downloaded](https://github.com/huaweicloud/Sermant/releases), [the demo source code is downloaded](https://github.com/huaweicloud/Sermant-examples/tree/main/sermant-template/demo-register), and [the ZooKeeper is downloaded](https://zookeeper.apache.org/releases.html#download). - -2. start zookeeper - -3. start backend, referring to the [backend module introduction](../backend.md) - -4. compile and package demo application - - ``` - mvn clean package - ``` - - - -5. publish traffic marking rule - - Invoke the interface `localhost:8900/publishConfig`, request body just follow below: - - ```json - { - "content": "alias: loadbalancer-rule\nmatches:\n- serviceName: zk-rest-provider", - "group": { - "app": "default", - "environment": "", - "service": "zk-rest-consumer" - }, - "key": "servicecomb.matchGroup.testLb" - } - ``` - - - -6. publish loadbalance rule (Random as a example). - - Invoke the interface`localhost:8900/publishConfig`, request body just follow below: - - ```json - { - "content": "rule: Random", - "group": { - "app": "default", - "environment": "", - "service": "zk-rest-consumer" - }, - "key": "servicecomb.loadbalance.testLb" - } - ``` - - - -7. Starting a provider (two instances) - - ```shell - java -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -Dserver.port=${port} -jar zk-rest-provider.jar - ``` - - Replace `path` with the **actual packaging path** of the Sermant and port with the producer port. In this example, you need to start two instances. Configure different ports for the two instances. - -8. Start a consumer (one instance). - - ```shell - java -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=default -Dserver.port=8005 -jar zk-rest-consumer.jar - ``` - -9. testing - - After the preceding steps are complete, access the localhost:8005/hello interface and check whether the random load balancing rule (by default, RoundRobin) takes effect based on the returned port. - -[Back to README of **Sermant** ](../../README.md) diff --git a/docs/user-guide/monitor/document-zh.md b/docs/user-guide/monitor/document-zh.md deleted file mode 100644 index b3e805e68c..0000000000 --- a/docs/user-guide/monitor/document-zh.md +++ /dev/null @@ -1,177 +0,0 @@ -# monitor - -本文档主要用于[monitor模块](../../../sermant-plugins/sermant-monitor)的使用说明 - -资源监控模块用于监控宿主应用所在服务器的CPU、内存、磁盘IO和网络IO等硬件资源的使用情况,以及宿主应用Java虚拟机的使用情况。 -监控模块依赖于prometheus进行指标收集,prometheus定期调用java agent的httpServer服务,获取插件注册的指标信息,并进行存储展示。 - -## 目录说明 - -- `config`: 配置文件目录 -- `monitor-service`: 服务器硬件资源和JVM监控采集服务 - -## 配置文件内容说明 -```yaml -monitor.config: # 监控服务配置 - enable-start-service: false # 监控服务启动开关 -``` - -## monitor-service插件说明 - -*使用背景* - -本服务包含两个采集子服务,分别为Linux资源监控采集、JVM资源监控 - -- Linux资源监控采集功能需要宿主应用部署在Linux环境。 -- JVM内存监控采集功能需要宿主应用使用OpenJDK或者基于OpenJDK的JDK版本 - -*功能说明* - -- **Linux资源监控采集**:通过执行linux命令获取系统CPU、内存、磁盘IO、网络IO资源使用情况数据,并注册到prometheus的默认注册器。 -```shell - #CPU - cat /proc/stat - #MEMORY - cat /proc/meminfo - #DISK - cat /proc/diskstats - #NETWORK - cat /proc/net/dev - #CPU CORE - lscpu - ``` -- **采集内容** -``` - CPU - double cpu_user; // 用户态时间占比 - double cpu_sys; // 系统时间占比 - double cpu_wait; // 等待时间百分占比 - double cpu_idle; // 空闲时间占比 - double cpu_cores; // CPU物理核心数 -``` - -``` - 内存使用情况 - double memory_total; // 总内存大小 - double memory_swap; // 对应cat /proc/meminfo指令的SwapCached - double memory_cached; // 对应cat /proc/meminfo指令的Cached - double memory_buffer; // 对应cat /proc/meminfo指令的Buffers - double memory_used; // 已使用的内存大小 -``` - -``` - 内存使用情况 - double memory_total; // 总内存大小 - double memory_swap; // 对应cat /proc/meminfo指令的SwapCached - double memory_cached; // 对应cat /proc/meminfo指令的Cached - double memory_buffer; // 对应cat /proc/meminfo指令的Buffers - double memory_used; // 已使用的内存大小 -``` - -``` - 磁盘IO - double disk_readBytesPerSec; // 采集周期内的每秒读字节数 - double disk_writeBytesPerSec; // 采集周期内的每秒写字节数 - double disk_ioSpentPercentage; // 采集周期内,IO花费的时间百分占比 -``` - -``` - 网络 - double network_readBytesPerSec; // 采集周期内的每秒读字节数 - double network_writeBytesPerSec; // 采集周期内的每秒写字节数 - double network_readPackagePerSec; // 采集周期内的每秒读包数 - double network_writePackagePerSec; // 采集周期内的每秒写包数 -``` - -- **JVM监控采集**:定时从java.lang.management.ManagementFactory获取JVM的指标情况 - -``` - JVM内存 - double heap_memory_init; // 堆内存初始化值 - double heap_memory_max; // 堆内存最大值 - double heap_memory_used // 堆内存已使用 - double heap_memory_committed // 堆内存已提交 - - double non_heap_memory_init; // 非堆内存初始化值 - double non_heap_memory_max; // 非堆内存最大值 - double non_heap_memory_used // 非堆内存已使用 - double non_heap_memory_committed // 非堆内存已提交 - - double code_cache_init; // 代码缓存区初始化值 - double code_cache_max; // 代码缓存区最大值 - double code_cache_used // 代码缓存区已使用 - double code_cache_committed // 代码缓存区已提交 - - double meta_sapce_init; // 元空间初始化值 - double meta_sapce_max; // 元空间最大值 - double meta_sapce_used // 元空间已使用 - double meta_sapce_committed // 元空间已提交 - - double compressed_class_space_init; // 压缩类空间初始化值 - double compressed_class_space_max; // 压缩类空间最大值 - double compressed_class_space_used // 压缩类空间已使用 - double compressed_class_space_committed // 压缩类空间已提交 - - double eden_init; // eden区内存初始化值 - double eden_max; // eden区内存最大值 - double eden_used // eden区内存已使用 - double eden_committed // eden区内存已提交 - - double survivor_init; // survivor区内存初始化值 - double survivor_max; // survivor区内存最大值 - double survivor_used // survivor区内存已使用 - double survivor_committed // survivor区内存已提交 - - double old_gen_init; // 老年代内存初始化值 - double old_gen_max; // 老年代内存最大值 - double old_gen_used // 老年代内存已使用 - double old_gen_committed // 老年代内存已提交 -``` - -``` - 线程 - double thread_live; // 活动线程 - double thread_peak; // 线程峰值 - double thread_daemon; // 守护线程 -``` - -``` - GC - double new_gen_count; // 年轻代GC次数 - double new_gen_spend; // 年轻代GC耗时 - double old_gen_count; // 老年代GC次数 - double old_gen_spend; // 老年代GC耗时 -``` - -``` - JVM其他指标 - double cpu_used; JVM占用CPU情况 - double start_time; JVM已经启动时间,毫秒数 -``` - -*使用说明* - -1、修改sermant-agentcore-config监控配置--config.properties。修改对外提供服务的IP 端口 以及开关 -```yaml -monitor.service.address=127.0.0.1 // 修改为宿主服务IP -monitor.service.port=12345 // 修改为对外提供服务端口 -monitor.service.isStartMonitor=false // 对外服务开关 -- 开关true时prometheus可以调用服务端口获取指标信息 -``` - -2、修改sermant-monitor的配置文件--config.properties。 -```yaml -monitor.config: # 监控服务配置 - enable-start-service: false # 监控服务启动开关 -``` -修改enable-start-service为true - -3、修改prometheus的配置文件. 在scrape_configs下增加对应的job信息(根据第一步配置的内容) - -4、宿主应用挂载java agent之后即可在prometheus看到对应的指标信息。 - - - - - - - diff --git a/docs/user-guide/registry/FAQ-zh.md b/docs/user-guide/registry/FAQ-zh.md deleted file mode 100644 index 875ed4e1c2..0000000000 --- a/docs/user-guide/registry/FAQ-zh.md +++ /dev/null @@ -1,102 +0,0 @@ -# 服务注册常见问题 - -[简体中文](FAQ-zh.md) | [English](FAQ.md) - -本文主要介绍[服务注册插件](../../../sermant-plugins/sermant-service-registry)在使用时遇到的常见问题。 - -## 报错:No such extension org.apache.dubbo.registry.RegistryFactory by name sc - -如下图所示: - -![No such extension org.apache.dubbo.registry.RegistryFactory by name sc](../../binary-docs/registry-faq-1.png) - -该错误原因有以下3种: - -1.1 宿主没有带agent启动。因为原生dubbo并不支持往sc注册,所以如果没带agent启动且配置的注册地址的协议为sc时,就会产生以上报错。 - -1.2 核心配置文件(${agent_package_path}/agent/config/config.properties)配置问题。仔细观察启动日志,会发现伴有类似以下的错误: - -![核心配置文件错误](../../binary-docs/registry-faq-2.png) - -- 原因是核心配置文件中,配置中心类型(dynamic.config.dynamic_config_type)的值(需要为KIE/ZOOKEEPER)配置错误,从而导致宿主应用无法加载agent,最后导致No such extension org.apache.dubbo.registry.RegistryFactory by name sc的报错。 - -1.3 核心配置文件(${agent_package_path}/agent/config/config.properties)配置问题。仔细观察启动日志,会发现伴有类似以下错误: - -![核心配置文件错误](../../binary-docs/registry-faq-3.png) - -- 原因是核心配置文件中,配置中心地址(dynamic.config.server_address)配置错误或者配置中心没有启动或者网络不通,从而导致宿主应用无法加载agent,最后导致No such extension org.apache.dubbo.registry.RegistryFactory by name sc的报错。 - -## 报错:/sermant/master/v1/register error - -如下图所示: - -![register error](../../binary-docs/registry-faq-4.png) - -原因是backend未启动或者配置地址不正确,请启动backend或正确配置地址。backend相关信息请见[backend文档](../backend-zh.md)。 - -注:该错误不会影响注册插件的流程,但会有相关报错。 - -## 报错:Connection reset - -如下图所示: - -![Connection reset](../../binary-docs/registry-faq-5.png) - -请检查插件配置(${agent_package_path}/agent/pluginPackage/service-registry/config/config.yaml)中,注册中心地址(servicecomb.service.address)是否正确,协议是否正确(http/https)。 - -## 报错:https protocol is not supported - -如下图所示: - -![https protocol is not supported](../../binary-docs/registry-faq-6.png) - -需要在插件配置(${agent_package_path}/agent/pluginPackage/service-registry/config/config.yaml)中,开启ssl(servicecomb.service.sslEnabled)。 - -## 报错:No such extension org.apache.dubbo.metadata.report.MetadataReportFactory by name sc - -如下图所示: - -![No such extension org.apache.dubbo.metadata.report.MetadataReportFactory by name sc](../../binary-docs/registry-faq-7.png) - -请检查dubbo应用的注册配置,protocol是否存在且不为sc,如下所示: - -- 例如dubbo/provider.xml - -```xml - -``` - -- 例如application.yml(或application.properties),以application.yml为例 -```yml -dubbo: - registry: - protocol: nacos - address: sc://127.0.0.1:30100 -``` - -如果protocol存在且不为sc,请把protocol的值设置成sc,或者删除protocol配置。 - -## 报错:No registry config found or it's not a valid config - -如下图所示: - -![No registry config found or it's not a valid config](../../binary-docs/registry-faq-8.png) - -需要设置dubbo本身注册中心地址的配置,请参考[服务注册插件文档](./document-zh.md#按需修改插件配置文件)中,关于**新开发**dubbo应用的说明。 - -## 插件配置中,enableSpringRegister/enableDubboRegister与openMigration之间的关系是什么? - -enableSpringRegister/enableDubboRegister与openMigration之间的关系如下表所示: - -|enableSpringRegister/enableDubboRegister|openMigration|作用| -|---|---|---| -|true|true|开启spring cloud/dubbo迁移功能| -|true|false|开启spring cloud/dubbo sc注册| -|false|true|关闭注册插件| -|false|false|关闭注册插件| - - - -[返回**服务注册插件**说明文档](./document-zh.md) - -[返回**Sermant**说明文档](../../README-zh.md) \ No newline at end of file diff --git a/docs/user-guide/registry/FAQ.md b/docs/user-guide/registry/FAQ.md deleted file mode 100644 index 9fb155093b..0000000000 --- a/docs/user-guide/registry/FAQ.md +++ /dev/null @@ -1,102 +0,0 @@ -# Service Registration FAQ - -[简体中文](FAQ-zh.md) | [English](FAQ.md) - -This document describes frequently asked questions (FAQs) about using the [service registration plugin](../../../sermant-plugins/sermant-service-registry). - -## Exception: No Such Extension org.apache.dubbo.registry.RegistryFactory by name sc - -As shown in the following figure: - -![No such extension org.apache.dubbo.registry.RegistryFactory by name sc](../../binary-docs/registry-faq-1.png) - -The possible causes are as follows: - -1.1 The application is not started with the agent. The native dubbo does not support registration with the SC. Therefore, if the application started without agent and the protocol of the registration address is SC, the preceding error is reported. - -1.2 The core configuration file (${agent_package_path}/agent/config/config.properties) is incorrectly configured. Check the startup log carefully and you will find an error similar to the following: - -![核心配置文件错误](../../binary-docs/registry-faq-2.png) - -- The value of the configuration center type (dynamic.config.dynamic_config_type) in the core configuration file is incorrect. As a result, the host application cannot load the agent and the No such extension org.apache.dubbo.registry.RegistryFactory by name sc reports an error. - -1.3 The core configuration file (${agent_package_path}/agent/config/config.properties) is incorrectly configured. Check the startup log carefully. The error information similar to the following is displayed: - -![核心配置文件错误](../../binary-docs/registry-faq-3.png) - -- The configuration center address (dynamic.config.server_address) is incorrectly configured in the core configuration file, the configuration center is not started, or the network is disconnected. As a result, the host application fails to load the agent, and the No such extension org.apache.dubbo.registry.RegistryFactory by name sc reports an error. - -## Exception: /sermant/master/v1/register error - -As shown in the following figure: - -![register error](../../binary-docs/registry-faq-4.png) - -The cause is that the backend is not started or the configured address is incorrect. Start the backend or configure the address correctly. For details about the backend, see the [backend document](../backend.md). - -Note: This error does not affect the plugin registration process, but related errors may be reported. - -## Exception: Connection reset - -As shown in the following figure: - -![Connection reset](../../binary-docs/registry-faq-5.png) - -Check whether the registration center address (servicecomb.service.address) and protocol (HTTP/HTTPS) in the plugin configuration (${agent_package_path}/agent/pluginPackage/service-registry/config/config.yaml) are correct. - -## Exception: https protocol is not supported - -As shown in the following figure: - -![https protocol is not supported](../../binary-docs/registry-faq-6.png) - -You need to enable ssl (servicecomb.service.sslEnabled) in the plugin configuration (${agent_package_path}/agent/pluginPackage/service-registry/config/config.yaml). - -## Exception: No such extension org.apache.dubbo.metadata.report.MetadataReportFactory by name sc - -As shown in the following figure: - -![No such extension org.apache.dubbo.metadata.report.MetadataReportFactory by name sc](../../binary-docs/registry-faq-7.png) - -Check the registration configuration of the dubbo application. Check whether protocol exists and is not sc. - -- Example for dubbo/provider.xml - -```xml - -``` - -- For example, application.yml (or application.properties). The following uses application.yml as an example. -```yml -dubbo: - registry: - protocol: nacos - address: sc://127.0.0.1:30100 -``` - -If protocol exists and is not set to sc, set protocol to sc or delete the protocol configuration. - -## Exception: No registry config found or it's not a valid config - -As shown in the following figure: - -![No registry config found or it's not a valid config](../../binary-docs/registry-faq-8.png) - -For details about how to set the address of the DUBBO registration center, see the description of newly developed DUBBO applications in the [service registration plugin](./document.md#Modify-the-plugin-configuration-file-on-demand) document. - -## What Is The Relationship Between Plugin Configuration, enableSpringRegister/enableDubboRegister, And openMigration? - -The following table describes the relationship between enableSpringRegister/enableDubboRegister and openMigration. - -|enableSpringRegister/enableDubboRegister|openMigration|effect| -|---|---|---| -|true|true|Enabling the Spring Cloud/Dubbo Migration Function| -|true|false|Enable Spring cloud/Dubbo With SC Registration| -|false|true|Disabling the Registration Plugin| -|false|false|Disabling the Registration Plugin| - - - -[Back to **Service Registration**](./document.md) - -[Back to README of **Sermant** ](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/registry/document-zh.md b/docs/user-guide/registry/document-zh.md deleted file mode 100644 index dc2c66c670..0000000000 --- a/docs/user-guide/registry/document-zh.md +++ /dev/null @@ -1,145 +0,0 @@ -# Service-Registry - -[简体中文](document-zh.md) | [English](document.md) - -本文主要介绍[服务注册插件](../../../sermant-plugins/sermant-service-registry)以及该插件的使用方法。 - -## 功能 - -服务注册插件提供代码无侵入方式,可让原本注册于Eureka,Nacos,Zookeeper、Consul等主流注册中心的微服务,无侵入地注册到[Service Center](https://github.com/apache/servicecomb-service-center)上, 同时支持Dubbo与SpringCloud框架。 - -## 使用说明 - -### 按需修改[核心配置文件](../../../sermant-agentcore/sermant-agentcore-config/config/config.properties) - -文件路径为:`${agent_package_path}/agent/config/config.properties`,其中`${agent_package_path}`需要替换为实际的打包路径。 - -配置项说明如下: - -```properties -#应用名 -service.meta.application=default -#版本号 -service.meta.version=1.0.0 -#命名空间 -service.meta.project=default -#环境 -service.meta.environment=development -``` - -### 按需修改[插件配置文件](../../../sermant-plugins/sermant-service-registry/config/config.yaml) - -文件路径为:`${agent_package_path}/agent/pluginPackage/service-registry/config/config.yaml`,其中`${agent_package_path}`需要替换为实际的打包路径。 - -配置项说明如下: - -```yaml -register.service: - registerType: SERVICE_COMB # 注册中心类型 支持NACOS/SERVICE_COMB - address: http://127.0.0.1:30100 #注册服务地址,service_comb:http://localhost:30100;nacos:127.0.0.1:8848 -``` - -```yaml -servicecomb.service: - heartbeatInterval: 15 #服务实例心跳发送间隔(单位:秒) - openMigration: false #是否开启迁移功能 - enableSpringRegister: false #是否开启spring插件注册能力,spring cloud框架需开启,dubbo框架需关闭 - enableDubboRegister: false #是否开启dubbo插件注册能力,dubbo框架需开启,spring cloud框架需关闭 - sslEnabled: false # 是否开启ssl -``` - -- 对于使用**NACOS**中心,还需要设置NACOS本身的注册中心相关配置,当前只支持springCloud - -```yaml -nacos.service: - username: "" # nacos验证账户 - password: "" # nacos的验证密码 - namespace: "" # 命名空间,nacos配置创建命名空间的id值 - weight: 1 # 服务实例权重值 - clusterName: DEFAULT # 集群名称 - ephemeral: true # 是否是临时节点,true为是,false为否 -``` - -注意: -1、nacos的group通过核心配置文件的service.meta.application设置 -2、nacos参数目前仅展示常用参数,其他参数项见[NACOS配置文件](../../../sermant-plugins/sermant-service-registry/registry-common/src/main/java/com/huawei/registry/config/NacosRegisterConfig.java) - -- 对于**新开发**的dubbo应用,还需要设置dubbo本身注册中心地址的配置。这个配置项一般在dubbo应用的配置文件中,比如“dubbo/provider.xml”文件中: - -```xml - -``` - -也可能在application.yml(或application.properties)中,以application.yml为例: - -```yml -dubbo: - registry: - address: sc://127.0.0.1:30100 -``` - -需要强调的是,这个配置项的地址信息**不会使用**,只使用了协议名称sc(即ip地址不重要,只需要**sc://** 开头即可)。 - -- **注意**:对于**存量**dubbo应用(即原本已经设置过dubbo本身注册中心地址的应用)**无需**进行这一步。 - -## 结果验证 - -- 前提条件[正确打包Sermant](../../README-zh.md#打包流程) - -- 启动Service Center,下载、使用说明和启动流程详见[官网](https://github.com/apache/servicecomb-service-center) - -- 编译[demo应用](https://github.com/huaweicloud/Sermant-examples/tree/main/registry-demo/dubbo-registry-demo) - -```shell -mvn clean package -``` - -- 启动消费者 - -```shell -# windows -java -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=dubbo-consumer -jar dubbo-consumer.jar - -# mac, linux -java -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=dubbo-consumer -jar dubbo-consumer.jar -``` - -- 启动生产者 - -```shell -# windows -java -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=dubbo-provider -jar dubbo-provider.jar - -# mac, linux -java -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=dubbo-provider -jar dubbo-provider.jar -``` - -注:为了便于测试,这里使用了-Dservicecomb.service.enableDubboRegister=true的方式打开了dubbo注册开关,如果使用了其它的方式打开了dubbo注册开关,则无需添加该参数。 - -其中${path}需要替换为Sermant工程路径,x.x.x需要替换为Sermant实际版本号,appName为agent启动参数中的应用名,与注册参数无关,执行命令的目录需要为demo应用的jar包目录。 - -启动参数的具体意义见[入口模块](../entrance-zh.md#启动参数)。 - -- 测试 - -当启动以上2个应用后,登录[Service Center](http://127.0.0.1:30103/)后台,查看相关服务实例是否已注册,并且访问应用接口,确认接口是否正常返回,若接口成功返回,则说明注册成功。 - -## 配置说明 - -**核心配置文件**与**插件配置文件**均支持环境变量、java -D参数配置),如下所示: - -```properties -service.meta.application=default -``` - -以上配置代表优选读取环境变量或-D参数中service.meta.application的值作为应用名,如果环境变量或-D参数中找不到这个值,则把default作为应用名。 - -## 更多文档 - -- [SpringCloud注册中心迁移](spring-cloud-registry-migiration-zh.md) - -- [Dubbo注册中心迁移](dubbo-registry-migiration-zh.md) - -- [服务注册常见问题](FAQ-zh.md) - -[返回**Sermant**说明文档](../../README-zh.md) \ No newline at end of file diff --git a/docs/user-guide/registry/document.md b/docs/user-guide/registry/document.md deleted file mode 100644 index 5074b6266c..0000000000 --- a/docs/user-guide/registry/document.md +++ /dev/null @@ -1,144 +0,0 @@ -# Service-Registry - -[简体中文](document-zh.md) | [English](document.md) - -This document describes the [service registration plugin](../../../sermant-plugins/sermant-service-registry) and how to use the plugin. - -## Function - -The service registration plug-in allows microservices that have been registered with popular registration centers, such as Eureka, Nacos, ZooKeeper, and Consul, to be registered with [Service Center](https://github.com/apache/servicecomb-service-center) in a non-intrusive manner. It also supports Dubbo and SpringCloud frameworks. - -## Usage - -### Modify [Core Configuration File](../../../sermant-agentcore/sermant-agentcore-config/config/config.properties) On Demand - - -The file path is `${agent_package_path}/agent/config/config.properties`. Please replace `${agent_package_path}` with the actual package path. - -The configuration items are described as follows: - -```properties -#application name -service.meta.application=default -#service version -service.meta.version=1.0.0 -#namespace, just keep default -service.meta.project=default -#you environment, currently, testing/development/production are supported -service.meta.environment=development -``` - -### Modify The [Plugin Configuration File](../../../sermant-plugins/sermant-service-registry/config/config.yaml) On Demand - -The file path is `${agent_package_path}/agent/pluginPackage/service-registry/config/config.yaml`. Please replace `${agent_package_path}` with the actual package path. - -The configuration items are described as follows: - -```yaml -register.service: - registerType: SERVICE_COMB # Registration center type, surpport NACOS/SERVICE_COMB - address: http://127.0.0.1:30100 # Registration center address. service_comb:http://localhost:30100;nacos:127.0.0.1:8848 -``` - -```yaml -servicecomb.service: - heartbeatInterval: 15 # Interval at which service instance heartbeats are sent (unit: second) - openMigration: false # Whether to enable the migration function. - enableSpringRegister: false # Whether to enable the Spring plug-in registration capability. This capability must be enabled for the Spring Cloud framework and disabled for the Dubbo framework. - enableDubboRegister: false # Whether to enable the dubbo plug-in registration capability. This capability must be enabled for the dubbo framework and disabled for the spring cloud framework. - sslEnabled: false # Whether to enable SSL. -``` - -- For using **NACOS** registry,also need setting nacos registration center configurations,currently only support springCloud - -```yaml -nacos.service: - username: "" # nacos check username - password: "" # nacos check password - namespace: "" # namespace, nacos setting the id of namespace - weight: 1 # service instance weight - clusterName: DEFAULT # cluster name - ephemeral: true # Whether to enable ephemeral endpoint, true for yes,false for no -``` - -Notice: -1. group of nacos can setting by core config service.meta.application. -2. nacos configs current only show normal use type, others see [NACOS config file](../../../sermant-plugins/sermant-service-registry/registry-common/src/main/java/com/huawei/registry/config/NacosRegisterConfig.java) - -- For **newly developed dubbo applications**, you also need to configure the address of the dubbo registration center. This configuration item is generally in the configuration file of the dubbo application, for example, in the dubbo/provider.xml file. - -```xml - -``` - -Alternatively, in application.yml (or application.properties), application.yml is used as an example. - -```yml -dubbo: - registry: - address: sc://127.0.0.1:30100 -``` - -Note that the address information of **this configuration item is not used**. Only the protocol name sc is used. (That is, the IP address is not important. **You only need to start with sc://**.) - -- **Note**: For **existing dubbo applications**, (Applications which hava already set up it's own registry address) **This step is not required**. - -## Verification - -- Prerequisites: [Sermant is packaged correctly](../../README.md#Packaging-Steps). -- Start the Service Center. For details about how to download, use, and start the Service Center, see the [official website](https://github.com/apache/servicecomb-service-center). -- Compile [demo application](https://github.com/huaweicloud/Sermant-examples/tree/main/registry-demo/dubbo-registry-demo) - -```shell -mvn clean package -``` - -- Start Consumer - -```shell -# windows -java -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=dubbo-consumer -jar dubbo-consumer.jar - -# mac, linux -java -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=dubbo-consumer -jar dubbo-consumer.jar -``` - -- Start Provider - -```shell -# windows -java -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=dubbo-provider -jar dubbo-provider.jar - -# mac, linux -java -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=dubbo-provider -jar dubbo-provider.jar -``` - -Note: To facilitate the test, the DUBBO registration function is enabled in -Dservicecomb.service.enableDubboRegister=true mode. If the DUBBO registration function is enabled in other modes, you do not need to add this parameter. - -Replace `${path}` with the Sermant project path, replace x.x.x with the actual Sermant version number, and appName with the application name in the agent startup parameter, which is irrelevant to registration parameters. The directory for running commands must be the JAR package directory of the demo application. - -Refer to the [entry module](../entrance.md#Startup-Parameters) for the specific meaning of the startup parameters. - -- Test - -After the preceding two applications are started, log in to the [Service Center](http://127.0.0.1:30103/) background and check whether related service instances have been registered. Access the application interface http://localhost:28820/hello to check whether the interface returns a normal response. If the interface returns a successful response, the registration is successful. - -## Configuration - -Both the **core configuration file and plugin configuration file** support the configuration of environment variables and java -D parameters, as shown in the following figure. - -```properties -service.meta.application=default -``` - -The preceding configuration indicates that the value of service.meta.application in the environment variable or -D parameter is preferred as the application name. If the value cannot be found in the environment variable or -D parameter, default is used as the application name. - -## More Documents - -- [SpringCloud Registry Migration](spring-cloud-registry-migiration.md) - -- [Dubbo Registry Migration](dubbo-registry-migiration.md) - -- [Registry Migration FAQ](FAQ.md) - -[Back to README of **Sermant** ](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/registry/dubbo-registry-migiration-zh.md b/docs/user-guide/registry/dubbo-registry-migiration-zh.md deleted file mode 100644 index 4938460502..0000000000 --- a/docs/user-guide/registry/dubbo-registry-migiration-zh.md +++ /dev/null @@ -1,110 +0,0 @@ -# Registry Migration - Dubbo - -[简体中文](dubbo-registry-migiration-zh.md) | [English](dubbo-registry-migiration.md) - -本文主要介绍[服务注册插件](../../../sermant-plugins/sermant-service-registry)基于Dubbo框架注册中心的迁移能力。 - -SpringCloud迁移见[SpringCloud注册中心迁移](spring-cloud-registry-migiration-zh.md) - -## 功能 - -提供代码无侵入方式,基于双注册的模式让线上应用在线上业务不停机的前提下将注册中心快速迁移到[Service Center](https://github.com/apache/servicecomb-service-center)的能力。支持注册中心如下: - -| 注册中心 | 是否支持 | -| --------- | -------- | -| Nacos | ✅ | -| Zookeeper | ✅ | - -**支持版本** - -Dubbo 2.6.x, 2.7.x - -**搬迁示意图** - -![agent注册中心迁移-迁移示意图](../../binary-docs/sermant-register-migration.png) - -## 使用说明 - -### 修改[插件配置文件](../../../sermant-plugins/sermant-service-registry/config/config.yaml) - -文件路径为:${agent_package_path}/agent/pluginPackage/service-registry/config/config.yaml,其中${agent_package_path}需要替换为实际的打包路径。 - -将servicecomb.service.openMigration与servicecomb.service.enableDubboRegister的值设置为true,如下所示: - -```yaml -servicecomb.service: - openMigration: true #开启迁移功能 - enableDubboRegister: true #开启dubbo插件注册 -``` - -详细配置说明见[服务注册插件文档](./document-zh.md#按需修改插件配置文件) - -**注意:如果开启了迁移功能,则无需修改原有的注册中心地址,否则将不会同时向2个注册中心(原注册中心+sc)进行注册。** - -### 启动Service Center - -Service Center启动流程详见[官网](https://github.com/apache/servicecomb-service-center) - -## 结果验证 - -- 说明:此处以原注册中心为Nacos进行举例。 - -- 前提条件[正确打包Sermant](../../README.md#打包流程)。 - -- 启动Service Center,下载、使用说明和启动流程详见[官网](https://github.com/apache/servicecomb-service-center)。 - -- 启动Nacos,下载、使用说明和启动流程详见[官网](https://nacos.io/zh-cn/docs/quick-start.html)。 - -- 编译[demo应用](../../../sermant-plugins/sermant-service-registry/demo-registry/demo-registry-dubbo)。 - -```shell -mvn clean package -``` - -- 启动双注册消费者 - -```shell -# windows -java -Dservicecomb.service.openMigration=true -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=dubbo-consumer -jar dubbo-consumer.jar - -# mac, linux -java -Dservicecomb.service.openMigration=true -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=dubbo-consumer -jar dubbo-consumer.jar -``` - -注:为了便于测试,这里使用了-Dservicecomb.service.openMigration=true -Dservicecomb.service.enableDubboRegister=true的方式打开了dubbo迁移功能,如果使用了其它的方式打开了dubbo迁移开关,则无需添加该参数。 - -- 启动原生产者(注册到Nacos中) - -```shell -# windows -java -jar dubbo-provider.jar - -# mac, linux -java -jar dubbo-provider.jar -``` - -- 启动新生产者(注册到SC中) - -```shell -# windows -java -Dservicecomb.service.enableDubboRegister=true -Dserver.port=48021 -Ddubbo.protocol.port=48821 -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=dubbo-provider -jar dubbo-provider.jar - -# mac, linux -java -Dservicecomb.service.enableDubboRegister=true -Dserver.port=48021 -Ddubbo.protocol.port=48821 -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=dubbo-provider -jar dubbo-provider.jar -``` - -注:为了便于测试,这里使用了-Dservicecomb.service.enableDubboRegister=true的方式打开了dubbo注册开关,如果使用了其它的方式打开了dubbo注册开关,则无需添加该参数;另外为了解决同一台服务器启动2个provider遇到的端口冲突问题,需要增加-Dserver.port=48021 -Ddubbo.protocol.port=48821参数,如果测试时2个provider在不同的服务器,则无需添加该参数。 - -其中${path}需要替换为Sermant工程路径,x.x.x需要替换为Sermant实际版本号,appName为agent启动参数中的应用名,与注册参数无关,执行命令的目录需要为demo应用的jar包所在的目录。 - -启动参数的具体意义见[入口模块](../entrance-zh.md#启动参数)。 - -- 测试 - -当启动以上3个应用后,登录[Service Center](http://127.0.0.1:30103/)后台和[Nacos](http://127.0.0.1:8848/nacos/index.html#/serviceManagement)后台,均可查看到consumer和provider应用,并且多次访问应用接口,确认接口是否正常返回,若接口成功返回并可访问2个注册中心的生产者实例,则说明注册并迁移成功。 - - - -[返回**服务注册插件**说明文档](./document-zh.md) - -[返回**Sermant**说明文档](../../README-zh.md) \ No newline at end of file diff --git a/docs/user-guide/registry/dubbo-registry-migiration.md b/docs/user-guide/registry/dubbo-registry-migiration.md deleted file mode 100644 index 89f7dcc253..0000000000 --- a/docs/user-guide/registry/dubbo-registry-migiration.md +++ /dev/null @@ -1,104 +0,0 @@ -# Registry Migration - Dubbo - -[简体中文](dubbo-registry-migiration-zh.md) | [English](dubbo-registry-migiration.md) - -This document describes the migration capability of the [service registration plugin](../../../sermant-plugins/sermant-service-registry) based on the Dubbo framework registration center. - -For details about SpringCloud migration, see [SpringCloud Registration Center Migration](spring-cloud-registry-migiration.md). - -## Function - -Provides the capability of quickly migrating the registration center to the [Service Center](https://github.com/apache/servicecomb-service-center) based on the dual-registration mode without interrupting online services business. The following registration centers are supported: - -| Registration Center | Support | -| --------- | -------- | -| Nacos | ✅ | -| Zookeeper | ✅ | - -## Support Versions - -Dubbo 2.6.x, 2.7.x - -**Schematic diagram of migration** - -![agent注册中心迁移-迁移示意图](../../binary-docs/sermant-register-migration-en.png) - -## Usage - -### Modify [Plugin Configuration File](../../../sermant-plugins/sermant-service-registry/config/config.yaml) - -The file path is `${agent_package_path}/agent/pluginPackage/service-registry/config/config.yaml`. Please replace `${agent_package_path}` with the actual package path. - -Set servicecomb.service.openMigration and servicecomb.service.enableDubboRegister to true as follows: - -```yaml -servicecomb.service: - openMigration: true #Enable the migration function - enableDubboRegister: true #Enabling Dubbo plugin registration -``` - -For details, see the [service registration plugin document](./document.md#Modify-the-plugin-configuration-file-on-demand). - -**Notices**: If the migration function is enabled, you do not need to change the address of the original registration center. Otherwise, the registration will not be performed at the same time with two registration centers (original registration center + SC). - -### Startup Service Center - -For details about the Service Center startup process, see the [official website](https://github.com/apache/servicecomb-service-center). - -## Verification - -- Notice:In this example, the original registration center is Nacos. -- Prerequisites: [The Sermant is packaged correctly](../../README.md). -- Start Service Center. For details about how to download, use, and start Service Center, see the [official website](https://github.com/apache/servicecomb-service-center). -- Start the Nacos. For details about how to download, use, and start the Nacos, see the [official website](https://nacos.io/zh-cn/docs/quick-start.html). -- Compile [demo application](../../../sermant-plugins/sermant-service-registry/demo-registry/demo-registry-dubbo) - -```shell -mvn clean package -``` - -- Start up dual registration consumer - -```shell -# windows -java -Dservicecomb.service.openMigration=true -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=dubbo-consumer -jar dubbo-consumer.jar - -# mac, linux -java -Dservicecomb.service.openMigration=true -Dservicecomb.service.enableDubboRegister=true -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=dubbo-consumer -jar dubbo-consumer.jar -``` - -Notices: To facilitate the test, the dubbo migration function is enabled in -Dservicecomb.service.openMigration=true -Dservicecomb.service.enableDubboRegister=true mode. If the dubbo migration function is enabled in other modes, you do not need to add this parameter. - -- Start the original producer (registered with the Nacos). - -```shell -# windows -java -jar dubbo-provider.jar - -# mac, linux -java -jar dubbo-provider.jar -``` - -- Starting a New Producer (Registering to the SC) - -```shell -# windows -java -Dservicecomb.service.enableDubboRegister=true -Dserver.port=48021 -Ddubbo.protocol.port=48821 -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=dubbo-provider -jar dubbo-provider.jar - -# mac, linux -java -Dservicecomb.service.enableDubboRegister=true -Dserver.port=48021 -Ddubbo.protocol.port=48821 -javaagent:${path}/sermant-agent-x.x.x/agent/sermant-agent.jar=appName=dubbo-provider -jar dubbo-provider.jar -``` - -Notice: To facilitate the test, the Dubbo registration function is enabled in -Dservicecomb.service.enableDubboRegister=true mode. If the Dubbo registration function is enabled in other modes, you do not need to add this parameter. In addition, to solve the port conflict problem when two providers are started on the same server, you need to add the -Dserver.port=48021 -Ddubbo.protocol.port=48821 parameter. If the two providers are on different servers, you do not need to add this parameter. - -Please replace `${path}` with the Sermant project path, replace x.x.x with the actual Sermant version number, and appName with the application name in the agent startup parameter, which is irrelevant to the registration parameter. The directory for running the command must be the directory where the JAR package of the demo application is located. - -Startup parameters can referring to the [entry module](../entrance.md#Startup-Parameters). - -- Test - -After the preceding three applications are started, log in to the [Service Center](http://127.0.0.1:30103/) background and [Nacos background](http://127.0.0.1:8848/nacos/index.html#/serviceManagement) to view the consumer and provider applications. Access the application interface http://localhost:28020/test for multiple times and check whether the interface returns a normal response. If the interface successfully returns a response and the producer instances of the two registration centers can be accessed, indiactes that the registration and migration are successful. - -[Back to **Service Registration**](./document.md) - -[Back to README of **Sermant** ](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/registry/spring-cloud-registry-migiration-zh.md b/docs/user-guide/registry/spring-cloud-registry-migiration-zh.md deleted file mode 100644 index 7e75be77af..0000000000 --- a/docs/user-guide/registry/spring-cloud-registry-migiration-zh.md +++ /dev/null @@ -1,104 +0,0 @@ -# Registry Migration - Spring Cloud - -[简体中文](./spring-cloud-registry-migiration-zh.md) | [English](./spring-cloud-registry-migiration.md) - -本文主要介绍[服务注册插件](../../../sermant-plugins/sermant-service-registry)基于Spring Cloud框架注册中心的迁移能力。 - -Dubbo迁移见[Dubbo注册中心迁移](dubbo-registry-migiration-zh.md) - -## 功能 - -提供代码无侵入方式,基于双注册的模式让线上应用在线上业务不停机的前提下将注册中心快速迁移到[Service Center](https://github.com/apache/servicecomb-service-center)的能力。支持注册中心如下: - -| 注册中心 | 是否支持 | -| --------- | -------- | -| Eureka | ✅ | -| Consul | ✅ | -| Nacos | ✅ | -| Zookeeper | ✅ | - -**支持版本** - -| Spring Cloud Version | Spring Boot Version | Zookeeper Discovery Version | Nacos Discovery Version | Consul Discovery Version | Eureka Client Version | -| -------------------- | ------------------- | --------------------------- | --------------------------- | ---------------------------- | ----------------------------------------------------- | -| Edgware.x | 1.5.x | 1.x.x, 2.0.x | 1.5.x | 1.x.x, 2.0.x, 2.1.x | 1.4.x, 2.0.x, 2.1.x | -| Finchley.x | 2.0.x, 2.1.x | 2.x.x | 1.5.x, 2.0.x, 2.1.x | 1.3.x, 2.0.x, 2.1.x | 1.4.x, 2.0.x, 2.1.x | -| Hoxton.x | 2.2.x, 2.3.x | 2.x.x, 3.0.0 - 3.1.0 | 2.x.x, 2020.0.RC1, 2021.1 | 1.3.x, 2.0.x, 2.1.x, 2.2.x | 1.4.4.RELEASE - 1.4.7.RELEASE, 2.x.x, 3.0.0 - 3.1.0 | -| 2020.0.x | 2.4.x, 2.5.x | 3.0.0 - 3.1.0 | 2.x.x, 2020.0.RC1, 2021.1 | 3.0.0 - 3.1.0 | 2.1.x, 2.2.x, 3.0.0 - 3.1.0 | -| 2021.0.0 | 2.6.x | 3.0.0 - 3.1.0 | 2.x.x, 2020.0.RC1, 2021.1 | 3.0.0 - 3.1.0 | 3.0.0 - 3.1.0 | - -**搬迁示意图** - -![agent注册中心迁移-迁移示意图](../../binary-docs/sermant-register-migration.png) - -## 使用说明 - -### 修改[配置文件](../../../sermant-plugins/sermant-service-registry/config/config.yaml) - -配置说明见[服务注册插件文档](./document-zh.md#按需修改插件配置文件) - -基于以上配置,**新增迁移配置**,并开启Spring注册插件配置内容如下: - -```yaml -servicecomb.service: - openMigration: true #是否开启迁移功能 若进行注册中心迁移,则需将该值设置为true - enableSpringRegister: true #开启spring注册插件 -``` - -如果迁移目标是NACOS,相关配置参考[配置项说明](./document-zh.md#按需修改插件配置文件),修改注册中心类型(registerType)为NACOS - -### 启动Service Center - -Service Center启动流程详见[官网](https://github.com/apache/servicecomb-service-center) - -### 进行双注册迁移模拟 - -(1)首先不带agent启动应用,例如有provider与consumer两个实例,启动后确保应用已成功注册到原注册中心且可正常访问 - -(2)启动一个新的provider,附加以下JVM参数,带agent一起启动 - -```shell -java -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=appName -``` - -其中path需要替换为Sermant实际打包路径,x.x.x需要替换为Sermant实际版本号,appName为agent的启动参数,与注册参数无关。 - -(3)启动成功后,新的provider实例会同时注册到Service Center与原注册中心,且consumer可以成功访问 - -(4)关闭旧的provider, 再按照(2)的方式启动新的consumer实例,同样确认新和旧的consumer都可以访问到provider,再停止旧的consumer即可 - -(5)最后再停止旧的注册中心 - -> ***提示:*** -> -> *关闭原注册中心,由于大部分注册中心存在心跳检查机制,实例可能会不断刷错误日志,但不影响应用的正常调用。* -> -> *若需要停止此类错误日志,参考节[**注册中心心跳配置下发**](#**注册中心心跳配置下发**)* - -## **注册中心心跳配置下发** - -注册中心迁移插件提供基于动态配置中心下发关闭原注册中心心跳机制的方法,以避免源源不断的错误日志输出 - -**后台提供配置下发接口进行动态配置下发:** - -URL - -POST /publishConfig - -**请求Body** - -| 参数 | 是否必填 | 参数类型 | 描述 | 配置值 | -| ------- | -------- | -------- | --------- | --------------------------------------- | -| key | 是 | String | 配置的key | sermant.agent.registry | -| group | 是 | String | 配置的组 | service=YourServiceName | -| content | 是 | String | 配置文本 | origin.\_\_registry\_\_.needClose: true | - -若需要关闭请参考表格**配置值**列进行配置下发 - -> ***注意 :*** -> -> *该操作为一次性操作,关闭注册中心心跳后,将无法开启,仅当应用实例重启才可恢复。* - -[返回**服务注册插件**说明文档](./document-zh.md) - -[返回**Sermant**说明文档](../../README-zh.md) \ No newline at end of file diff --git a/docs/user-guide/registry/spring-cloud-registry-migiration.md b/docs/user-guide/registry/spring-cloud-registry-migiration.md deleted file mode 100644 index 3262646e3a..0000000000 --- a/docs/user-guide/registry/spring-cloud-registry-migiration.md +++ /dev/null @@ -1,104 +0,0 @@ -# Registry Migration - Spring Cloud - -[简体中文](./spring-cloud-registry-migiration-zh.md) | [English](./spring-cloud-registry-migiration.md) - -This document describes the migration capability of the [service registration plugin](../../../sermant-plugins/sermant-service-registry) based on the Spring Cloud framework registration center. - -Dubbo migration referring [Dubbo Registry Migration](dubbo-registry-migiration.md) - -## Function - -Provides the capability of quickly migrating the registration center to the [Service Center](https://github.com/apache/servicecomb-service-center) based on the dual-registration mode without interrupting online services business. The following registration centers are supported: - -| Registration Center | Supported or Not | -| ------------------- | ---------------- | -| Eureka | ✅ | -| Consul | ✅ | -| Nacos | ✅ | -| Zookeeper | ✅ | - -**Support Versions** - -| Spring Cloud Version | Spring Boot Version | Zookeeper Discovery Version | Nacos Discovery Version | Consul Discovery Version | Eureka Client Version | -| -------------------- | ------------------- | --------------------------- | --------------------------- | ---------------------------- | ----------------------------------------------------- | -| Edgware.x | 1.5.x | 1.x.x, 2.0.x | 1.5.x | 1.x.x, 2.0.x, 2.1.x | 1.4.x, 2.0.x, 2.1.x | -| Finchley.x | 2.0.x, 2.1.x | 2.x.x | 1.5.x, 2.0.x, 2.1.x | 1.3.x, 2.0.x, 2.1.x | 1.4.x, 2.0.x, 2.1.x | -| Hoxton.x | 2.2.x, 2.3.x | 2.x.x, 3.0.0 - 3.1.0 | 2.x.x, 2020.0.RC1, 2021.1 | 1.3.x, 2.0.x, 2.1.x, 2.2.x | 1.4.4.RELEASE - 1.4.7.RELEASE, 2.x.x, 3.0.0 - 3.1.0 | -| 2020.0.x | 2.4.x, 2.5.x | 3.0.0 - 3.1.0 | 2.x.x, 2020.0.RC1, 2021.1 | 3.0.0 - 3.1.0 | 2.1.x, 2.2.x, 3.0.0 - 3.1.0 | -| 2021.0.0 | 2.6.x | 3.0.0 - 3.1.0 | 2.x.x, 2020.0.RC1, 2021.1 | 3.0.0 - 3.1.0 | 3.0.0 - 3.1.0 | - -**Schematic diagram of migration** - -![agent注册中心迁移-迁移示意图](../../binary-docs/sermant-register-migration-en.png) - -## Usage - -#### Modify [Configuration File](../../../sermant-plugins/sermant-service-registry/config/config.yaml) - -For details about the configuration, see the [service registration plugin document](./document.md#Modify-the-plugin-configuration-file-on-demand). - -Based on the preceding configuration, **the migration configuration is added and the Spring registration plugin is enabled**. The configuration content is as follows: - -```yaml -servicecomb.service: - openMigration: true #Specifies whether to enable the migration function. To migrate the registration center, set this parameter to true. - enableSpringRegister: true #Enabling the spring registration plugin -``` - -If migration target is NACOS, see the [configuration items described](./document.md#Modify-the-plugin-configuration-file-on-demand), modify registration center type (registerType) as NACOS. - -### Startup Service Center - -For details about the Service Center startup process, see the [official website](https://github.com/apache/servicecomb-service-center). - -### Registration Migration Simulation - -(1)Start the application without the agent. For example, start separately one instance for provider and consumer, ensure that the application has been registered with the original registration center and can be requested normally. - -(2)Start a new provider, add the following JVM parameters, and start the provider with the agent. - -```shell -java -javaagent:${path}\sermant-agent-x.x.x\agent\sermant-agent.jar=appName=appName -``` - -**Replace path with the actual Sermant package path**, x.x.x is the actual Sermant version number, and appName with the agent startup parameter, which is irrelevant to registration parameters. - -(3)After the service is started, the new provider instance will register to the service center and the original registration center both, and the consumer can request provider. - -(4)Stop the old provider and start the new consumer instance in step 2. Ensure that both the old and new consumers can request the provider normally, then stop the old consumer. - -(5)Finally, stop the old register center. - -> ***Notices:*** -> -> Stop the original register center. Because most of the registry centers have the heartbeat check mechanism, the instance may continuously update error logs, but the application invoking is not affected. -> -> To stop such error logs, see [**Delivering Heartbeat Configurations**](#Delivering-Heartbeat-Configurations). - -## Delivering Heartbeat Configurations - -The registration center migration plugin provides the method of disabling the heartbeat mechanism of the original registration center based on the dynamic configuration center to prevent continuous error log output. - -**The [backend service](../backend.md) provides the configuration delivery interface for dynamic configuration delivery:** - -URL - -POST /publishConfig - -**Request Body** - -| Params | Mandatory Or Not | Param Type | Description | Configuration Value | -| ------- | ---------------- | ---------- | --------------------- | --------------------------------------- | -| key | Y | String | configuration key | sermant.agent.registry | -| group | Y | String | configuration group | service=YourServiceName | -| content | Y | String | configuration.content | origin.\_\_registry\_\_.needClose: true | - -If you need to disable this function, deliver the configuration by referring to the Configuration Value column in the table. - -> ***Notices :*** -> -> This operation is a one-off operation. After the registration center heartbeat function is disabled, the heartbeat function cannot be enabled. It can be restored only after the application instance is restarted. - -[Back to **Service Registration**](./document.md) - -[Back to README of **Sermant** ](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/router/document-zh.md b/docs/user-guide/router/document-zh.md deleted file mode 100644 index 786a4116ff..0000000000 --- a/docs/user-guide/router/document-zh.md +++ /dev/null @@ -1,162 +0,0 @@ -# 标签路由 - -[简体中文](document-zh.md) | [English](document.md) - -本文档主要介绍[标签路由插件](../../../sermant-plugins/sermant-router)的使用方法。 - -区域路由见[区域路由](zone-router-zh.md)。 - -## 功能 - -在微服务存在多个版本、多个实例的情况下,通过配置路由规则管理服务之间的路由,达到无损升级、应用拨测等业务目的。 - -## 使用说明 - -- 配置路由规则 - -Sermant backend提供api的方式发布配置, 使用前需启动backend后台应用,配置发布接口如下: - -**URL** - -POST /publishConfig - -**请求Body** - -|参数|是否必填|参数类型|描述 -|---|---|---|---| -|key|√|String|配置的key| -|group|√|String|配置的组| -|content|√|String|配置文本| - -其中key值为servicecomb.routeRule.${yourServiceName},${yourServiceName}为目标应用的微服务名称。 - -group需要配置为应用级别,即app=${yourApp}&&environment=${yourEnvironment},其中app默认为default,environment默认为空。 - -content为具体的路由规则。 - -### 标签路由规则示例及说明如下: - -```yaml ---- -- precedence: 2 # 优先级,数字越大,优先级越高。 - match: # 请求匹配规则。0..N个,不配置表示匹配。每条匹配规则只允许存在一个attachments/headers/args。 - attachments: # dubbo attachment匹配。如果是http header匹配,需要配置为headers - id: # 如果配置了多个key,那么所有的key规则都必须和请求匹配 - exact: '1' # 配置策略,等于1,详细配置策略参考配置策略表 - caseInsensitive: false # false:不区分大小写(默认),true:区分大小写。配置为false时,将统一转为大写进行比较 - args: # dubbo参数匹配 - args0: # dubbo接口的第0个参数 - type: .id # 取值类型,dubbo应用特有字段,第0个参数为实体,获取其id的属性值,如果参数类型为int,String等普通类型,则无需填写该值,所有的取值类型见取值类型列表 - exact: '2' # 配置策略,等于2,所有的匹配策略见配置策略列表 - caseInsensitive: false # 是否区分大小写,默认为false,区分大小写 - route: # 路由规则 - - weight: 20 # 权重值 - tags: - version: 1.0.0 # 实例标记。满足标记条件的实例放到这一组。 - - weight: 80 # 权重值 - tags: - version: 1.0.1 # 实例标记。满足标记条件的实例放到这一组。 -- precedence: 1 - route: - - weight: 20 - tags: - group: red - - weight: 80 - tags: - group: green -``` - -**注意:新增配置时,请去掉注释,否则会导致新增失败。** - -### 配置策略列表 - -|策略名|策略值|匹配规则| -|---|---|---| -|精确匹配|exact|参数值等于配置值| -|正则|regex|参数值匹配正则表达式,由于部分正则表达式(如\w与\W等)区分大小写,所以使用正则策略时,请谨慎选择caseInsensitive(是否区分大小写)| -|不等于|noEqu|参数值不等于配置值| -|大于等于|noLess|参数值大于等于配置值| -|小于等于|noGreater|参数值小于等于配置值| -|大于|greater|参数值大于配置值| -|小于|less|参数值小于配置值| - -### 取值类型列表 - -|类型|取值方式|适用参数类型| -|---|---|---| -|留空|表示直接取当前参数的值|适用普通参数类型,例如String、int、long等| -|.name|表示取参数的name属性,相当于ARG0.getName()|适用于对象类型| -|.isEnabled()|表示取参数的enabled属性,相当于ARG0.isEnabled()|适用于对象类型| -|[0]|取数组的第一个值,相当于ARG0[0]|适用于普通类型的数组,例如String[]、int[]| -|.get(0)|取List的第一个值,相当于ARG0.get(0)|适用于普通类型的列表,例如List\、List\| -|.get("key")|获取key对应的值,相当于ARG0.get("key")|适用于普通类型的map,例如Map| - -- 启动标签应用 - -在附带agent启动时,按需加上以下参数: - -``` --Dservice_meta_version=${VERSION} -Dservice_meta_parameters=${PARAMETERS} -``` - -参数说明如下: - -- ${VERSION}需替换为服务注册时的版本号(形如a.b.c的格式,其中a,b,c均为数字,默认为1.0.0),标签应用需要修改为不同于正常应用的版本号。 -- ${PARAMETERS}需替换为服务注册时的自定义标签(形如tag1:value1,tag2:value2),即标签名与标签值以英文冒号分隔,多个标签之间以英文逗号分隔。 -- 一般地,如果用版本号进行路由,则只需配置service_meta_version,如果用自定义标签进行路由,则只需配置service_meta_parameters。 - -## 结果验证 - -- 前提条件[正确打包Sermant](../../README.md) - -- 注册中心使用华为CSE,下载[Local-CSE](https://support.huaweicloud.com/devg-cse/cse_devg_0036.html) ,解压后按照文档说明进行启动 - -- 配置路由规则 - -调用接口`localhost:8900/publishConfig`, 请求参数如下: - -```json -{ - "content": "---\n- precedence: 1\n match:\n headers:\n id:\n exact: '1'\n caseInsensitive: false\n route:\n - tags:\n group: gray\n weight: 100\n- precedence: 2\n match:\n headers:\n id:\n exact: '2'\n caseInsensitive: false\n route:\n - tags:\n version: 1.0.1\n weight: 100", - "group": "app=default&&environment=", - "key": "servicecomb.routeRule.spring-cloud-router-provider" -} -``` - -- 编译[demo应用](https://github.com/huaweicloud/Sermant-examples/tree/main/router-demo/spring-cloud-router-demo) - -```shell -mvn clean package -``` - -- 启动zuul网关 - -```shell -java -Dservicecomb_service_enableSpringRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar spring-cloud-router-zuul.jar -``` - -- 启动消费者 - -```shell -java -Dservicecomb_service_enableSpringRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar spring-cloud-router-consumer.jar -``` - -- 启动生产者 - -```shell -java -Dservicecomb_service_enableSpringRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar spring-cloud-router-provider.jar -``` - -- 启动标签生产者(版本为1.0.1,标签为group:gray) - -```shell -java -Dservicecomb_service_enableSpringRegister=true -Dservice_meta_version=1.0.1 -Dservice_meta_parameters=group:gray -Dserver.port=8163 -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar spring-cloud-router-provider.jar -``` - -其中path需要替换为Sermant实际安装路径。 - -- 测试 - -当启动以上4个应用并正确配置路由规则后,通过http客户端工具访问,可以发现,当请求头为id: 1或者id: 2时,会路由到版本为1.0.1的provider,当不满足以上条件时,会访问到版本为1.0.0的provider - -[返回**Sermant**说明文档](../../README.md) diff --git a/docs/user-guide/router/document.md b/docs/user-guide/router/document.md deleted file mode 100644 index 180ef73fd5..0000000000 --- a/docs/user-guide/router/document.md +++ /dev/null @@ -1,162 +0,0 @@ -# Tag Router - -[简体中文](document-zh.md) | [English](document.md) - -This document is used to introduce the usage of [tag router](../../../sermant-plugins/sermant-router) - -Zone Router referring [Zone Router](zone-router.md). - -## Function - -In the case of multiple versions and instances of microservices, the routing between services is managed by configuring routing rules to achieve business purposes such as lossless upgrade and application dial test. - -## Usage - -- Configure Routing Rules - -Sermant backend provides api way to publish the configuration, you need to start the backend application before use, the configuration publishing interface is as follows: - -**URL** - -POST /publishConfig - -**Request Body** - -|Params|Mandatory or not|Param type|Description -|---|---|---|---| -|key|√|String|configuration key| -|group|√|String|Configuration group, which is used to configure subscriptions| -|content|√|String|Configuration text, that is, specific routing rules| - -The key value needs to be servicecomb.routeRule.${yourServiceName}, ${yourServiceName} is the microservice name of the target application. - -The group needs to be configured to application level, i.e. app=${yourApp}&&environment=${yourEnvironment}, app defaults to default, environment defaults to empty. - -The content is the specific routing rule. - -### Examples of tag routing rules and descriptions are as follows - -```yaml ---- -- precedence: 2 # Priority, the higher the number, the higher the priority. - match: # Request match rule. 0..N, not configured to indicate a match. Only one attachments/headers/args are allowed per match rule. - attachments: # dubbo attachment matches. If it is an http header match, you need to configure it as headers. - id: # If multiple keys are configured, then all key rules must match the request. - exact: '1' # Configuration policy, equal to 1, detailed configuration policy refer to the configuration policy table. - caseInsensitive: false # false: case-insensitive (default), true: case-sensitive. When configured to false, it will be converted to uppercase uniformly for comparison. - args: # dubbo parameter matches - args0: # The 0th parameter of the dubbo interface - type: .id # Take the value type, dubbo application-specific field, the 0th parameter is an entity, get its id property value, if the parameter type is int, String and other common types, it is not necessary to fill in the value, all the value types see the table of value types. - exact: '2' # Configuration policy, equal to 2, detailed configuration policy refer to the configuration policy table. - caseInsensitive: false # Whether to be case-sensitive, default is false, case-sensitive. - route: # Routing Rules - - weight: 20 # Weight - tags: - version: 1.0.0 # Instance tagging. Instances that meet the tagging criteria are placed in this group. - - weight: 80 # Weight - tags: - version: 1.0.1 # Instance tagging. Instances that meet the tagging criteria are placed in this group. -- precedence: 1 - route: - - weight: 20 - tags: - group: red - - weight: 80 - tags: - group: green -``` - -**Note: When adding a new configuration, please remove the comment, otherwise it will cause the addition to fail.** - -### Configuration Policy Table - -|Strategy Name|Strategy Value|Matching Rules| -|---|---|---| -|Exact Match|exact|The parameter value is equal to the configured value| -|Regex Match|regex|Parameter values match regex expressions, Since some regex expressions (such as \w and \W, etc.) are case-sensitive, please choose caseInsensitive (case-sensitive or not) carefully when using regex match| -|Not Equal Match|noEqu|The parameter value is not equal to the configuration value| -|Not Less Match|noLess|The parameter value is not less than the configured value| -|Not Greater Match|noGreater|The parameter value is not greater than the configured value| -|Greater Match|greater|The parameter value is greater than the configured value| -|Less Match|less|The parameter value is less than the configured value| - -### Value Types Table - -|Type|Fetch Method|Parameter types| -|---|---|---| -|Empty/Null|Indicates that the value of the current parameter is obtained directly|Applicable to common parameter types, such as String, int, long, etc.| -|.name|Denotes the name attribute of the fetch parameter, equivalent to ARG0.getName()|Applicable to object types| -|.isEnabled()|Denotes the enabled attribute of the fetch parameter, equivalent to ARG0.isEnabled()|Applicable to object types| -|[0]|Takes the first value of the array, equivalent to ARG0[0]|For arrays of common types, such as String[], int[]| -|.get(0)|Takes the first value of the list, equivalent to ARG0.get(0)|For list of common types, such as List\, List\| -|.get("key")|Get the value corresponding to the key, equivalent to ARG0.get("key")|For map of common types, such as Map| - -- Start the tag application - -Add the following parameters as required at the start of the attached agent: - -``` --Dservice_meta_version=${VERSION} -Dservice_meta_parameters=${PARAMETERS} -``` - -The parameters are described as follows: - -- ${VERSION} needs to be replaced with the version number at the time of service registration (The format of a.b.c, where a,b,c are numbers and the default is 1.0.0). The tag application needs to be modified to a different version number than the normal application. -- ${PARAMETERS} needs to be replaced with the custom tag from the service registration (Such as tag1:value1, tag2:value2). That is, tag keys and tag values are separated by colons, and multiple tags are separated by commas. -- In general, only service_meta_version needs to be configured if routing by version number, or service_meta_parameters if routing by custom tag. - -## Result Verification - -- Prerequisites [correctly packed Sermant](../../README.md) - -- Registration center using Huawei CSE, download [Local-CSE](https://support.huaweicloud.com/devg-cse/cse_devg_0036.html), unzip and follow the documentation to start. - -- Configuring Routing Rules - -Calling the interface `localhost:8900/publishConfig`, with the following request parameters: - -```json -{ - "content": "---\n- precedence: 1\n match:\n headers:\n id:\n exact: '1'\n caseInsensitive: false\n route:\n - tags:\n group: gray\n weight: 100\n- precedence: 2\n match:\n headers:\n id:\n exact: '2'\n caseInsensitive: false\n route:\n - tags:\n version: 1.0.1\n weight: 100", - "group": "app=default&&environment=", - "key": "servicecomb.routeRule.spring-cloud-router-provider" -} -``` - -- Compile [demo application](https://github.com/huaweicloud/Sermant-examples/tree/main/router-demo/spring-cloud-router-demo) - -```shell -mvn clean package -``` - -- Start the zuul gateway - -```shell -java -Dservicecomb_service_enableSpringRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar spring-cloud-router-zuul.jar -``` - -- Start the consumer - -```shell -java -Dservicecomb_service_enableSpringRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar spring-cloud-router-consumer.jar -``` - -- Start the provider - -```shell -java -Dservicecomb_service_enableSpringRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar spring-cloud-router-provider.jar -``` - -- Start the provider with tag (version is 1.0.1, tag is group:gray.) - -```shell -java -Dservicecomb_service_enableSpringRegister=true -Dservice_meta_version=1.0.1 -Dservice_meta_parameters=group:gray -Dserver.port=8163 -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar spring-cloud-router-provider.jar -``` - -${path} needs to be replaced with the actual Sermant installation path. - -- Testing - -After starting the above 4 applications and configuring the routing rules correctly, when accessing through the http client tool, we can find that when the request header is id: 1 or id: 2, it will be routed to the provider of version 1.0.1, and when the above conditions are not met When the above condition is not met, it will visit the provider with version 1.0.0. - -[Back to README of **Sermant** ](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/router/zone-router-zh.md b/docs/user-guide/router/zone-router-zh.md deleted file mode 100644 index 73dfdaea93..0000000000 --- a/docs/user-guide/router/zone-router-zh.md +++ /dev/null @@ -1,122 +0,0 @@ -# 区域路由 - -[简体中文](zone-router-zh.md) | [English](zone-router.md) - -本文档主要介绍[区域路由插件](../../../sermant-plugins/sermant-router)的使用方法。 - -标签路由见[标签路由](document-zh.md)。 - -## 功能 - -在微服务部署在多个AZ(available zone)的情况下,优先筛选同AZ实例进行调用,同AZ的实例都不可用时,跳到不同AZ。 - -## 使用说明 - -- 按需修改[插件配置文件](../../../sermant-plugins/sermant-router/config/config.yaml) - -文件路径为:`${agent_package_path}/agent/pluginPackage/service-router/config/config.yaml`,其中`${agent_package_path}`需要替换为实际的打包路径。 - -配置项说明如下: - -```yaml -router.plugin: - # 是否开启dubbo区域路由 - enabled-dubbo-zone-router: false - # 是否开启spring cloud区域路由(预留配置,暂不支持) - enabled-spring-zone-router: false - # 是否开启注册插件(sermant-springboot-registry)区域路由 - enabled-registry-zone-router: false -``` - -- 配置路由生效规则 - -Sermant backend提供api的方式发布配置, 使用前需启动backend后台应用,配置发布接口如下: - -**URL** - -POST /publishConfig - -**请求Body** - -|参数|是否必填|参数类型|描述 -|---|---|---|---| -|key|√|String|配置的key| -|group|√|String|配置的组| -|content|√|String|配置文本| - -其中key值为sermant.plugin.router。 - -group需要配置为应用级别,即app=${yourApp}&&environment=${yourEnvironment},其中app默认为default,environment默认为空。 - -content为具体的路由规则。 - -### 生效规则示例及说明如下: - -```yaml -strategy: all # 生效策略:all(全部生效)/none(全不生效)/white(白名单)/black(黑名单) -value: # 下游服务名,多个下游用逗号分隔。当生效策略为white时,value为白名单,当生效策略为black时,value为黑名单 -``` - -**注意:新增配置时,请去掉注释,否则会导致新增失败。** - -- 启动应用 - -在附带agent启动时,按需加上以下参数: - -``` --Dservice_meta_zone=${zone} -``` - -参数说明如下: - -- ${zone}需替换为服务注册时的az。 - -## 结果验证 - -- 前提条件[正确打包Sermant](../../README.md) - -- 注册中心使用华为CSE,下载[Local-CSE](https://support.huaweicloud.com/devg-cse/cse_devg_0036.html) ,解压后按照文档说明进行启动 - -- 配置路由生效规则 - -调用接口`localhost:8900/publishConfig`, 请求参数如下: - -```json -{ - "content": "strategy: all", - "group": "app=default&&environment=", - "key": "sermant.plugin.router" -} -``` - -- 编译[消费者应用](../../../sermant-integration-tests/dubbo-test/dubbo-2-7-integration-consumer)与[生产者应用](../../../sermant-integration-tests/dubbo-test/dubbo-2-7-integration-provider) - -```shell -mvn clean package -``` - -- 启动消费者(zone为sz) - -```shell -java -Drouter_plugin_enabled_dubbo_zone_router=true -Dservice_meta_zone=sz -Dservicecomb_service_enableDubboRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar dubbo-integration-consumer.jar -``` - -- 启动生产者(zone为sz) - -```shell -java -Drouter_plugin_enabled_dubbo_zone_router=true -Dservice_meta_zone=sz -Dservicecomb_service_enableDubboRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar dubbo-integration-provider.jar -``` - -- 启动生产者(zone为gz) - -```shell -java -Drouter_plugin_enabled_dubbo_zone_router=true -Dservice_meta_zone=gz -Dservicecomb_service_enableDubboRegister=true -Dserver.port=28022 -Ddubbo.protocol.port=28822 -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar dubbo-integration-provider.jar -``` - -其中path需要替换为Sermant实际安装路径。 - -- 测试 - -当启动以上3个应用并正确配置路由生效规则后,通过http客户端工具访问,可以发现,请求会路由到zone为sz的生产者中。当停掉zone为sz的生产者后,请求会路由到zone为gz的生产者中 - -[返回**Sermant**说明文档](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/router/zone-router.md b/docs/user-guide/router/zone-router.md deleted file mode 100644 index 39b6a20ff3..0000000000 --- a/docs/user-guide/router/zone-router.md +++ /dev/null @@ -1,122 +0,0 @@ -# Zone Router - -[简体中文](zone-router-zh.md) | [English](zone-router.md) - -This document is used to introduce the usage of [zone router](../../../sermant-plugins/sermant-router). - -Tag Router referring [Tag Router](document.md). - -## Function - -In the case that microservices are deployed in multiple AZs (available zone), priority is given to filtering instances of the same AZ for invocation, and jumping to different AZs when all instances of the same AZ are unavailable. - -## Usage - -- Modify The [Plugin Configuration File](../../../sermant-plugins/sermant-router/config/config.yaml) On Demand. - -The file path is: `${agent_package_path}/agent/pluginPackage/service-router/config/config.yaml`. Please replace `${agent_package_path}` with the actual package path. - -The configuration items are described as follows: - -```yaml -router.plugin: - # Whether to enable dubbo zone router - enabled-dubbo-zone-router: false - # Whether to enable spring cloud zone router(Reserved configuration, not supported at this time) - enabled-spring-zone-router: false - # Whether to enable sermant-springboot-registry zone router - enabled-registry-zone-router: false -``` - -- Configure routing rules to take effect - -Sermant backend provides api way to publish the configuration, you need to start the backend application before use, the configuration publishing interface is as follows: - -**URL** - -POST /publishConfig - -**Request Body** - -|Params|Mandatory or not|Param type|Description -|---|---|---|---| -|key|√|String|configuration key| -|group|√|String|Configuration group, which is used to configure subscriptions| -|content|√|String|Configuration text, that is, specific routing rules| - -The key value needs to be sermant.plugin.router. - -The group needs to be configured to application level, i.e. app=${yourApp}&&environment=${yourEnvironment}, app defaults to default, environment defaults to empty. - -The content is the specific routing effective rule. - -### Examples of tag routing rules and descriptions are as follows: - -```yaml -strategy: all # Effective Strategy: all(All effective)/none(None effective)/white(White list)/black(black list) -value: # Downstream service name, with multiple downstreams separated by commas. When the effective policy is white, the value is white list, when the effective policy is black, the value is black list. -``` - -**Note: When adding a new configuration, please remove the comment, otherwise it will cause the addition to fail.** - -- Start the application - -Add the following parameters as required at the start of the attached agent: - -``` --Dservice_meta_zone=${zone} -``` - -The parameters are described as follows: - -- ${zone} needs to be replaced with the az at the time of service registration。 - -## Result Verification - -- Prerequisites [correctly packed Sermant](../../README.md) - -- Registration center using Huawei CSE, download [Local-CSE](https://support.huaweicloud.com/devg-cse/cse_devg_0036.html), unzip and follow the documentation to start. - -- Configuring Routing Effective Rules - -Calling the interface `localhost:8900/publishConfig`, with the following request parameters: - -```json -{ - "content": "strategy: all", - "group": "app=default&&environment=", - "key": "sermant.plugin.router" -} -``` - -- Compile [consumer demo](../../../sermant-integration-tests/dubbo-test/dubbo-2-7-integration-consumer) and [provider-demo](../../../sermant-integration-tests/dubbo-test/dubbo-2-7-integration-provider) - -```shell -mvn clean package -``` - -- Start the consumer(zone is sz) - -```shell -java -Drouter_plugin_enabled_dubbo_zone_router=true -Dservice_meta_zone=sz -Dservicecomb_service_enableDubboRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar dubbo-integration-consumer.jar -``` - -- Start the provider(zone is sz) - -```shell -java -Drouter_plugin_enabled_dubbo_zone_router=true -Dservice_meta_zone=sz -Dservicecomb_service_enableDubboRegister=true -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar dubbo-integration-provider.jar -``` - -- Start the provider(zone is gz) - -```shell -java -Drouter_plugin_enabled_dubbo_zone_router=true -Dservice_meta_zone=gz -Dservicecomb_service_enableDubboRegister=true -Dserver.port=28022 -Ddubbo.protocol.port=28822 -javaagent:${path}\agent\sermant-agent.jar=appName=default -jar dubbo-integration-provider.jar -``` - -${path} needs to be replaced with the actual Sermant installation path. - -- Testing - -After starting the above 3 applications and configuring the routing effective rules correctly, when accessingthrough the http client tool, we can be find that the request is routed to the producer with zone sz. When the producer with zone sz is disabled, the request is routed to the producer with zone gz. - -[Back to README of **Sermant** ](../../README.md) \ No newline at end of file diff --git a/docs/user-guide/springboot-registry/document-zh.md b/docs/user-guide/springboot-registry/document-zh.md deleted file mode 100644 index 681f0c770a..0000000000 --- a/docs/user-guide/springboot-registry/document-zh.md +++ /dev/null @@ -1,220 +0,0 @@ -# SpringBoot Registry - -[简体中文](document-zh.md) | [English](document.md) - -本篇文章主要介绍[SpringBoot注册插件](../../../sermant-plugins/sermant-springboot-registry)以及使用方法。 - -## 功能 - -该插件为纯SpringBoot应用提供服务注册发现能力,方便用户在不修改代码的前提下快速接入注册中心,同时提供服务超时重试的能力,实现服务调用的高可用。 - -插件的生效基于Url解析, 根据发起客户端调用Url解析下游服务,并根据负载均衡选择优选实例,动态替换Url, 完成服务调用。 - -目前Url支持的格式:http://www.domain.com/serviceName/apiPath - -其中`www.domain.com`为实际调用的域名,`serviceName`为下游的服务名,`apiPath`则为下游请求接口路径。 - - - -## 版本支持 - -注册中心支持: Zookeeper 3.4.x及以上 - -客户端支持: - -- HttpClient: 4.x -- HttpAsyncClient: 4.1.4 -- OkhttpClient: 2.x, 3.x, 4.x -- Feign(springcloud-openfeign-core): 2.1.x, 3.0.x -- RestTemplate(Spring-web): 5.1.x, 5.3.x - -框架支持:SpringBoot 1.5.10.Release及以上 - -## 使用说明 - -### 配置动态配置中心(可选) - -用户可基于配置文件配置或者采用环境变量方式配置。 - -(1)基于配置文件配置 - -您需找到配置文件[config.properties](https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/config.properties), 修改如下配置: - -```properties -# 配置中心地址 -dynamic.config.serverAddress=127.0.0.1:2181 -# 配置中心类型, 目前支持ZOOKEEPER与KIE -dynamic.config.dynamicConfigType=ZOOKEEPER -``` - -(2)基于环境变量配置 - -您可在应用启动时,增加环境变量进行指定,例如:`-Ddynamic.config.serverAddress=127.0.0.1:2181 -Ddynamic.config.dynamicConfigType=ZOOKEEPER` 便可达到上述配置文件的效果。 - -### 配置插件(可选) - -在sermant打包后,您可在路径`${agent path}/agent/pluginPackage/springboot-registry/config/config.yaml`找到该插件的配置文件, 配置如下所示: - -```yaml -sermant.springboot.registry: - realmName: www.domain.com # 该域名需替换为您的请求地址的域名! - -sermant.springboot.registry.lb: - lbType: RoundRobin # 负载均衡类型, 当前支持轮询(RoundRobin)、随机(Random)、响应时间权重(WeightedResponseTime)、最低并发数(BestAvailable) - registryAddress: 127.0.0.1:2181 # 注册中心地址(必填) - instanceCacheExpireTime: 0 # 实例过期时间, 单位秒, 若<=0则永不过期 - instanceRefreshInterval: 0 # 实例刷新时间, 单位秒, 必须小于instanceCacheExpireTime - refreshTimerInterval: 5 # 实例定时检查间隔, 判断实例是否过期, 若其大于instanceRefreshInterval, 则值设置为instanceRefreshInterval - - -``` - -如上配置, **请注意务必确保配置`realName`与`registryAddress`填写正确**, 否则插件不会生效! - -除以上用户需要注意的配置外,如下为可选配置, 用户可采用环境变量的方式进行配置 - -| 参数名 | 描述 | 默认值 | -| ------------------------------- | ------------------------------------------------------------ | ----------------- | -| connectionTimeoutMs | 连接ZK的超时时间 | 2000ms | -| readTimeoutMs | 连接ZK的响应超时时间 | 10000ms | -| retryIntervalMs | 连接ZK的重试间隔 | 3000ms | -| zkBasePath | ZK作为注册中心时注册的节点路径 | /sermant/services | -| registryCenterType | 注册中心类型, 目前仅支持Zookeeper | Zookeeper | -| maxRetry | 当调用发生超时时,最大重试次数 | 3次 | -| retryWaitMs | 重试等待时间 | 1000ms | -| enableSocketConnectTimeoutRetry | 是否在发生`SocketTimeoutException: connect timed out`进行重试 | true | -| enableSocketReadTimeoutRetry | 是否在发生`SocketTimeoutException: read timed out`进行重试 | true | -| enableTimeoutExRetry | 是否在发生`TimeoutException`进行重试 | true | -| specificExceptionsForRetry | 额外的重试异常 | 空 | -| statsCacheExpireTime | 统计指标的缓存时间,单位分钟 | 60Min | -| instanceStatTimeWindowMs | 指标统计时间窗口, 单位毫秒 | 600000ms | - -### 配置灰度策略(必须) - -若使插件生效,还需为插件配置灰度策略,首先说明下灰度策略。 - -灰度策略意在根据指定服务名判断需不需要为请求进行代理,替换url地址,当前灰度策略包含如下三种: - -- all, 即全量,不区分下游服务名,所有的服务url均代理替换 -- none, 与上相反 -- white, 白名单模式, 指定的服务集合才会代理请求。 - -其配置格式如下: - -```yaml -# 灰度策略类型 -strategy: all -# 白名单服务集合, 仅当strategy配置为white时生效 -value: service-b -``` - - - -#### **灰度策略下发** - -##### 基于backend下发 - -那如何配置下发灰度策略, 这里需要基于backend的下发接口进行配置下发,backend提供如下接口: - -URL `/publishConfig` - -请求参数如下: - -| 配置参数 | 说明 | -| -------- | ------------------------------------------------ | -| key | 配置键 | -| group | 配置的标签组 | -| content | 配置内容,即具体的规则配置,其格式均为`YAML`格式 | - -> 其中**group**的配置格式为k1=v1, 多个值使用"&"分隔,例如k1=v1&k2=v2, 代表该key绑定的标签组 - -默认插件会订阅分组`app=default&environment=`和`service=yourApplicationName&app=default&environment=` - -其中`yourApplicationName`为您当前的app的`spring.application.name`。若您想修改订阅分组, 您可设置如下环境变量进行指定: - -- `-Dservice.meta.application`, 可指定app的标签 -- `-Dservice.meta.environment`, 可指定environment的标签 - -以上,为配置流程,随后携带sermant启动即可完成。 - -##### 基于配置中心 - -当然此处您也可以直接基于配置中心客户端直接配置下发, 以zookeeper为例: - -(1)登录zookeeper 客户端 - -```shell -# windows -双击 zkCli.cmd -# linux -sh zkCli.sh -server localhost:2181 -``` - -(2)创建组路径 - -```shell -create /app=default&environment= "" -``` - -(3)创建该具体配置节点路径(`sermant.plugin.registry`) - -```shell -create /app=default&environment=/sermant.plugin.registry "strategy: all" -``` - - - -## 快速使用 - -下面以demo为例,演示如何使用该插件能力 - -### 环境准备 - -- JDK1.8及以上 -- Maven -- 完成下载[demo源码](https://github.com/huaweicloud/Sermant-examples/tree/springboor-registry-demo/registry-demo/springboot-registry-demo) -- 完成编译打包sermant - -### 编译打包demo应用 - -执行如下命令进行打包: - -```shell -mvn clean package -``` - -您可得到两个jar包,service-a.jar与service-b.jar, 调用关系为a->b - -### 启动demo应用 - -参考如下命令启动a应用 - -```shell -java --javaagent:${agent path}\sermant-agent-1.0.0\agent\sermant-agent.jar=appName=default -jar -Dserver.port=8989 service-a.jar -``` - -参考如下命令启动b应用 - -```shell -java --javaagent:${agent path}\sermant-agent-1.0.0\agent\sermant-agent.jar=appName=default -jar -Dserver.port=9999 service-b.jar -``` - -### 下发灰度策略 - -参考使用[配置灰度策略](#配置灰度策略(必须))的灰度策略进行下发, 下发如下配置 - -```json -{ - "key":"sermant.plugin.registry", - "group":"app=default&environment=", - "content":"strategy: all" -} -``` - -以上即对所有下游服务请求均受理。 - -### 验证 - -调用接口`localhost:8989/httpClientGet`, 判断接口是否成功返回, 若成功返回则说明插件已成功生效。 - -[返回**Sermant**说明文档](../../README-zh.md) diff --git a/docs/user-guide/springboot-registry/document.md b/docs/user-guide/springboot-registry/document.md deleted file mode 100644 index 3bf31f521c..0000000000 --- a/docs/user-guide/springboot-registry/document.md +++ /dev/null @@ -1,212 +0,0 @@ -# SpringBoot Registry - -[简体中文](document-zh.md) | [English](document.md) - -This article describes how to [SpringBoot registry plugin]((../../../sermant-plugins/sermant-springboot-registry)) and how to use it. - -## Ability - -This plugin provides service registration and discovery abilities for pure SpringBoot applications. Users can quickly access the registration center without modifying code. In addition, the plugin also provides the service timeout retry ability, achieving high availability of service invocation. - -The plugin takes effect based on URL resolution. The plugin parses downstream services based on the URL invoking by the client, selects a preferred instance based on load balancer, and dynamically replaces the URL to complete service invoking. - -Currently, URL formats are supported.:http://www.domain.com/serviceName/apiPath - -Just like the URL above, ` www.domain.com` indicates the domain name, `serviceName` indicates the downstream service name, and `apiPath` indicates the downstream request interface path. - -## Version Supports - -Reistry Center Support: Zookeeper 3.4.x and above - -Client Supports: - -- HttpClient: 4.x -- HttpAsyncClient: 4.1.4 -- OkhttpClient: 2.x, 3.x, 4.x -- Feign(springcloud-openfeign-core): 2.1.x, 3.0.x -- RestTemplate(Spring-web): 5.1.x, 5.3.x - -Application Framework Supports:SpringBoot 1.5.10.Release and above - -## Usage - -### (Optional) Configuring the Dynamic Configuration Center - -You can configure it based on the configuration file or by using environment variables. - -(1)Configuration based on the configuration file - -You need to find the configuration file [config.properties]((https://github.com/huaweicloud/Sermant/blob/develop/sermant-agentcore/sermant-agentcore-config/config/config.properties)) and modify the following configuration: - -```properties -# Configuration Center Address -dynamic.config.serverAddress=127.0.0.1:2181 -# Configuration Center Type, Currently, support ZOOKEEPER and KIE -dynamic.config.dynamicConfigType=ZOOKEEPER -``` - -(2)Configuration based on Environment - -You can add environment variables during application startup, for example, `-Ddynamic.config.serverAddress=127.0.0.1:2181 -Ddynamic.config.dynamicConfigType=ZOOKEEPER`. - -### (Optional) Configuring the Plugin - -After the sermant is packaged, you can find the configuration file of the plugin in `${agent path}/agent/pluginPackage/springboot-registry/config/config.yaml`. The configuration is as follows: - -```yaml -sermant.springboot.registry: - realmName: www.domain.com # Replace the domain name with the domain name of your request address. - -sermant.springboot.registry.lb: - lbType: RoundRobin # Load balancer type. The options are RoundRobin, Random, WeightedResponseTime, and BestAvailable. - registryAddress: 127.0.0.1:2181 # Registration Center Address (Mandatory) - instanceCacheExpireTime: 0 # Instance expiration time, in seconds. If the value is less than or equal to 0, the instance never expires. - instanceRefreshInterval: 0 # Instance refresh time, in seconds. The value must be less than the value of instanceCacheExpireTime. - refreshTimerInterval: 5 # Interval for checking whether the instance has expired. If the value is greater than the value of instanceRefreshInterval, the value is set to instanceRefreshInterval. -``` - -Ensure that the values of` realName` and `registryAddress` are correct. Otherwise, the plugin does not take effect. - -In addition to the preceding configurations, the following configurations are optional. You can configure the configurations by using environment variables. - -| Configuration | Desc | Default | -| ------------------------------- | ------------------------------------------------------------ | ----------------- | -| connectionTimeoutMs | Timeout interval for connecting to the ZooKeeper. | 2000ms | -| readTimeoutMs | Read timeout interval for connecting to the ZooKeeper. | 10000ms | -| retryIntervalMs | ZooKeeper connection retry interval | 3000ms | -| zkBasePath | Path of the node registered when the ZooKeeper as the registration center. | /sermant/services | -| registryCenterType | Registration center type. Currently, only ZooKeeper is supported. | Zookeeper | -| maxRetry | Maximum number of retries when a call timeout occurs | 3 times | -| retryWaitMs | Retry Wait Time | 1000ms | -| enableSocketConnectTimeoutRetry | Whether `SocketTimeoutException: connect timed out` to retry | true | -| enableSocketReadTimeoutRetry | Whether `SocketTimeoutException: read timed out` to retry | true | -| enableTimeoutExRetry | Indicates whether to retry when a `TimeoutException` occurs. | true | -| specificExceptionsForRetry | Extra retry exception | emptyList | -| statsCacheExpireTime | Indicates the cache duration of statistics indicators, in minutes. | 60Min | -| instanceStatTimeWindowMs | Indicates the time window for counter statistics, in milliseconds. | 600000ms | - -### (Mandatory) Configuring a Gray Policy - -To make the plugin take effect, you need to configure a gray policy for the plugin. - -The gray policy is used to determine whether a request needs to be proxyed based on the specified service name and replace the URL. Currently, the gray policy includes the following three types: - -- all,all service URLs are replaced by proxy, regardless of downstream service names. -- none, contrary to the above -- white, In trustlist mode, the specified service collection proxy requests. - -The configuration format is as follows: - -```yaml -# Gray Policy Type -strategy: all -# Trustlist service set. This parameter is valid only when strategy is set to white -value: service-b -``` - -#### **Gray Policy Delivery** - -##### Backend-Based Delivery - -How to configure and deliver a gray policy? You need to configure and deliver the gray policy based on the delivery interface of the backend. The backend provides the following interfaces: - -URL `/publishConfig` - -The request parameters are as follows:: - -| Configurations | Desc | -| -------------- | ------------------------------------------------------------ | -| key | Config key | -| group | Config Group | -| content | Configuration content, that is, the specific rule configuration, is in `YAML` format. | - -> The format of group is k1=v1, and multiple values are separated by ampersands (&). For example, k1=v1&k2=v2, indicating the label group bound to the key. - -The default scenario plugin subscribes the groups `app=default&environment=`和`service=yourApplicationName&app=default&environment=` - -`yourApplicationName` is the `spring.application.name` of your current app. To modify a subscription group, you can set the following environment variables: - -- `-Dservice.meta.application`, Specifies the tag of an app. -- `-Dservice.meta.environment`, Specifies the label of the environment. - -The preceding figure shows the configuration process. The configuration process is complete after the service is started with the sermant message. - -##### Based On The Configuration Center - -You can also directly deliver configurations based on the configuration center client. The following uses ZooKeeper as an example. - -(1)Login the ZooKeeper Client. - -```shell -# windows -double click zkCli.cmd -# linux -sh zkCli.sh -server localhost:2181 -``` - -(2)Create Group Path - -```shell -create /app=default&environment= "" -``` - -(3)Create configuration node named `sermant.plugin.registry` - -```shell -create /app=default&environment=/sermant.plugin.registry "strategy: all" -``` - -## Quick Use - -The following uses the demo as an example to describe how to use the plugin ability. - -### Environment Preparation - -- JDK1.8 and above -- Maven -- Downloaded [demo souce code](https://github.com/huaweicloud/Sermant-examples/tree/springboor-registry-demo/registry-demo/springboot-registry-demo) -- package sermant - -### Package Demo - -Run the following command to pack the package: - -```shell -mvn clean package -``` - -You can get two JAR packages, service-a.jar and service-b.jar, and the calling relationship is a->b. - -### Start the Demo Application. - -Run the following command to start application a: - -```shell -java --javaagent:${agent path}\sermant-agent-1.0.0\agent\sermant-agent.jar=appName=default -jar -Dserver.port=8989 service-a.jar -``` - -Run the following command to start application b: - -```shell -java --javaagent:${agent path}\sermant-agent-1.0.0\agent\sermant-agent.jar=appName=default -jar -Dserver.port=9999 service-b.jar -``` - -### Delivering a Gray Policy - -[Deliver the gray policy](#(Mandatory) Configuring-a-Gray-Policy) by referring to. Deliver the following configurations: - -```json -{ - "key":"sermant.plugin.registry", - "group":"app=default&environment=", - "content":"strategy: all" -} -``` - -All downstream service requests will handled by plugin. - -### Validation - -Invoke the` localhost:8989/httpClientGet` interface to check whether the interface is successfully returned. If yes, the plugin has taken effect. - -[[Back to README of **Sermant** ](../../README.md)] diff --git a/docs/user-guide/template/document.md b/docs/user-guide/template/document.md deleted file mode 100644 index 83ab3d37b4..0000000000 --- a/docs/user-guide/template/document.md +++ /dev/null @@ -1,9 +0,0 @@ -# plugin name - -[插件目录](../../sermant-plugins/sermant-pluginName) - -[定位 是什么]: todo -[功能 做什么]: todo -[使用方式 怎么做]: todo - -[返回**Sermant**说明文档](../../README.md) diff --git a/sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/subscribe/AbstractGroupConfigSubscriber.java b/sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/subscribe/AbstractGroupConfigSubscriber.java index 9992eac7a8..1e4a710d62 100644 --- a/sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/subscribe/AbstractGroupConfigSubscriber.java +++ b/sermant-agentcore/sermant-agentcore-core/src/main/java/com/huaweicloud/sermant/core/plugin/subscribe/AbstractGroupConfigSubscriber.java @@ -24,6 +24,7 @@ import java.util.Locale; import java.util.Map; +import java.util.logging.Logger; /** * 配置订阅 @@ -32,7 +33,9 @@ * @since 2022-04-13 */ public abstract class AbstractGroupConfigSubscriber implements ConfigSubscriber { - private final DynamicConfigService dynamicConfigService; + private static final Logger LOGGER = LoggerFactory.getLogger(); + + private DynamicConfigService dynamicConfigService; /** * 订阅的插件名称 @@ -56,7 +59,13 @@ protected AbstractGroupConfigSubscriber(DynamicConfigService dynamicConfigServic */ protected AbstractGroupConfigSubscriber(DynamicConfigService dynamicConfigService, String pluginName) { if (dynamicConfigService == null) { - this.dynamicConfigService = ServiceManager.getService(DynamicConfigService.class); + try { + this.dynamicConfigService = ServiceManager.getService(DynamicConfigService.class); + } catch (IllegalArgumentException e) { + LOGGER.severe("dynamicConfigService is not enabled!"); + this.dynamicConfigService = null; + } + } else { this.dynamicConfigService = dynamicConfigService; } @@ -65,6 +74,10 @@ protected AbstractGroupConfigSubscriber(DynamicConfigService dynamicConfigServic @Override public boolean subscribe() { + if (dynamicConfigService == null) { + LOGGER.severe("dynamicConfigService is null, fail to subscribe!"); + return false; + } if (!isReady()) { LoggerFactory.getLogger().warning("The group subscriber is not ready, may be service name is null"); return false; diff --git a/sermant-injector/src/test/resources/test.json b/sermant-injector/src/test/resources/test.json index f274436404..1682919751 100644 --- a/sermant-injector/src/test/resources/test.json +++ b/sermant-injector/src/test/resources/test.json @@ -2,7 +2,7 @@ "kind": "AdmissionReview", "apiVersion": "admission.k8s.io/v1beta1", "request": { - "uid": "57d4d575-4a5d-444a-8b21-b325d3d11b45", + "uid": "c57327fb-27c5-4d26-bc49-4732569f3c1d", "kind": { "group": "", "version": "v1", @@ -23,26 +23,26 @@ "version": "v1", "resource": "pods" }, - "namespace": "mesh", + "namespace": "default", "operation": "CREATE", "userInfo": { - "username": "foo", - "uid": "f8b49463-63cd-434e-865d-1a2f8679ccec", + "username": "system:serviceaccount:kube-system:replicaset-controller", + "uid": "584907d5-656e-4d6f-969c-90569b29b56e", "groups": [ - "system:bar", - "system:foo", - "system:bar" + "system:serviceaccounts", + "system:serviceaccounts:kube-system", + "system:authenticated" ] }, "object": { "kind": "Pod", "apiVersion": "v1", "metadata": { - "generateName": "bar-test-f8b49463-", + "generateName": "testapp-7c8756758c-", "creationTimestamp": null, "labels": { - "app": "bar-test", - "pod-template-hash": "f8b49463", + "app": "testapp", + "pod-template-hash": "7c8756758c", "sermant-injection": "enabled" }, "annotations": { @@ -54,79 +54,171 @@ { "apiVersion": "apps/v1", "kind": "ReplicaSet", - "name": "bar-test-f8b49463", - "uid": "4a28cea0-2a40-4e22-95a5-f61d2a5878bd", + "name": "testapp-7c8756758c", + "uid": "aa70b547-02ac-4d23-ae49-0305aad0c7a2", "controller": true, "blockOwnerDeletion": true } + ], + "managedFields": [ + { + "manager": "kube-controller-manager", + "operation": "Update", + "apiVersion": "v1", + "time": "2022-12-22T12:28:22Z", + "fieldsType": "FieldsV1", + "fieldsV1": { + "f:metadata": { + "f:generateName": {}, + "f:labels": { + ".": {}, + "f:app": {}, + "f:env.sermant.io/key1": {}, + "f:env.sermant.io/key2": {}, + "f:pod-template-hash": {}, + "f:sermant-injection": {} + }, + "f:ownerReferences": { + ".": {}, + "k:{\"uid\":\"aa70b547-02ac-4d23-ae49-0305aad0c7a2\"}": { + ".": {}, + "f:apiVersion": {}, + "f:blockOwnerDeletion": {}, + "f:controller": {}, + "f:kind": {}, + "f:name": {}, + "f:uid": {} + } + } + }, + "f:spec": { + "f:containers": { + "k:{\"name\":\"testapp\"}": { + ".": {}, + "f:env": { + ".": {}, + "k:{\"name\":\"az\"}": { + ".": {}, + "f:name": {}, + "f:value": {} + }, + "k:{\"name\":\"dubbo.registry.address\"}": { + ".": {}, + "f:name": {}, + "f:value": {} + }, + "k:{\"name\":\"sermant_springboot_registry_lb_registryAddress\"}": { + ".": {}, + "f:name": {}, + "f:value": {} + } + }, + "f:image": {}, + "f:imagePullPolicy": {}, + "f:name": {}, + "f:ports": { + ".": {}, + "k:{\"containerPort\":8104,\"protocol\":\"TCP\"}": { + ".": {}, + "f:containerPort": {}, + "f:protocol": {} + } + }, + "f:resources": {}, + "f:terminationMessagePath": {}, + "f:terminationMessagePolicy": {} + } + }, + "f:dnsPolicy": {}, + "f:enableServiceLinks": {}, + "f:imagePullSecrets": { + ".": {}, + "k:{\"name\":\"foo-secret\"}": { + ".": {}, + "f:name": {} + } + }, + "f:restartPolicy": {}, + "f:schedulerName": {}, + "f:securityContext": {}, + "f:terminationGracePeriodSeconds": {} + } + } + } ] }, "spec": { "volumes": [ { - "name": "foo", - "secret": { - "secretName": "bar" + "name": "kube-api-access-sd2sx", + "projected": { + "sources": [ + { + "serviceAccountToken": { + "expirationSeconds": 3607, + "path": "token" + } + }, + { + "configMap": { + "name": "kube-root-ca.crt", + "items": [ + { + "key": "ca.crt", + "path": "ca.crt" + } + ] + } + }, + { + "downwardAPI": { + "items": [ + { + "path": "namespace", + "fieldRef": { + "apiVersion": "v1", + "fieldPath": "metadata.namespace" + } + } + ] + } + } + ] } } ], "containers": [ { - "name": "foo-test", - "image": "bar-test:1.0.1", + "name": "testapp", + "image": "swr.cn-north-5.myhuaweicloud.com/pengyuyi/testapp:3.10.0", "ports": [ { - "containerPort": 100, - "protocol": "TCP" - }, - { - "containerPort": 101, - "protocol": "TCP" - }, - { - "containerPort": 102, + "containerPort": 8104, "protocol": "TCP" } ], "env": [ { - "name": "SERVICECOMB.SERVICE.ENABLEDUBBOREGISTER", - "value": "true" - }, - { - "name": "SERVICECOMB.SERVICE.ENABLESPRINGREGISTER", - "value": "false" - }, - { - "name": "SERVICECOMB.SERVICE.SSLENABLED", - "value": "false" + "name": "dubbo.registry.address", + "value": "zookeeper://192.168.1.1:1111" }, { - "name": "SERVICECOMB.SERVICE.OPENMIGRATION", - "value": "false" + "name": "az", + "value": "sz" }, { - "name": "DYNAMIC.CONFIG.PLUGIN.ENABLEDYNAMICCONFIG", - "value": "false" + "name": "sermant_springboot_registry_lb_registryAddress", + "value": "192.168.1.1:1111" } ], "resources": {}, "volumeMounts": [ { - "name": "bar", + "name": "kube-api-access-sd2sx", "readOnly": true, - "mountPath": "foo" + "mountPath": "/var/run/secrets/kubernetes.io/serviceaccount" } ], - "lifecycle": { - "preStop": { - "exec": { - "command": [ - "echo \"1111111111111111111111111111\"" - ] - } - } - }, "terminationMessagePath": "/dev/termination-log", "terminationMessagePolicy": "File", "imagePullPolicy": "IfNotPresent" @@ -135,31 +227,44 @@ "restartPolicy": "Always", "terminationGracePeriodSeconds": 30, "dnsPolicy": "ClusterFirst", - "serviceAccountName": "foo", - "serviceAccount": "bar", + "serviceAccountName": "default", + "serviceAccount": "default", "securityContext": {}, "imagePullSecrets": [ { - "name": "foo" + "name": "foo-secret" } ], - "schedulerName": "bar", + "schedulerName": "default-scheduler", "tolerations": [ { - "key": "bar", + "key": "node.kubernetes.io/not-ready", "operator": "Exists", "effect": "NoExecute", "tolerationSeconds": 300 }, { - "key": "foo", + "key": "node.kubernetes.io/unreachable", "operator": "Exists", "effect": "NoExecute", "tolerationSeconds": 300 } ], "priority": 0, - "enableServiceLinks": true + "dnsConfig": { + "options": [ + { + "name": "single-request-reopen", + "value": "" + }, + { + "name": "timeout", + "value": "2" + } + ] + }, + "enableServiceLinks": true, + "preemptionPolicy": "PreemptLowerPriority" }, "status": {} }, diff --git a/sermant-plugins/sermant-flowcontrol/flowcontrol-common/src/main/java/com/huawei/flowcontrol/common/init/FlowControlInitServiceImpl.java b/sermant-plugins/sermant-flowcontrol/flowcontrol-common/src/main/java/com/huawei/flowcontrol/common/init/FlowControlInitServiceImpl.java index 74183d4df4..917daa73dd 100644 --- a/sermant-plugins/sermant-flowcontrol/flowcontrol-common/src/main/java/com/huawei/flowcontrol/common/init/FlowControlInitServiceImpl.java +++ b/sermant-plugins/sermant-flowcontrol/flowcontrol-common/src/main/java/com/huawei/flowcontrol/common/init/FlowControlInitServiceImpl.java @@ -23,6 +23,7 @@ import com.huawei.flowcontrol.common.entity.FlowControlServiceMeta; import com.huawei.flowcontrol.common.factory.FlowControlThreadFactory; +import com.huaweicloud.sermant.core.common.LoggerFactory; import com.huaweicloud.sermant.core.operation.OperationManager; import com.huaweicloud.sermant.core.operation.initializer.DynamicConfigServiceInitializer; import com.huaweicloud.sermant.core.plugin.config.PluginConfigManager; @@ -36,6 +37,7 @@ import java.util.concurrent.SynchronousQueue; import java.util.concurrent.ThreadPoolExecutor; import java.util.concurrent.TimeUnit; +import java.util.logging.Logger; /** * 流控插件 公共能力 统一初始化入口 @@ -44,8 +46,10 @@ * @since 2022-01-25 */ public class FlowControlInitServiceImpl implements PluginService { + private static final Logger LOGGER = LoggerFactory.getLogger(); + private final ThreadPoolExecutor executor = new ThreadPoolExecutor(1, 1, 0, - TimeUnit.SECONDS, new SynchronousQueue<>(), new FlowControlThreadFactory("FLOW_CONTROL_INIT_THREAD")); + TimeUnit.SECONDS, new SynchronousQueue<>(), new FlowControlThreadFactory("FLOW_CONTROL_INIT_THREAD")); private final FlowControlLifeCycle flowControlLifeCycle = new FlowControlLifeCycle(); @@ -70,16 +74,22 @@ static class FlowControlLifeCycle implements Runnable { @Override public void run() { + DynamicConfigService dynamicConfigService = getDynamicConfigService(); + if (dynamicConfigService == null) { + LOGGER.severe("dynamicConfigService is null, fail to init FlowControlLifeCycle!"); + return; + } + ConfigSubscriber configSubscriber; final FlowControlConfig pluginConfig = PluginConfigManager.getPluginConfig(FlowControlConfig.class); if (pluginConfig.isUseCseRule()) { // 适配cse, 开始适配cse的专用配置监听器 configSubscriber = new CseGroupConfigSubscriber(FlowControlServiceMeta.getInstance().getServiceName(), - new RuleDynamicConfigListener(), getDynamicConfigService(), "FlowControl"); + new RuleDynamicConfigListener(), dynamicConfigService, "FlowControl"); } else { configSubscriber = new DefaultGroupConfigSubscriber( FlowControlServiceMeta.getInstance().getServiceName(), - new RuleDynamicConfigListener(), getDynamicConfigService(), + new RuleDynamicConfigListener(), dynamicConfigService, "FlowControl"); } configSubscriber.subscribe(); @@ -89,13 +99,19 @@ private DynamicConfigService getDynamicConfigService() { final FlowControlConfig pluginConfig = PluginConfigManager.getPluginConfig(FlowControlConfig.class); DynamicConfigService dynamicConfigService; - // 根据使用需求选择是否使用自身配置中心 - if (pluginConfig.isUseAgentConfigCenter()) { - dynamicConfigService = ServiceManager.getService(DynamicConfigService.class); - } else { - dynamicConfigService = OperationManager.getOperation(DynamicConfigServiceInitializer.class) - .initKieDynamicConfigService(pluginConfig.getConfigKieAddress(), pluginConfig.getProject()); + try { + // 根据使用需求选择是否使用自身配置中心 + if (pluginConfig.isUseAgentConfigCenter()) { + dynamicConfigService = ServiceManager.getService(DynamicConfigService.class); + } else { + dynamicConfigService = OperationManager.getOperation(DynamicConfigServiceInitializer.class) + .initKieDynamicConfigService(pluginConfig.getConfigKieAddress(), pluginConfig.getProject()); + } + } catch (IllegalArgumentException e) { + LOGGER.severe("dynamicConfigService is not enabled!"); + dynamicConfigService = null; } + return dynamicConfigService; } } diff --git a/sermant-plugins/sermant-router/router-config-service/src/main/java/com/huaweicloud/sermant/router/config/handler/RouterConfigHandler.java b/sermant-plugins/sermant-router/router-config-service/src/main/java/com/huaweicloud/sermant/router/config/handler/RouterConfigHandler.java index 66ecd6cbcb..ce1afdd921 100644 --- a/sermant-plugins/sermant-router/router-config-service/src/main/java/com/huaweicloud/sermant/router/config/handler/RouterConfigHandler.java +++ b/sermant-plugins/sermant-router/router-config-service/src/main/java/com/huaweicloud/sermant/router/config/handler/RouterConfigHandler.java @@ -81,14 +81,10 @@ public boolean shouldHandle(String key) { private Map getRouteRuleMap(DynamicConfigEvent event) { String content = event.getContent(); - Map>> load = yaml.load(content); - if (CollectionUtils.isEmpty(load)) { + Map routeRuleMap = yaml.load(content); + if (CollectionUtils.isEmpty(routeRuleMap)) { return Collections.emptyMap(); } - Map> servicecomb = load.get(RouterConstant.ROUTER_CONFIG_SERVICECOMB_KEY); - if (CollectionUtils.isEmpty(servicecomb)) { - return Collections.emptyMap(); - } - return servicecomb.get(RouterConstant.ROUTER_CONFIG_ROUTE_RULE_KEY); + return routeRuleMap; } } \ No newline at end of file diff --git a/sermant-plugins/sermant-service-registry/spring-cloud-registry-plugin/src/main/java/com/huawei/registry/auto/sc/ServiceCombRegistry.java b/sermant-plugins/sermant-service-registry/spring-cloud-registry-plugin/src/main/java/com/huawei/registry/auto/sc/ServiceCombRegistry.java index abd3f85d91..b4b6ca7bcb 100644 --- a/sermant-plugins/sermant-service-registry/spring-cloud-registry-plugin/src/main/java/com/huawei/registry/auto/sc/ServiceCombRegistry.java +++ b/sermant-plugins/sermant-service-registry/spring-cloud-registry-plugin/src/main/java/com/huawei/registry/auto/sc/ServiceCombRegistry.java @@ -50,12 +50,22 @@ public void register(ServiceCombRegistration registration) { GraceHelper.configWarmUpParams(registration.getMetadata(), PluginConfigManager.getPluginConfig(GraceConfig.class)); ZoneUtils.setZone(registration.getMetadata()); - getRegisterCenterService().register(new FixedResult()); + RegisterCenterService registerService = getRegisterCenterService(); + if (registerService == null) { + LOGGER.severe("registerCenterService is null, fail to register!"); + return; + } + registerService.register(new FixedResult()); } @Override public void deregister(ServiceCombRegistration registration) { - getRegisterCenterService().unRegister(); + RegisterCenterService registerService = getRegisterCenterService(); + if (registerService == null) { + LOGGER.severe("registerCenterService is null, fail to unRegister!"); + return; + } + registerService.unRegister(); } @Override @@ -65,7 +75,12 @@ public void close() { @Override public void setStatus(ServiceCombRegistration registration, String status) { - getRegisterCenterService().updateInstanceStatus(status); + RegisterCenterService registerService = getRegisterCenterService(); + if (registerService == null) { + LOGGER.severe("registerCenterService is null, fail to update instance status!"); + return; + } + registerService.updateInstanceStatus(status); } @Override @@ -75,7 +90,11 @@ public String getStatus(ServiceCombRegistration registration) { private RegisterCenterService getRegisterCenterService() { if (registerCenterService == null) { - registerCenterService = PluginServiceManager.getPluginService(RegisterCenterService.class); + try { + registerCenterService = PluginServiceManager.getPluginService(RegisterCenterService.class); + } catch (IllegalArgumentException e) { + LOGGER.severe("registerCenterService is not enabled!"); + } } return registerCenterService; } diff --git a/sermant-plugins/sermant-service-registry/spring-cloud-registry-plugin/src/main/java/com/huawei/registry/inject/grace/ContextClosedEventListener.java b/sermant-plugins/sermant-service-registry/spring-cloud-registry-plugin/src/main/java/com/huawei/registry/inject/grace/ContextClosedEventListener.java index 1dea673c71..a83861b0dc 100644 --- a/sermant-plugins/sermant-service-registry/spring-cloud-registry-plugin/src/main/java/com/huawei/registry/inject/grace/ContextClosedEventListener.java +++ b/sermant-plugins/sermant-service-registry/spring-cloud-registry-plugin/src/main/java/com/huawei/registry/inject/grace/ContextClosedEventListener.java @@ -19,6 +19,7 @@ import com.huawei.registry.config.GraceConfig; import com.huawei.registry.services.GraceService; +import com.huaweicloud.sermant.core.common.LoggerFactory; import com.huaweicloud.sermant.core.plugin.config.PluginConfigManager; import com.huaweicloud.sermant.core.plugin.service.PluginServiceManager; @@ -26,6 +27,8 @@ import org.springframework.context.event.EventListener; import org.springframework.stereotype.Component; +import java.util.logging.Logger; + /** * spring关闭时间监听器 * @@ -34,13 +37,20 @@ */ @Component public class ContextClosedEventListener { - private final GraceService graceService; + private static final Logger LOGGER = LoggerFactory.getLogger(); + + private GraceService graceService; /** * 构造方法 */ public ContextClosedEventListener() { - graceService = PluginServiceManager.getPluginService(GraceService.class); + try { + graceService = PluginServiceManager.getPluginService(GraceService.class); + } catch (IllegalArgumentException exception) { + LOGGER.severe("graceService is not enabled"); + graceService = null; + } } /** @@ -48,7 +58,7 @@ public ContextClosedEventListener() { */ @EventListener(value = ContextClosedEvent.class) public void listener() { - if (!isEnableGraceDown()) { + if (!isEnableGraceDown() || graceService == null) { return; } graceService.shutdown();