Skip to content

Supplementary Document #351

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
zhao-kun merged 3 commits into from
Sep 5, 2025
Merged

Supplementary Document #351

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4d57f34
doc: supplementary Document
observeralone Sep 4, 2025
4ce2c11
doc: update spring-boot-upgrade.md
observeralone Sep 4, 2025
9d0c42d
doc: add release and change message to spring-boot-upgrade.md
observeralone Sep 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
9 changes: 9 additions & 0 deletions build/src/main/resources/agent.properties
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,15 @@ plugin.observability.elasticsearch.metric.url=/platform-metrics
# plugin.observability.httpServlet.metric.url=/application-metrics
# plugin.observability.httpServlet.metric.appendType=kafka
#
#
# -------------------- tomcat ---------------------
# plugin.observability.tomcat.tracing.enabled=true
# plugin.observability.tomcat.metric.enabled=true
# plugin.observability.tomcat.metric.interval=30
# plugin.observability.tomcat.metric.topic=application-metrics
# plugin.observability.tomcat.metric.url=/application-metrics
# plugin.observability.tomcat.metric.appendType=kafka
#
# -------------------- jdbc ---------------------
## jdbc tracing
# plugin.observability.jdbc.tracing.enabled=true
Expand Down
59 changes: 59 additions & 0 deletions doc/spring-boot-upgrade.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Spring Boot upgrade

## Background

Different versions of spring-boot may use different technologies, depend on different jar packages, and implement
different methods.

For example, in spring-boot 2 and spring-boot 3, the httpserver of spring-boot 2 uses httpservlet, while the httpserver
of spring-boot 3 uses tomcat.

Some classes or methods have been deprecated after upgrading to spring-boot 3, and the old sampling entry points will
also be deprecated.

Therefore, different entry points and different sampling implementations are required according to different code
versions.

## Plugin Dependencies

### jdk dependencies

| spring-boot 2.x | spring-boot 3.x |
|:----------------|:----------------|
| jdk8 | jdk17 |

### plugin dependencies

| plugin name | spring-boot 2.x jar | spring-boot 3.x jar |
|:------------------|:--------------------|:--------------------------------------------------|
| httpURLConnection | httpurlconnection | httpurlconnection-jdk17 |
| httpServlet | httpservlet | |
| tomcat | | tomcat-jdk17 |
| springGateway | spring-gateway | spring-boot-3.5.3/spring-boot-gateway-3.5.3 |
| resTemplate | springweb | spring-boot-3.5.3/spring-boot-rest-template-3.5.3 |
| serviceName | servicename | spring-boot-3.5.3/spring-boot-servicename-3.5.3 |

## Base config

When your code uses Spring Boot 3.x.x, it means that your code depends on JDK 17+ and Spring Boot 3+.

In this case, you need to add two configurations for the agent to take effect:

```properties
runtime.code.version.points.jdk=jdk17
runtime.code.version.points.spring-boot=3.x.x
```

## Change Tag
release and change message: [Release-v2.3.0](https://github.com/megaease/easeagent/releases/tag/v2.3.0)

## Features
Easy to upgrade. If you upgrade your spring-boot version in the future, you only need to add the missing plugins.

If HTTP Sever is changed from tomcat to jetty, add the jetty plugin.

If there are incompatible methods in the plug-in below spring-boot-3.5.3, you only need to copy spring-boot-3.5.3 to a higher version, find the incompatible class or method, and implement the sampling logic.

Add different versions of development methods: [development-guide code version](./development-guide.md#code-version)


28 changes: 18 additions & 10 deletions doc/user-manual.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,8 @@ $ java "-javaagent:${EASE_AGENT_PATH}/easeagent.jar" -jar user-app.jar
* `plugins`:
* servicename: `default`,`2.x.x`
* spring-gateway: `default`,`2.x.x`
* springweb: `default`,`2.x.x`
* springweb(resTemplate): `default`,`2.x.x`
* springweb(feignClient,webclient): `default`
* spring-boot-gateway-3.5.3: `3.x.x`
* spring-boot-rest-template-3.5.3: `3.x.x`
* spring-boot-servicename-3.5.3: `3.x.x`
Expand All @@ -138,6 +139,11 @@ runtime.code.version.points.jdk=jdk17
runtime.code.version.points.spring-boot=3.x.x
```

###### about doc
[spring-boot-3.x.x-demo](spring-boot-3.x.x-demo.md)

[spring-boot-upgrade](spring-boot-upgrade.md)

#### Internal HTTP Server
EaseAgent opens port `9900` by default to receive configuration change notifications and Prometheus requests.

Expand Down Expand Up @@ -323,6 +329,7 @@ Supported components and corresponding namespaces:
| Plugin/Components | Namespace | Description |
|-------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| httpservlet | `httpServlet` | Http Request Metric |
| tomcat | `tomcat` | Http Request Metric |
| spring-gateway | `springGateway` | Http Request Metric |
| jdbcConnection | `jdbcConnection` | JDBC Connection Metric |
| jdbcStatement | `jdbcStatement` | JDBC SQL Metric. When using SQL as a tag, the string length of SQL is often very long, which will consume network bandwidth and CPU to a great extent. Our solution is to use SQL's MD5 as an indicator, which is associated with the storage and front-end.Closed configuration: `plugin.observability.jdbc.sql.compress.enabled=false` |
Expand All @@ -334,7 +341,7 @@ Supported components and corresponding namespaces:
| JVM Memory | `jvmMemory` | JVM Memory Metric |
| dubbo | `dubbo` | dubbo Metric |
| motan | `motan` | Motan Metric |
| sofarpc | `sofarpc` | SOFARPC Metric |
| sofarpc | `sofarpc` | SOFARPC Metric |

#### Application Log
Application log modules collecting application logs printed by the application.
Expand Down Expand Up @@ -521,14 +528,14 @@ Response Body:
EaseAgent use [brave](https://github.com/openzipkin/brave) to collect tracing logs.The data format stored in `Kafka` is [Zipkin Data Model](https://zipkin.io/pages/data_model.html). User can send tracing logs to [Zipkin server](https://zipkin.io/pages/quickstart.html).

### Tracing Component
| Component Type | Component | Reference |
| -------------- |-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| HTTP Client | `RestTemplate`、 `WebClient`、 `FeignClient` | [brave-instrumentation-http](https://github.com/openzipkin/brave/tree/master/instrumentation/http) |
| HTTP Server | `Servlet`、`Filter` | [brave-instrumentation-http](https://github.com/openzipkin/brave/tree/master/instrumentation/http) |
| DataBase | `JDBC` | [Brave](https://github.com/openzipkin/brave/tree/master/brave) |
| Cache | `Jedis`、`Lettuce` | [Brave](https://github.com/openzipkin/brave/tree/master/brave) |
| Message | `RabbitMQ`、`Kafka` | [brave-instrumentation-messaging](https://github.com/openzipkin/brave/tree/master/instrumentation/messaging) 、[Brave Kafka instrumentation](https://github.com/openzipkin/brave/tree/master/instrumentation/kafka-clients) |
| Logging | `Log4j2`、`Logback` | [brave-context-log4j2](https://github.com/openzipkin/brave/tree/master/context/log4j2) 、[brave-context-slf4j](https://github.com/openzipkin/brave/tree/master/context/slf4j) |
| Component Type | Component | Reference |
| -------------- |------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| HTTP Client | `RestTemplate`、 `WebClient`、 `FeignClient` | [brave-instrumentation-http](https://github.com/openzipkin/brave/tree/master/instrumentation/http) |
| HTTP Server | `Servlet`、`Tomcat`、`Filter` | [brave-instrumentation-http](https://github.com/openzipkin/brave/tree/master/instrumentation/http) |
| DataBase | `JDBC` | [Brave](https://github.com/openzipkin/brave/tree/master/brave) |
| Cache | `Jedis`、`Lettuce` | [Brave](https://github.com/openzipkin/brave/tree/master/brave) |
| Message | `RabbitMQ`、`Kafka` | [brave-instrumentation-messaging](https://github.com/openzipkin/brave/tree/master/instrumentation/messaging) 、[Brave Kafka instrumentation](https://github.com/openzipkin/brave/tree/master/instrumentation/kafka-clients) |
| Logging | `Log4j2`、`Logback` | [brave-context-log4j2](https://github.com/openzipkin/brave/tree/master/context/log4j2) 、[brave-context-slf4j](https://github.com/openzipkin/brave/tree/master/context/slf4j) |
| RPC | `AlibabaDubbo`、`ApacheDubbo`、`Motan`,`SOFARPC` | [brave-instrumentation-dubbo](https://github.com/openzipkin/brave/tree/master/instrumentation/dubbo) 、[brave-instrumentation-dubbo-rpc](https://github.com/openzipkin/brave/tree/master/instrumentation/dubbo-rpc)、[brave-instrumentation-rpc](https://github.com/openzipkin/brave/tree/master/instrumentation/rpc) |

### Tracing Component Config Description
Expand Down Expand Up @@ -654,6 +661,7 @@ For Example: EaseAgent collect metric of HTTP Request. The collected metric data
For different kind of metrics, we have different schemas:

#### HTTP Request
`httpServlet` and `Tomcat` both support HTTP Request
HTTP Request schema describes key metrics of service APIs, which include:
* Total execution count (cnt, errcnt)
* Throughput (m1, m5, m15)
Expand Down
Loading