Quickstart guide

Traffic Hunter Quickstart

Target Applicaiton

The target application is recommended to use Spring Framework 6.2+ and Spring Boot 3.2+ 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

traffichunter-javaagent.tar is a TAR archive that contains the following two files:

javaagent-bootstrap.jar - agent boot
javaagent-extension.jar - agent engine

These files are part of the Java agent component of the TrafficHunter project.

curl -L -O https://github.com/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-javaagent.tar

wget https://github.com/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-javaagent.tar

tar -xvf traffichunter-javaagent.tar

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: payments-service-agent
  jar: /jar-path/javaagent-bootstrap.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 service name of the agent. (e.g., payments-service).
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/javaagent-bootstrap.jar
-Dtraffichunter.config=/path/agent-env.yml
-Dtraffichunter.javaagent.transform.debug=false
-Dtraffichunter.javaagent.exporter.debug=false
-Dtraffichunter.javaagent.zipkin.endpoint=http://localhost:9411/api/v2/spans
-Dtraffichunter.javaagent.banner=true
-jar /path/myJar.jar

-javaagent : agent jar path
-Dtraffichunter.config : yaml file path
-Dtraffichunter.javaagent.trasform.debug : true or false
-Dtraffichunter.javaagent.exporter.debug : true or false
-Dtraffichunter.javaagent.zipkin.endpoint : zipkin path (default http://localhost:9411/api/v2/spans)
-Dtraffichunter.javaagent.banner : true or false

Step.3

It is highly recommended to start the server before starting the agent.
After launching the agent, wait approximately 10 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/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-server.jar

wget https://github.com/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-server.jar

Command

java -DDB_IP=localhost:5432 -DDB_NAME=db_name -DUSER_NAME=admin -DPASSWORD=password -jar traffichunter-server.jar

Docker (Sorry, not supported)

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/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-visualization.json

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

Step.1

Enter grafana dashboards tap

Step.2

New -> Import

Step.3

Upload dashboard json -> Load

PreviousIntroduction NextNotes

Last updated 1 month ago