# Quickstart guide ## *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. ```gradle implementation 'org.springframework.boot:spring-boot-starter-actuator' ``` ```yaml 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. ```bash curl -L -O https://github.com/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-javaagent.tar ``` ```bash wget https://github.com/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-javaagent.tar ``` ```bash 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. ```yaml 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. ```bash 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 ) * `-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](https://docs.timescale.com/self-hosted/latest/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. ```yaml spring: datasource: driver-class-name: org.postgresql.Driver username: ${USER_NAME} password: ${PASSWORD} url: jdbc:postgresql://${DB_IP}/${DB_NAME} ``` ### JAR **Download** ```bash curl -L -O https://github.com/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-server.jar ``` ```bash wget https://github.com/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-server.jar ``` **Command** ```bash java -DDB_IP=localhost:5432 -DDB_NAME=db_name -DUSER_NAME=admin -DPASSWORD=password -jar traffichunter-server.jar ``` ### Docker (Sorry, not supported) **Download** ```bash docker pull qkfks1234/traffic-hunter:1.0.0 ``` * linux/amd64 ```bash docker pull --platform linux/amd64 qkfks1234/traffic-hunter:1.0.0 ``` * linux/arm64 ```bash docker pull --platform linux/arm64 qkfks1234/traffic-hunter:1.0.0 ``` **Command** ```bash 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](https://grafana.com/docs/grafana/latest/setup-grafana/installation/) ### Import Dashboard * Install dashboard json. ```bash curl -L -O https://github.com/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-visualization.json ``` ```bash wget https://github.com/traffic-hunter/traffic_hunter/releases/download/v1.1.0/traffichunter-visualization.json ``` **Step.1** * Enter grafana dashboards tap ![스크린샷 2024-12-14 오후 10 50 32](https://github.com/user-attachments/assets/45b32ba7-e034-4574-bbcd-10872828ecd8) **Step.2** * New -> Import **Step.3** * Upload dashboard json -> Load ![스크린샷 2024-12-14 오후 10 51 32](https://github.com/user-attachments/assets/32f4a861-542e-4e5a-914c-2553ee64af69) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://traffic-hunter.gitbook.io/traffic-hunter/getting-started/quickstart.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.