An agent component for Java system.

• Overview
  • Purpose
  • Principles
  • Architecture Diagram
• Features
• QuickStart
  • Download
  • Build From Source
• User Manual
• Development Guide
• Licenses

• EaseAgent is a Java agent for APM(Application Performance Management) system.
• EaseAgent majorly focuses on the Spring Boot development environments.
• EaseAgent is compatible with mainstream monitoring ecosystems, such as Kafka, ElasticSearch, Prometheus, Zipkin, etc.
• EaseAgent collects the basic metrics and the service tracking logs, which is very helpful for performance analysis and troubleshooting.

• Design for Micro-Service architecture, collecting the data from a service perspective.
• Instrumenting a Java application in a non-intrusive way.
• Lightweight and very low CPU, memory, and I/O resource usage.
• Safe to Java application/service.

Instrumenting the method base on Byte buddy technology.

net.bytebuddy.asm.Advice.OnMethodEnter, net.bytebuddy.asm.Advice.OnMethodExit

1. When the program invokes the enhanced method of class, the method which has the annotation (OnMethodEnter) will be invoked at first.
2. Method Advice will invoke Metric Interceptor and Tracing Interceptor to processing.
3. Metric and Tracing information will be stored in MetricRegistry and Tracing.
4. The Reporter module will get information from MetricRegistry and Tracing and send it to Kafka.
5. The method which has the annotation (OnMethodExit) will be invoked at last.

• Collecting Metric & Tracing Logs.
  • JDBC 4.0
  • HTTP Servlet、HTTP Filter
  • Spring Boot 2.2.x: WebClient 、 RestTemplate、FeignClient
  • RabbitMQ Client 5.x、 Kafka Client 2.4.x
  • Jedis 3.5.x、 Lettuce 5.3.x
• Collecting Access Logs.
  • HTTP Servlet、HTTP Filter
  • Spring Cloud Gateway
• Instrumenting the traceId and spanId automatically
• Supplying the health check endpoint
• Supplying the readiness check endpoint for SpringBoot2.2.x

Download easeagent.jar from releases releases.

or

$ curl -Lk https://github.com/megaease/easeagent/releases/download/{tag}/easeagent.jar -O

Download EaseAgent with git clone https://github.com/megaease/easeagent.git.

$ cd easeagent
$ mvn clean package -am -pl build
```****
The `./build/target/easeagent-dep.jar` is the agent jar with all the dependencies.

> Windows platform user please make sure git `core.autocrlf` is set to false before git clone.
> You can use `git config --global core.autocrlf false` to modify `core.autocrlf`.

### Step 1
Extracting the default configuration file.

$ jar xf easeagent.jar agent.properties log4j2.xml

### Step 2
* Modify service name, default configuration is unknown-service.

name=[app-name]

* Modify kafka server config, default configuration is `127.0.0.1:9092`.

observability.outputServer.bootstrapServer = [ip:port]

* Modify output configuration, if you want to see log information in console.

observability.metrics.[xxxx].appendType=console

observability.tracings.output.enabled=false

* Sending tracing data to zipkin server

observability.tracings.output.target=zipkin

observability.tracings.output.target.zipkinUrl=http://localhost:9411/api/v2/spans

### Step 3
Building the demo application.

$ git clone https://github.com/akwei/spring-petclinic-microservices.git $ cd spring-petclinic-microservices $ mvn -DskipTests=true package

### Step 4
Run the demo application with EaseAgent.

$ java -jar spring-petclinic-config-server/target/spring-petclinic-config-server-2.4.2.jar

$ java -jar spring-petclinic-discovery-server/target/spring-petclinic-discovery-server-2.4.2.jar

$ export EASE_AGENT_PATH=[Replace with agent path] $ java "-javaagent:${EASE_AGENT_PATH}/easeagent-dep.jar=${EASE_AGENT_PATH}/agent.properties" -Deaseagent.server.port=9900 -jar spring-petclinic-vets-service/target/spring-petclinic-vets-service-2.4.2.jar

$ export EASE_AGENT_PATH=[Replace with agent path] $ java "-javaagent:${EASE_AGENT_PATH}/easeagent-dep.jar=${EASE_AGENT_PATH}/agent.properties" -Deaseagent.server.port=9901 -jar spring-petclinic-visits-service/target/spring-petclinic-visits-service-2.4.2.jar

$ export EASE_AGENT_PATH=/[Replace with agent path] $ java "-javaagent:${EASE_AGENT_PATH}/easeagent-dep.jar=${EASE_AGENT_PATH}/agent.properties" -Deaseagent.server.port=9902 -jar spring-petclinic-customers-service/target/spring-petclinic-customers-service-2.4.2.jar

$ export EASE_AGENT_PATH=[Replace with agent path] $ java "-javaagent:${EASE_AGENT_PATH}/easeagent-dep.jar=${EASE_AGENT_PATH}/agent.properties" -Deaseagent.server.port=9903 -jar spring-petclinic-api-gateway/target/spring-petclinic-api-gateway-2.4.2.jar

### Step 5
Adding the following configuration in `prometheus.yml`

• job_name: 'petclinic-vets-service' static_configs:

  • targets: ['localhost:9900'] metrics_path: "/prometheus/metrics"

• job_name: 'petclinic-visits-service' static_configs:

  • targets: ['localhost:9901'] metrics_path: "/prometheus/metrics"

• job_name: 'petclinic-customers-service' static_configs:

  • targets: ['localhost:9902'] metrics_path: "/prometheus/metrics"

• job_name: 'petclinic-api-gateway' static_configs:

  • targets: ['localhost:9903'] metrics_path: "/prometheus/metrics"

Start Prometheus

$ ./prometheus --config.file=prometheus.yml

### Step 6
Open Browser to visit [http://localhost:8080](http://localhost:8080).

After visit more pages, open Prometheus manager [http://localhost:9090](http://localhost:9090), and search `_00GET__owners`. You will see as following.

![image](./doc/images/prometheus-demo-1.png)

## User Manual
For more information, please refer to the [User Manual](./doc/user-manual.md).

## Development Guide
Refer to [Development-Guide](./doc/development-guide.md).

## Licenses
EaseAgent is licensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) for the full license text.