> For the complete documentation index, see [llms.txt](https://traffic-hunter.gitbook.io/traffic-hunter/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://traffic-hunter.gitbook.io/traffic-hunter/getting-started/quickstart.md).

# 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 <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.

<figure><img src="https://github.com/user-attachments/assets/1462242c-eb9c-433e-9fda-ba22d541dd4c" alt=""><figcaption></figcaption></figure>

### 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)