eggfly/easeagent

A java agent for APM

• Overview
  • Purpose & Principles
  • Architecture Diagram
• Features
• QuickStart
  • Download
  • Build From Source
• Documentation
  • Agent Configuration
  • Health Check Endpoint
  • Readiness Check Endpoint
  • Tracing
  • Metrics
    • Prometheus Metrics Support
• Development Guide
• Licenses

Overview

Purpose

EaseAgent is an APM tool under the Java system, used in a distributed system developed by Java. It provides cross-service call chain tracking and performance information collection for distributed systems, helps users analyze the overall structure of the distributed system and the call relationships between services and components, thereby improving the efficiency of troubleshooting.

Principles

• No invasion
• Service based view
• High performance

Architecture Diagram

Features

• Collect Metric and Tracing information
  • JDBC4.0 SQL
  • 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
• Collect Access Log
  • Http Servlet、Http Filter
  • Spring Cloud Gateway
• Support traceId and spanId inject into user application
• Support health check endpoint
• Support readiness check endpoint for SpringBoot2.2.x

QuickStart

Download

Download easeagent.jar from releases releases

or

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

Build From Source

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

cd easeagent
mvn clean package -am -pl build

A generated ./build/target/easeagent-dep.jar is the agent jar with all the dependencies.

Step 1

Extract default configuration files

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

# metric output
observability.metrics.[xxxx].appendType=console

# tracings output
observability.tracings.output.enabled=false

Step 3

Clone demo source code and build

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

Step 4

Run java application with agent in console

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

java -javaagent:/[user path]/easeagent.jar=/{path}/agent.properties -Deaseagent.server.port=9900 -jar spring-petclinic-vets-service/target/spring-petclinic-vets-service-2.4.2.jar

java -javaagent:/[user path]/easeagent.jar=/{path}/agent.properties -Deaseagent.server.port=9901 -jar spring-petclinic-visits-service/target/spring-petclinic-visits-service-2.4.2.jar

java -javaagent:/[user path]/easeagent.jar=/{path}/agent.properties -Deaseagent.server.port=9902 -jar spring-petclinic-customers-service/target/spring-petclinic-customers-service-2.4.2.jar

java -javaagent:/[user path]/easeagent.jar=/{path}/agent.properties -Deaseagent.server.port=9903 -jar spring-petclinic-api-gateway/target/spring-petclinic-api-gateway-2.4.2.jar

Step 5

add config 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

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

Documentation

Agent Configuration

Health Check Endpoint

User can use the following URL to support health check and liveness check

http://[ip]:[easeagent.server.port]/health

Readiness Check Endpoint

User can use the following URL to support health check in SpringBoot 2.2.x

http://[ip]:[easeagent.server.port]/health/readiness

Tracing

EaseAgent use brave to collect tracing information.The data format stored in Kafka is Zipkin Data Model. User can send tracing information to Zipkin server.

Metrics

EaseAgent use io.dropwizard.metrics to collect metric information.

For more metric information, please refer to the User Manual

Development-Guide

Refer to Development-Guide

Licenses

EaseAgent is licensed under the Apache License, Version 2.0. See LICENSE for the full license text.