EaseAgent
A lightweight & opening Java Agent for Cloud-Native and APM system
- EaseAgent
Overview
- EaseAgent is the underlying component that provides non-intrusive extensions to applications of the Java ecosystem.
- EaseAgent can collect distributed application tracing, metrics, and logs, which could be used in the APM system and improve the observability of a distributed system. for the tracing, EaseAgent follows the Google Dapper paper.
- EaseAgent also can work with Cloud-Native architecture. For example, it can help Service Mesh (especially for EaseMesh ) to do some control panel work.
- EaseAgent supports plugins mechanism development, which is easy to extend or add new functionality.
Purpose
- EaseAgent can be a Java agent for APM(Application Performance Management) system.
- EaseAgent collects the basic metrics and the service tracing logs, which is very helpful for performance analysis and troubleshooting.
- EaseAgent is compatible with mainstream monitoring ecosystems, such as Kafka, ElasticSearch, Prometheus, Zipkin, etc.
- EaseAgent majorly focuses on the Spring Boot development environments, but users can support any Java ecosystem applications through plugins.
- EaseAgent can support scenario-specific business requirements through the plugin mechanism, such as traffic redirection, traffic coloring, etc.
Principles
- Safe to Java application/service.
- Instrumenting a Java application in a non-intrusive way.
- Lightweight and very low CPU, memory, and I/O resource usage.
- Highly extensible, users can easily do extensions through a simple and clear plugin interface.
- Design for Micro-Service architecture, collecting the data from a service perspective.
Features
-
Easy to use. It is right out of the box for Metrics, Tracing and Logs collecting.
- 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 (sync、async)
ElasticSearch Client >= 7.x (sync、async)
Mongodb Client >=4.0.x (sync、async)
Motan
Dubbo
SofaRpc >= 5.3.0
- Collecting Access Logs.
HTTP Servlet
、HTTP Filter
Spring Cloud Gateway
- Instrumenting the
traceId
andspanId
into user application logging automatically - Supplying the
health check
endpoint - Supplying the
readiness check
endpoint forSpringBoot2.2.x
- Supplying the
agent info
endpoint
- Collecting Metric & Tracing Logs.
-
Data Reports
- Console Reporter.
- Prometheus Exports.
- Http Reporter.
- Kafka Reporter.
- Custom Reporter.
-
Easy to Extend
- Simple and clear Plugin Interface, creating a plugin as few as three classes.
- Extremely cleanly packaged
Tracing
andMetric
API, with a small amount of code to achieve business support.
-
Standardization
- The tracing data format is fully compatible with the Zipkin data format.
- Metric data format fully supports integration with
Prometheus
. - The application log format is fully compatible with the
Opentelemetry
data format.
Architecture Diagram
Description
Plugin Framework in core
module is base on Byte buddy technology.
- Easeagent's plugin defines where (which classes and methods) to make enhancements by implementing the
Points
and what to do at the point of enhancement by implementing theInterceptor
. - When the program invokes the enhanced method of class defined by Points, the
unique index
(uid) owned by the method will be used as a parameter to call the common interface ofAgent Common Method Advice
, which finds theAgent Interceptor Chain
by theUnique Index
and calls thebefore
method of each Interceptor in the chain in order of priority. - Normally, both the
Metric Interceptor
and theTracing Interceptor
are in the agent interceptor chain and are called sequentially. - According to call the
Metric API
andTracing API
in interceptors, theMetric
andTracing
information will be stored inMetricRegistry
andTracing
. - The
Reporter
module will get information fromMetricRegistry
andTracing
and send it toKafka
. - The
after
method of each interceptor in theAgent Interceptor Chain
will be invoked in the reverse order of thebefore
invoked at last. - The
tracing
data can be sent tokafka
server orzipkin
server, themetric
data can be sent tokafka
server and pull byPrometheus
server.
QuickStart
Get And Set Environment Variable
Setup Environment Variable and then download the latest release of easeagent.jar
or build it from the source.
Setup Environment Variable
$ cd ~/easeagent #[Replace with agent path]
$ export EASE_AGENT_PATH=`pwd` # export EASE_AGENT_PATH=[Replace with agent path]
$ mkdir plugins
Download
Download easeagent.jar
from releases releases.
$ curl -Lk https://github.com/megaease/easeagent/releases/latest/download/easeagent.jar -O
Build From the Source
You need Java 1.8+ and git:
Download EaseAgent with git clone https://github.com/megaease/easeagent.git
.
$ cd easeagent
$ mvn clean package -Dmaven.test.skip
$ cp ./build/target/easeagent-dep.jar $EASE_AGENT_PATH/easeagent.jar
The ./build/target/easeagent-dep.jar
is the agent jar with all the dependencies.
For the Windows platform, please make sure git
core.autocrlf
is set to false before git clone. You can usegit config --global core.autocrlf false
to modifycore.autocrlf
.
How to use easeagent.jar on host?
How to use easeagent.jar in docker?
Get Configuration file
Extracting the default configuration file.
$ cd $EASE_AGENT_PATH
$ jar xf easeagent.jar agent.properties easeagent-log4j2.xml
By default, there is an agent.properties configuration file, which is configured to print all output data to the console.
Monitor Spring Petclinic
Prerequisites
- Make sure you have installed the docker, docker-compose in your environment.
- Make sure your docker version is higher than v19.+.
- Make sure your docker-compose version is higher than v2.+.
Initialize and Start the project
$ git clone https://github.com/megaease/easeagent-spring-petclinic.git
$ cd easeagent-spring-petclinic
$ git submodule update --init
$ ./spring-petclinic.sh start
The script will download the latest release of EaseAgent. If you want to use your own built EaseAgent, copy it to the directory:
easeagent/downloaded
$ cp $EASE_AGENT_PATH/easeagent.jar easeagent/downloaded/easeagent-latest.jar
It requires Docker
to pull images from the docker hub, be patient.
Open Browser to visit grafana UI: http://localhost:3000.
Metric
Click the search dashboards
, the first icon in the left menu bar. Choose the spring-petclinic-easeagent
to open the dashboard we prepare for you.
Prometheus Metric Schedule: Prometheus Metric
Tracing
If you want to check the tracing-data, you could click the explore in the left menu bar. Click the Search - beta to switch search mode. Click search query button in the right up corner, there is a list containing many tracing. Choose one to click.
Build Spring Petclinic
Add an Enhancement Plugin
Add a Demo Plugin to EaseAgent
User Manual
For more information, please refer to the User Manual.
Enhancement Plugin Development Guide
Refer to Plugin Development Guide.
Report Plugin Development Guide
Report plugin enables user report tracing/metric data to different kinds of the backend in a different format.
Refer to Report Plugin Development Guide
Community
- Github Issues
- Join Slack Workspace for requirement, issue and development.
- MegaEase on Twitter
If you have any questions, welcome to discuss them in our community. Welcome to join!
Licenses
EaseAgent is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.