feat: support customized log config

.github/workflows/test.yml

@@ -55,3 +55,118 @@ jobs:
           echo "Main JAR file:"
           ls -la target/*.jar | grep -v javadoc | grep -v sources || echo "No main JAR found"
           echo "Build verification completed"
+
+      - name: Test Log4j2 Local Example
+        env:
+          TRACEROOT_OTLP_ENDPOINT: http://127.0.0.1:4318/v1/traces
+        run: |
+          cd examples/log4j2-local-example
+          echo "Running Log4j2 local example..."
+          timeout 30s mvn clean compile exec:java -Dexec.mainClass="com.example.StandaloneExample" || exit_code=$?
+          if [ $exit_code -eq 124 ] || [ $exit_code -eq 0 ]; then
+            echo "Log4j2 local example ran successfully"
+          else
+            echo "Log4j2 local example failed with exit code: $exit_code"
+            exit $exit_code
+          fi
+
+          echo "Validating log file exists..."
+          if [ ! -f logs/traceroot-sdk.log ]; then
+            echo "Error: Log file not found at logs/traceroot-sdk.log"
+            exit 1
+          fi
+
+          echo "Validating JSON format..."
+          # Check that log file contains valid JSON
+          if ! head -1 logs/traceroot-sdk.log | python3 -m json.tool > /dev/null 2>&1; then
+            echo "Error: Log file does not contain valid JSON"
+            cat logs/traceroot-sdk.log | head -5
+            exit 1
+          fi
+
+          echo "Validating required TraceRoot fields..."
+          # Extract first log entry and validate required fields
+          first_log=$(head -1 logs/traceroot-sdk.log)
+
+          required_fields=("github_owner" "trace_id" "environment" "level" "span_id" "github_repo_name" "service_name" "stack_trace" "message" "github_commit_hash" "timestamp")
+
+          for field in "${required_fields[@]}"; do
+            if ! echo "$first_log" | grep -q "\"$field\""; then
+              echo "Error: Required field '$field' not found in log entry"
+              echo "Log entry: $first_log"
+              exit 1
+            fi
+          done
+
+          # Validate that custom fields from user pattern are NOT present (this is local example without custom pattern)
+          if echo "$first_log" | grep -q "\"dateTime\"" || echo "$first_log" | grep -q "\"thread\""; then
+            echo "Error: Custom user fields should not be present in local example"
+            echo "Log entry: $first_log"
+            exit 1
+          fi
+
+          echo "✓ Log4j2 local example validation passed"
+
+      - name: Test Log4j2 Custom Format Example
+        env:
+          TRACEROOT_OTLP_ENDPOINT: http://127.0.0.1:4318/v1/traces
+        run: |
+          cd examples/log4j2-custom-format-example
+          echo "Running Log4j2 custom format example..."
+          timeout 30s mvn clean compile exec:java -Dexec.mainClass="com.example.StandaloneExample" || exit_code=$?
+          if [ $exit_code -eq 124 ] || [ $exit_code -eq 0 ]; then
+            echo "Log4j2 custom format example ran successfully"
+          else
+            echo "Log4j2 custom format example failed with exit code: $exit_code"
+            exit $exit_code
+          fi
+
+          echo "Validating log file exists..."
+          if [ ! -f logs/traceroot-sdk.log ]; then
+            echo "Error: Log file not found at logs/traceroot-sdk.log"
+            exit 1
+          fi
+
+          echo "Validating JSON format..."
+          # Check that log file contains valid JSON
+          if ! head -1 logs/traceroot-sdk.log | python3 -m json.tool > /dev/null 2>&1; then
+            echo "Error: Log file does not contain valid JSON"
+            cat logs/traceroot-sdk.log | head -5
+            exit 1
+          fi
+
+          echo "Validating required TraceRoot fields..."
+          # Extract first log entry and validate required fields
+          first_log=$(head -1 logs/traceroot-sdk.log)
+
+          required_fields=("github_owner" "trace_id" "environment" "level" "span_id" "github_repo_name" "service_name" "stack_trace" "message" "github_commit_hash" "timestamp")
+
+          for field in "${required_fields[@]}"; do
+            if ! echo "$first_log" | grep -q "\"$field\""; then
+              echo "Error: Required field '$field' not found in log entry"
+              echo "Log entry: $first_log"
+              exit 1
+            fi
+          done
+
+          echo "Validating custom user fields..."
+          # Validate that custom fields ARE present (this example has custom pattern)
+          custom_fields=("dateTime" "thread" "class" "method")
+
+          for field in "${custom_fields[@]}"; do
+            if ! echo "$first_log" | grep -q "\"$field\""; then
+              echo "Error: Custom field '$field' not found in log entry"
+              echo "Log entry: $first_log"
+              exit 1
+            fi
+          done
+
+          echo "Validating field ordering..."
+          # TraceRoot fields should come before custom fields
+          # Check that github_owner appears before custom fields like dateTime
+          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
+            echo "Error: TraceRoot fields should appear before custom user fields"
+            exit 1
+          fi
+
+          echo "✓ Log4j2 custom format example validation passed"

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

@@ -0,0 +1,6 @@
+# Required: OTLP endpoint for trace export
+# typically in the format of http://cvm_primary_public_ipv4_address:4318/v1/traces
+TRACEROOT_OTLP_ENDPOINT=your_traceroot_otlp_endpoint
+
+# Required: Absolute path to your project root directory
+TRACEROOT_ROOT_PATH=your_project_path_here

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

@@ -0,0 +1,173 @@
+# TraceRoot Log4j2 Local Example
+
+This example demonstrates how to use the TraceRoot SDK with Log4j2 as the logging framework in a standalone Java application with local file logging.
+
+## Prerequisites
+
+- Java 11 or higher
+- Maven 3.6+
+- TraceRoot OTLP endpoint (for trace export)
+
+## Quick Start
+
+### 1. Build and Install the Java Environment
+
+From the repository root:
+
+```bash
+mvn clean install -Dgpg.skip=true
+```
+
+### 2. Configure Environment Variables
+
+Copy the example environment file and populate it with your values:
+
+```bash
+cp .env.example .env
+```
+
+Edit `.env` and set:
+
+- `TRACEROOT_OTLP_ENDPOINT` - Your OTLP endpoint
+- `TRACEROOT_ROOT_PATH` - Absolute path to this project directory
+
+### 3. Run the Application
+
+```bash
+mvn clean compile exec:java
+```
+
+## Setting Up Jaeger on Tencent CVM
+
+This section guides you through setting up a Jaeger instance on Tencent CVM to collect and visualize traces from your application.
+
+### Step 1: Install Docker
+
+SSH into your Tencent CVM and install Docker:
+
+```bash
+# Install Docker
+sudo apt-get update
+sudo apt-get install -y docker.io
+
+# Start Docker and enable on boot
+sudo systemctl start docker
+sudo systemctl enable docker
+
+# Add current user to docker group (optional, avoids needing sudo)
+sudo usermod -aG docker $USER
+# Note: Log out and log back in for group changes to take effect
+```
+
+### Step 2: Start Jaeger Container
+
+Run Jaeger All-in-One with OTLP support enabled:
+
+```bash
+docker run -d --name jaeger \
+  --restart unless-stopped \
+  -e COLLECTOR_OTLP_ENABLED=true \
+  -p 16686:16686 \
+  -p 14268:14268 \
+  -p 14250:14250 \
+  -p 4317:4317 \
+  -p 4318:4318 \
+  cr.jaegertracing.io/jaegertracing/jaeger:2.8.0
+```
+
+**Port Mappings:**
+
+- `16686` - Jaeger UI
+- `4318` - OTLP HTTP endpoint (used by TraceRoot SDK)
+- `4317` - OTLP gRPC endpoint
+- `14268` - Jaeger Collector HTTP
+- `14250` - Jaeger Collector gRPC
+
+### Step 3: Verify Jaeger is Running
+
+Check that the container is running properly:
+
+```bash
+# Check container status
+sudo docker ps | grep jaeger
+
+# Test Jaeger API endpoint
+curl http://localhost:16686/api/services
+```
+
+**Expected output:** `{"data":null}` or `{"data":[]}` (empty because no traces have been sent yet)
+
+## Setting Up Tencent CLS LogListener
+
+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).
+
+### Step 1: Install LogListener Agent
+
+SSH into your Tencent CVM and install the LogListener agent:
+
+```bash
+# Download LogListener installer
+cd /tmp
+wget http://mirrors.tencent.com/install/cls/loglistener-linux-x64.tar.gz
+
+# Extract to /usr/local
+sudo tar -zxvf loglistener-linux-x64.tar.gz -C /usr/local/
+
+# Navigate to tools directory
+cd /usr/local/loglistener/tools
+
+# Install the agent
+sudo ./loglistener.sh install
+```
+
+### Step 2: Initialize LogListener with Your Credentials
+
+Initialize the agent with your Tencent Cloud credentials:
+
+```bash
+# Initialize with your credentials
+sudo ./loglistener.sh init \
+  --secretid YOUR_SECRET_ID \
+  --secretkey YOUR_SECRET_KEY \
+  --region YOUR_LOCATION \
+  --network internet
+```
+
+### Step 3: Start LogListener Service
+
+Start and verify the LogListener daemon:
+
+```bash
+# Start the service
+sudo systemctl start loglistenerd
+
+# Check service status
+sudo systemctl status loglistenerd
+
+# Enable on boot (optional)
+sudo systemctl enable loglistenerd
+```
+
+### Step 4: Configure Collection in CLS Console
+
+Configure the log collection in Tencent CLS Console:
+
+1. **Navigate to CLS Console** → Select your **Log Topic** → **Collection Configuration**
+
+1. **Create Machine Group**:
+
+   - Go to **Machine Group** section
+   - Click **Create Machine Group**
+   - Add your CVM's **private IP address**
+   - Save the machine group
+
+1. **Create Collection Configuration**:
+
+   - Click **Create Collection Config**
+   - **Collection Path**:
+     ```
+     /path/to/traceroot-sdk-java/examples/log4j2-local-example/logs/traceroot-sdk.log
+     ```
+   - **Key-Value Extraction Mode**: Select `JSON`
+   - **Associate Machine Group**: Select the machine group you created
+   - Click **Save**