Skip to content

Commit 9add8ba

Browse files
zechengzzechengz
authored
Merge pull request #44 from traceroot-ai/feat/support_customized_log_config
feat: support customized log config
2 parents aedd010 + f6e9ed1 commit 9add8ba

File tree

10 files changed

+1018
-21
lines changed

10 files changed

+1018
-21
lines changed

‎.github/workflows/test.yml‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -55,3 +55,118 @@ jobs:
5555
echo "Main JAR file:"
5656
ls -la target/*.jar | grep -v javadoc | grep -v sources || echo "No main JAR found"
5757
echo "Build verification completed"
58+
59+
- name: Test Log4j2 Local Example
60+
env:
61+
TRACEROOT_OTLP_ENDPOINT: http://127.0.0.1:4318/v1/traces
62+
run: |
63+
cd examples/log4j2-local-example
64+
echo "Running Log4j2 local example..."
65+
timeout 30s mvn clean compile exec:java -Dexec.mainClass="com.example.StandaloneExample" || exit_code=$?
66+
if [ $exit_code -eq 124 ] || [ $exit_code -eq 0 ]; then
67+
echo "Log4j2 local example ran successfully"
68+
else
69+
echo "Log4j2 local example failed with exit code: $exit_code"
70+
exit $exit_code
71+
fi
72+
73+
echo "Validating log file exists..."
74+
if [ ! -f logs/traceroot-sdk.log ]; then
75+
echo "Error: Log file not found at logs/traceroot-sdk.log"
76+
exit 1
77+
fi
78+
79+
echo "Validating JSON format..."
80+
# Check that log file contains valid JSON
81+
if ! head -1 logs/traceroot-sdk.log | python3 -m json.tool > /dev/null 2>&1; then
82+
echo "Error: Log file does not contain valid JSON"
83+
cat logs/traceroot-sdk.log | head -5
84+
exit 1
85+
fi
86+
87+
echo "Validating required TraceRoot fields..."
88+
# Extract first log entry and validate required fields
89+
first_log=$(head -1 logs/traceroot-sdk.log)
90+
91+
required_fields=("github_owner" "trace_id" "environment" "level" "span_id" "github_repo_name" "service_name" "stack_trace" "message" "github_commit_hash" "timestamp")
92+
93+
for field in "${required_fields[@]}"; do
94+
if ! echo "$first_log" | grep -q "\"$field\""; then
95+
echo "Error: Required field '$field' not found in log entry"
96+
echo "Log entry: $first_log"
97+
exit 1
98+
fi
99+
done
100+
101+
# Validate that custom fields from user pattern are NOT present (this is local example without custom pattern)
102+
if echo "$first_log" | grep -q "\"dateTime\"" || echo "$first_log" | grep -q "\"thread\""; then
103+
echo "Error: Custom user fields should not be present in local example"
104+
echo "Log entry: $first_log"
105+
exit 1
106+
fi
107+
108+
echo "✓ Log4j2 local example validation passed"
109+
110+
- name: Test Log4j2 Custom Format Example
111+
env:
112+
TRACEROOT_OTLP_ENDPOINT: http://127.0.0.1:4318/v1/traces
113+
run: |
114+
cd examples/log4j2-custom-format-example
115+
echo "Running Log4j2 custom format example..."
116+
timeout 30s mvn clean compile exec:java -Dexec.mainClass="com.example.StandaloneExample" || exit_code=$?
117+
if [ $exit_code -eq 124 ] || [ $exit_code -eq 0 ]; then
118+
echo "Log4j2 custom format example ran successfully"
119+
else
120+
echo "Log4j2 custom format example failed with exit code: $exit_code"
121+
exit $exit_code
122+
fi
123+
124+
echo "Validating log file exists..."
125+
if [ ! -f logs/traceroot-sdk.log ]; then
126+
echo "Error: Log file not found at logs/traceroot-sdk.log"
127+
exit 1
128+
fi
129+
130+
echo "Validating JSON format..."
131+
# Check that log file contains valid JSON
132+
if ! head -1 logs/traceroot-sdk.log | python3 -m json.tool > /dev/null 2>&1; then
133+
echo "Error: Log file does not contain valid JSON"
134+
cat logs/traceroot-sdk.log | head -5
135+
exit 1
136+
fi
137+
138+
echo "Validating required TraceRoot fields..."
139+
# Extract first log entry and validate required fields
140+
first_log=$(head -1 logs/traceroot-sdk.log)
141+
142+
required_fields=("github_owner" "trace_id" "environment" "level" "span_id" "github_repo_name" "service_name" "stack_trace" "message" "github_commit_hash" "timestamp")
143+
144+
for field in "${required_fields[@]}"; do
145+
if ! echo "$first_log" | grep -q "\"$field\""; then
146+
echo "Error: Required field '$field' not found in log entry"
147+
echo "Log entry: $first_log"
148+
exit 1
149+
fi
150+
done
151+
152+
echo "Validating custom user fields..."
153+
# Validate that custom fields ARE present (this example has custom pattern)
154+
custom_fields=("dateTime" "thread" "class" "method")
155+
156+
for field in "${custom_fields[@]}"; do
157+
if ! echo "$first_log" | grep -q "\"$field\""; then
158+
echo "Error: Custom field '$field' not found in log entry"
159+
echo "Log entry: $first_log"
160+
exit 1
161+
fi
162+
done
163+
164+
echo "Validating field ordering..."
165+
# TraceRoot fields should come before custom fields
166+
# Check that github_owner appears before custom fields like dateTime
167+
if ! echo "$first_log" | python3 -c 'import json,sys;d=json.load(sys.stdin);keys=list(d.keys());print("PASS" if keys.index("github_owner")<keys.index("dateTime") else "FAIL")' | grep -q "PASS"; then
168+
echo "Error: TraceRoot fields should appear before custom user fields"
169+
exit 1
170+
fi
171+
172+
echo "✓ Log4j2 custom format example validation passed"

‎examples/log4j2-custom-format-example/.env.example‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
# Required: OTLP endpoint for trace export
2+
# typically in the format of http://cvm_primary_public_ipv4_address:4318/v1/traces
3+
TRACEROOT_OTLP_ENDPOINT=your_traceroot_otlp_endpoint
4+
5+
# Required: Absolute path to your project root directory
6+
TRACEROOT_ROOT_PATH=your_project_path_here

‎examples/log4j2-custom-format-example/README.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# TraceRoot Log4j2 Local Example
2+
3+
This example demonstrates how to use the TraceRoot SDK with Log4j2 as the logging framework in a standalone Java application with local file logging.
4+
5+
## Prerequisites
6+
7+
- Java 11 or higher
8+
- Maven 3.6+
9+
- TraceRoot OTLP endpoint (for trace export)
10+
11+
## Quick Start
12+
13+
### 1. Build and Install the Java Environment
14+
15+
From the repository root:
16+
17+
```bash
18+
mvn clean install -Dgpg.skip=true
19+
```
20+
21+
### 2. Configure Environment Variables
22+
23+
Copy the example environment file and populate it with your values:
24+
25+
```bash
26+
cp .env.example .env
27+
```
28+
29+
Edit `.env` and set:
30+
31+
- `TRACEROOT_OTLP_ENDPOINT` - Your OTLP endpoint
32+
- `TRACEROOT_ROOT_PATH` - Absolute path to this project directory
33+
34+
### 3. Run the Application
35+
36+
```bash
37+
mvn clean compile exec:java
38+
```
39+
40+
## Setting Up Jaeger on Tencent CVM
41+
42+
This section guides you through setting up a Jaeger instance on Tencent CVM to collect and visualize traces from your application.
43+
44+
### Step 1: Install Docker
45+
46+
SSH into your Tencent CVM and install Docker:
47+
48+
```bash
49+
# Install Docker
50+
sudo apt-get update
51+
sudo apt-get install -y docker.io
52+
53+
# Start Docker and enable on boot
54+
sudo systemctl start docker
55+
sudo systemctl enable docker
56+
57+
# Add current user to docker group (optional, avoids needing sudo)
58+
sudo usermod -aG docker $USER
59+
# Note: Log out and log back in for group changes to take effect
60+
```
61+
62+
### Step 2: Start Jaeger Container
63+
64+
Run Jaeger All-in-One with OTLP support enabled:
65+
66+
```bash
67+
docker run -d --name jaeger \
68+
--restart unless-stopped \
69+
-e COLLECTOR_OTLP_ENABLED=true \
70+
-p 16686:16686 \
71+
-p 14268:14268 \
72+
-p 14250:14250 \
73+
-p 4317:4317 \
74+
-p 4318:4318 \
75+
cr.jaegertracing.io/jaegertracing/jaeger:2.8.0
76+
```
77+
78+
**Port Mappings:**
79+
80+
- `16686` - Jaeger UI
81+
- `4318` - OTLP HTTP endpoint (used by TraceRoot SDK)
82+
- `4317` - OTLP gRPC endpoint
83+
- `14268` - Jaeger Collector HTTP
84+
- `14250` - Jaeger Collector gRPC
85+
86+
### Step 3: Verify Jaeger is Running
87+
88+
Check that the container is running properly:
89+
90+
```bash
91+
# Check container status
92+
sudo docker ps | grep jaeger
93+
94+
# Test Jaeger API endpoint
95+
curl http://localhost:16686/api/services
96+
```
97+
98+
**Expected output:** `{"data":null}` or `{"data":[]}` (empty because no traces have been sent yet)
99+
100+
## Setting Up Tencent CLS LogListener
101+
102+
This section guides you through setting up Tencent CLS LogListener agent to automatically collect local log files and send them to CLS (Cloud Log Service).
103+
104+
### Step 1: Install LogListener Agent
105+
106+
SSH into your Tencent CVM and install the LogListener agent:
107+
108+
```bash
109+
# Download LogListener installer
110+
cd /tmp
111+
wget http://mirrors.tencent.com/install/cls/loglistener-linux-x64.tar.gz
112+
113+
# Extract to /usr/local
114+
sudo tar -zxvf loglistener-linux-x64.tar.gz -C /usr/local/
115+
116+
# Navigate to tools directory
117+
cd /usr/local/loglistener/tools
118+
119+
# Install the agent
120+
sudo ./loglistener.sh install
121+
```
122+
123+
### Step 2: Initialize LogListener with Your Credentials
124+
125+
Initialize the agent with your Tencent Cloud credentials:
126+
127+
```bash
128+
# Initialize with your credentials
129+
sudo ./loglistener.sh init \
130+
--secretid YOUR_SECRET_ID \
131+
--secretkey YOUR_SECRET_KEY \
132+
--region YOUR_LOCATION \
133+
--network internet
134+
```
135+
136+
### Step 3: Start LogListener Service
137+
138+
Start and verify the LogListener daemon:
139+
140+
```bash
141+
# Start the service
142+
sudo systemctl start loglistenerd
143+
144+
# Check service status
145+
sudo systemctl status loglistenerd
146+
147+
# Enable on boot (optional)
148+
sudo systemctl enable loglistenerd
149+
```
150+
151+
### Step 4: Configure Collection in CLS Console
152+
153+
Configure the log collection in Tencent CLS Console:
154+
155+
1. **Navigate to CLS Console** → Select your **Log Topic** → **Collection Configuration**
156+
157+
1. **Create Machine Group**:
158+
159+
- Go to **Machine Group** section
160+
- Click **Create Machine Group**
161+
- Add your CVM's **private IP address**
162+
- Save the machine group
163+
164+
1. **Create Collection Configuration**:
165+
166+
- Click **Create Collection Config**
167+
- **Collection Path**:
168+
```
169+
/path/to/traceroot-sdk-java/examples/log4j2-local-example/logs/traceroot-sdk.log
170+
```
171+
- **Key-Value Extraction Mode**: Select `JSON`
172+
- **Associate Machine Group**: Select the machine group you created
173+
- Click **Save**

0 commit comments

Comments
 (0)