{"id":13511785,"url":"https://github.com/megaease/easeagent","last_synced_at":"2025-05-16T17:04:07.920Z","repository":{"id":40456755,"uuid":"76088862","full_name":"megaease/easeagent","owner":"megaease","description":"An agent component for the Java system","archived":false,"fork":false,"pushed_at":"2024-10-14T10:42:41.000Z","size":20588,"stargazers_count":581,"open_issues_count":16,"forks_count":125,"subscribers_count":25,"default_branch":"master","last_synced_at":"2025-04-14T10:42:46.792Z","etag":null,"topics":["apm","distributed-tracing","java","javaagent","metrics","microservices","monitoring","observability","opentracing","prometheus","servicemesh","spring-cloud","tracing","zipkin","zipkin-brave"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/megaease.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-12-10T03:49:26.000Z","updated_at":"2025-04-04T04:25:23.000Z","dependencies_parsed_at":"2024-01-31T16:34:20.768Z","dependency_job_id":"0bad790c-e2ec-4486-bb7f-3f114c051656","html_url":"https://github.com/megaease/easeagent","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megaease%2Feaseagent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megaease%2Feaseagent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megaease%2Feaseagent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/megaease%2Feaseagent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/megaease","download_url":"https://codeload.github.com/megaease/easeagent/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254573589,"owners_count":22093731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apm","distributed-tracing","java","javaagent","metrics","microservices","monitoring","observability","opentracing","prometheus","servicemesh","spring-cloud","tracing","zipkin","zipkin-brave"],"created_at":"2024-08-01T03:01:10.757Z","updated_at":"2025-05-16T17:04:07.868Z","avatar_url":"https://github.com/megaease.png","language":"Java","funding_links":[],"categories":["Java","应用分析与监控"],"sub_categories":[],"readme":"# EaseAgent\n\nA lightweight \u0026 opening Java Agent for Cloud-Native and APM system\n\n- [EaseAgent](#easeagent)\n  - [Overview](#overview)\n    - [Purpose](#purpose)\n    - [Principles](#principles)\n  - [Features](#features)\n  - [Architecture Diagram](#architecture-diagram)\n      - [Description](#description)\n  - [QuickStart](#quickstart)\n    - [Get And Set Environment Variable](#get-and-set-environment-variable)\n      - [Setup Environment Variable](#setup-environment-variable)\n      - [Download](#download)\n      - [Build From the Source](#build-from-the-source)\n      - [Get Configuration file](#get-configuration-file)\n    - [Monitor Spring Petclinic](#monitor-spring-petclinic)\n      - [Prerequisites](#prerequisites)\n      - [Initialize and Start the project](#initialize-and-start-the-project)\n      - [Metric](#metric)\n      - [Tracing](#tracing)\n      - [Build Spring Petclinic](#build-spring-petclinic)\n    - [Add an Enhancement Plugin](#add-an-enhancement-plugin)\n  - [User Manual](#user-manual)\n  - [Enhancement Plugin Development Guide](#enhancement-plugin-development-guide)\n  - [Report Plugin Development Guide](#report-plugin-development-guide)\n  - [Community](#community)\n  - [Licenses](#licenses)\n\n## Overview\n- EaseAgent is the underlying component that provides non-intrusive extensions to applications of the Java ecosystem. \n- 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](https://research.google/pubs/pub36356/) paper.\n- EaseAgent also can work with Cloud-Native architecture. For example, it can help Service Mesh (especially for [EaseMesh](https://github.com/megaease/easemesh/) ) to do some control panel work.\n- EaseAgent supports plugins mechanism development, which is easy to extend or add new functionality.\n\n### Purpose\n- EaseAgent can be a Java agent for APM(Application Performance Management) system.\n- EaseAgent collects the basic metrics and the service tracing logs, which is very helpful for performance analysis and troubleshooting.\n- EaseAgent is compatible with mainstream monitoring ecosystems, such as Kafka, ElasticSearch, Prometheus, Zipkin, etc.\n- EaseAgent majorly focuses on the Spring Boot development environments, but users can support any Java ecosystem applications through plugins.\n- EaseAgent can support scenario-specific business requirements through the plugin mechanism, such as traffic redirection, traffic coloring, etc.\n\n### Principles\n- Safe to Java application/service.\n- Instrumenting a Java application in a non-intrusive way.\n- Lightweight and very low CPU, memory, and I/O resource usage.\n- Highly extensible, users can easily do extensions through a simple and clear plugin interface.\n- Design for Micro-Service architecture, collecting the data from a service perspective.\n\n## Features\n* Easy to use. It is right out of the box for Metrics, Tracing and Logs collecting.\n    * Collecting Metric \u0026 Tracing Logs.\n        * `JDBC 4.0`\n        * `HTTP Servlet`、`HTTP Filter`\n        * `Spring Boot 2.2.x`: `WebClient` 、 `RestTemplate`、`FeignClient`\n        * `RabbitMQ Client 5.x`、 `Kafka Client 2.4.x`\n        * `Jedis 3.5.x`、 `Lettuce 5.3.x (sync、async)`\n        * `ElasticSearch Client \u003e= 7.x (sync、async)`\n        * `Mongodb Client \u003e=4.0.x (sync、async)`\n        * `Motan`\n        * `Dubbo`\n        * `SofaRpc \u003e= 5.3.0`\n    * Collecting Access Logs.\n        * `HTTP Servlet`、`HTTP Filter`\n        * `Spring Cloud Gateway`\n    * Instrumenting the `traceId` and `spanId` into user application logging automatically\n    * Supplying the `health check` endpoint\n    * Supplying the `readiness check` endpoint for `SpringBoot2.2.x`\n    * Supplying the `agent info` endpoint\n    \n*  Data Reports\n    * Console Reporter.\n    * Prometheus Exports.\n    * Http Reporter.\n    * Kafka Reporter.\n    * Custom Reporter.\n\n* Easy to Extend\n    * Simple and clear Plugin Interface, creating a plugin as few as three classes.\n    * Extremely cleanly packaged `Tracing` and `Metric` API, with a small amount of code to achieve business support.\n\n* Standardization\n    * The tracing data format is fully compatible with the Zipkin data format.\n    * Metric data format fully supports integration with `Prometheus`.\n    * The application log format is fully compatible with the `Opentelemetry` data format.\n\n\n## Architecture Diagram\n![image](./doc/images/EaseAgent-Architecture-Base-v2.0.png)\n\n#### Description\n**Plugin Framework** in `core` module is base on [Byte buddy](https://github.com/raphw/byte-buddy) technology.\n\n1. 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 the `Interceptor`.\n2. 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 of `Agent Common Method Advice`, which finds the `Agent Interceptor Chain` by the `Unique Index` and calls the `before` method of each Interceptor in the chain in order of priority.\n3. Normally, both the `Metric Interceptor` and the `Tracing Interceptor` are in the agent interceptor chain and are called sequentially.\n4. According to call the `Metric API` and `Tracing API` in interceptors, the `Metric` and `Tracing` information will be stored in `MetricRegistry` and `Tracing`.\n5. The `Reporter` module will get information from `MetricRegistry` and `Tracing` and send it to `Kafka`.\n6. The `after` method of each interceptor in the `Agent Interceptor Chain` will be invoked in the reverse order of the `before` invoked at last.\n7. The `tracing` data can be sent to `kafka` server or `zipkin` server, the `metric` data can be sent to `kafka` server and pull by `Prometheus` server.\n\n## QuickStart\n\n### Get And Set Environment Variable\n\nSetup Environment Variable and then download the latest release of `easeagent.jar` or build it from the source.\n\n#### Setup Environment Variable\n```\n$ cd ~/easeagent #[Replace with agent path]\n$ export EASE_AGENT_PATH=`pwd` # export EASE_AGENT_PATH=[Replace with agent path]\n$ mkdir plugins\n```\n\n#### Download\nDownload `easeagent.jar` from releases [releases](https://github.com/megaease/easeagent/releases).\n\n```\n$ curl -Lk https://github.com/megaease/easeagent/releases/latest/download/easeagent.jar -O\n```\n\n#### Build From the Source\n\nYou need Java 1.8+ and git:\n\nDownload EaseAgent with `git clone https://github.com/megaease/easeagent.git`.\n```\n$ cd easeagent\n$ mvn clean package -Dmaven.test.skip\n$ cp ./build/target/easeagent-dep.jar $EASE_AGENT_PATH/easeagent.jar\n```\nThe `./build/target/easeagent-dep.jar` is the agent jar with all the dependencies.\n\n\u003e For the Windows platform, please make sure git `core.autocrlf` is set to false before git clone.\n\u003e You can use `git config --global core.autocrlf false` to modify `core.autocrlf`.\n\n[How to use easeagent.jar on host?](doc/how-to-use/use-on-host.md)\n\n[How to use easeagent.jar in docker?](doc/how-to-use/use-in-docker.md)\n\n#### Get Configuration file\nExtracting the default configuration file.\n```\n$ cd $EASE_AGENT_PATH\n$ jar xf easeagent.jar agent.properties easeagent-log4j2.xml\n```\n\nBy default, there is an agent.properties configuration file, which is configured to print all output data to the console.\n\n### Monitor Spring Petclinic\n#### Prerequisites\n- Make sure you have installed the docker, docker-compose in your environment.\n- Make sure your docker version is higher than v19.+.\n- Make sure your docker-compose version is higher than v2.+.\n\n[Project Details](https://github.com/megaease/easeagent-spring-petclinic)\n\n#### Initialize and Start the project\n```\n$ git clone https://github.com/megaease/easeagent-spring-petclinic.git\n$ cd easeagent-spring-petclinic\n$ git submodule update --init\n$ ./spring-petclinic.sh start\n```\n\n\u003e The script will download the latest release of EaseAgent. \n\u003e If you want to use your own built EaseAgent, copy it to the directory: `easeagent/downloaded`\n\u003e\u003e ```$ cp $EASE_AGENT_PATH/easeagent.jar  easeagent/downloaded/easeagent-latest.jar``` \n\nIt requires `Docker` to pull images from the docker hub, be patient. \n\nOpen Browser to visit grafana UI: [http://localhost:3000](http://localhost:3000).\n\n#### Metric\nClick the `search dashboards`, the first icon in the left menu bar. Choose the `spring-petclinic-easeagent` to open the dashboard we prepare for you.\n\nPrometheus Metric Schedule: [Prometheus Metric](doc/prometheus-metric-schedule.md)\n\n![metric](doc/images/grafana-metric.png)\n\n#### Tracing\n\nIf 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.\n\n![tracing](doc/images/grafana-tracing.png)\n\n#### Build Spring Petclinic\n\n[Spring Petclinic Demo](doc/spring-petclinic-demo.md)\n\n### Add an Enhancement Plugin\n[Add a Demo Plugin to EaseAgent](doc/add-plugin-demo.md)\n\n## User Manual\nFor more information, please refer to the [User Manual](./doc/user-manual.md).\n\n## Enhancement Plugin Development Guide\nRefer to [Plugin Development Guide](./doc/development-guide.md).\n\n## Report Plugin Development Guide\nReport plugin enables user report tracing/metric data to different kinds of the backend in a different format.\n\nRefer to [Report Plugin Development Guide](./doc/report-development-guide.md)\n\n## Community\n\n* [Github Issues](https://github.com/megaease/easeagent/issues)\n* [Join Slack Workspace](https://join.slack.com/t/openmegaease/shared_invite/zt-upo7v306-lYPHvVwKnvwlqR0Zl2vveA) for requirement, issue and development.\n* [MegaEase on Twitter](https://twitter.com/megaease)\n\nIf you have any questions, welcome to discuss them in our community. Welcome to join!\n\n\n## Licenses\nEaseAgent is licensed under the Apache License, Version 2.0. See [LICENSE](./LICENSE) for the full license text.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegaease%2Feaseagent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmegaease%2Feaseagent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmegaease%2Feaseagent/lists"}