Quick‐Start

Target Applicaiton

• The target application is recommended to use Spring Framework 6.x and Spring Boot 3.x versions. It is also advised to configure Spring Actuator to the latest version. Lower versions may not function properly or could encounter compatibility issues.

• Before running the Traffic Hunter agent, you need to install Spring Actuator in your application. Additionally, update your application.yml file with the following configuration

• The agent collects metrics using JMX (Java Management Extensions), making the configuration of Actuator mandatory.

implementation 'org.springframework.boot:spring-boot-starter-actuator'

management:
  endpoints:
    jmx:
      exposure:
        include: "*"

server:
  tomcat:
    mbeanregistry:
      enabled: true

spring:
  datasource:
    hikari:
      register-mbeans: true
    tomcat:
      jmx-enabled: true

  jmx:
    unique-names: true

Agent

Download

curl -L -O https://github.com/yungwangoh/traffic_hunter/releases/download/v1.0.0/traffic-hunter-agent-v1.0.0.jar

wget https://github.com/yungwangoh/traffic_hunter/releases/download/v1.0.0/traffic-hunter-agent-v1.0.0.jar

Step.1

• An environment configuration file is required for the agent. The file format should be in YAML.
• Create a Yaml file and place it in the desired path.

agent:
  name: myAgent
  jar: /jar-path/traffic-hunter-agent-v1.0.0.jar
  server-uri: localhost:9100
  target-uri: localhost:8080                                                                                               
  interval: 5
  retry:
     max-attempt: 10
     backoff:
       interval-millis: 1000
       multiplier: 2

• name : Specifies the unique name of the agent. (e.g., myAgent).

• jar : The file path to the agent's JAR file. (e.g., /path/my-agent.jar).

• server-uri : Server uri (e.g., localhost:9100).

• target-uri : Target App uri (e.g., localhost:8080).

• interval : The interval (in seconds) at which the agent sends metrics or traces to the server. (e.g., 5 seconds).

• retry : A section defining the retry mechanism for the agent when it fails to send data to the server.

  • max-attempt : The maximum number of retry attempts the agent makes in case of failure (e.g., 10).

  • backoff: A subsection defining the backoff policy for retries.

    • interval-millis: The initial delay (in milliseconds) between retry attempts (e.g., 1000 milliseconds).

    • multiplier: The multiplier for the exponential backoff. After each retry attempt, the delay increases by multiplying the previous delay by this value (e.g., 2).

Step.2

• Place the YAML file in the desired directory and configure the application to launch with the Java agent at runtime.

java -javaagent:/path/my-agent.jar -Dtraffichunter.config=/path/agent-env.yml

• -javaagent : agent jar path
• -Dtraffichunter.config : yaml file path

Step.3

• It is highly recommended to start the server before starting the agent.
• After launching the agent, wait approximately 8 seconds until the message start metric send!! appears. Metrics will begin transmitting once this message is displayed. Please wait until it appears.

Notes

• If you discover the file /home/traffic-hunter/key/xxx_agent_id.txt, do not delete it under any circumstances. This .txt file contains the identification code of the agent. Deleting it may cause data loss issues during the agent's runtime.

DataBase

• TimescaleDB enhances APM systems by providing efficient time-series data storage with advanced compression, reducing storage costs while retaining performance. Its seamless integration as a PostgreSQL extension allows developers to leverage familiar SQL for querying metrics, traces, and logs. This makes it ideal for handling high-throughput APM data, enabling real-time analytics and historical insights without additional database complexity.

• TimescaleDB Install

Server

• The server only requires additional configuration for database-related information.
• The following code represents the actual YAML configuration file for the server environment. This file requires DB_IP, DB_NAME, USER_NAME, and PASSWORD.
• This server uses port 9100.

spring:
  datasource:
    driver-class-name: org.postgresql.Driver
    username: ${USER_NAME}
    password: ${PASSWORD}
    url: jdbc:postgresql://${DB_IP}/${DB_NAME}

JAR

Download

curl -L -O https://github.com/yungwangoh/traffic_hunter/releases/download/v1.0.0/traffic-hunter-server-v1.0.0.jar

wget https://github.com/yungwangoh/traffic_hunter/releases/download/v1.0.0/traffic-hunter-agent-v1.0.0.jar

Command

java -DDB_IP=localhost:5432 -DDB_NAME=db_name -DUSER_NAME=admin -DPASSWORD=password -jar Traffic-Hunter-Server.jar

Docker

Download

docker pull qkfks1234/traffic-hunter:1.0.0

• linux/amd64

docker pull --platform linux/amd64 qkfks1234/traffic-hunter:1.0.0

• linux/arm64

docker pull --platform linux/arm64 qkfks1234/traffic-hunter:1.0.0

Command

docker run -d -p 9100:9100 --name Traffic-Hunter \
 -e DB_IP=localhost:5432 \
 -e DB_NAME=db_name \
 -e USER_NAME=admin \
 -e PASSWORD=password \
 traffic-hunter:1.0.0

Visualization

• Grafana is used in conjunction with TimescaleDB to deliver an optimal UI for monitoring and visualization.

• Grafana Install

Import Dashboard

• Install dashboard json.

curl -L -O https://github.com/yungwangoh/traffic_hunter/releases/download/v1.0.0/traffic-hunter-visualization.json

wget https://github.com/yungwangoh/traffic_hunter/releases/download/v1.0.0/traffic-hunter-visualization.json

Step.1

• Enter grafana dashboards tap

Step.2

• New -> Import

Step.3

• Upload dashboard json -> Load