Boost SpringBoot Debugging: Seamless Integration with Hera Log Platform

Why Traditional Logging Fails

In distributed systems engineers often waste hours hunting for a single null‑pointer exception across dozens of servers, struggle to correlate order‑payment failures because logs are scattered, or cannot reproduce intermittent timeouts due to incomplete sampling.

Hera’s Core Benefits

Eliminates log fragmentation and boosts search efficiency with business‑level tags.

Provides end‑to‑end traceability by stitching together request paths across gateways, services, and databases.

Reduces storage cost through tiered retention: critical logs kept 30 days, non‑critical logs 7 days, saving up to 60 %.

Architecture Overview

Log Collection Layer : Hera Agent embedded in SpringBoot collects logs non‑intrusively and adds custom fields (e.g., traceId, userId).

Platform Layer : Hera core parses fields and routes logs based on business rules.

Storage Layer : Hot logs stored in Elasticsearch for fast search; cold logs archived to HDFS.

Analysis Layer : Full‑text search, trace view, aggregation statistics.

Interaction Layer : Web console or OpenAPI for developers to query logs.

Step‑by‑Step Integration

Add Maven dependencies to the SpringBoot project:

<!-- Hera log client dependency -->
<dependency>
  <groupId>com.hera</groupId>
  <artifactId>hera-log-spring-boot-starter</artifactId>
  <version>2.5.3</version>
</dependency>

<!-- Optional trace dependency -->
<dependency>
  <groupId>com.hera</groupId>
  <artifactId>hera-trace-spring-boot-starter</artifactId>
  <version>2.5.3</version>
</dependency>

Configure application.yml with Hera parameters (example):

spring:
  application:
    name: order-service # service tag

hera:
  log:
    agent-address: 192.168.1.101:8888,192.168.1.102:8888
    level: INFO
    custom-fields:
      - key: businessType
        value: ${spring.application.name}-order
      - key: env
        value: ${spring.profiles.active:dev}
      - key: userId
        value-provider: com.example.order.config.HeraUserIdProvider
    trace:
      enabled: true
      sampling-rate: 1.0
      trace-id-header: X-Hera-Trace-Id

Implement custom field provider for userId (must be a Spring bean):

@Component
public class HeraUserIdProvider implements HeraCustomFieldProvider {
    @Override
    public String getValue() {
        UserContext context = UserContextHolder.getCurrentContext();
        return context != null ? context.getUserId() : "unknown";
    }
}

Log output remains unchanged . Existing SLF4J/Logback calls automatically carry the configured fields and traceId:

@Service
public class OrderService {
    private static final Logger log = LoggerFactory.getLogger(OrderService.class);
    public Order createOrder(OrderCreateDTO dto) {
        // business logic …
        log.info("创建订单成功，订单号：{}，用户ID：{}", order.getOrderNo(), order.getUserId());
        try {
            orderMapper.insert(order);
        } catch (Exception e) {
            log.error("创建订单失败，订单号：{}，原因：{}", order.getOrderNo(), e.getMessage(), e);
            throw new BusinessException("订单创建失败");
        }
        return order;
    }
}

Trace across services : When trace is enabled, Hera injects X-Hera-Trace-Id into HTTP headers, allowing the console to display the full call chain with a single traceId.

Use the Hera console (three steps):

Select service name and environment to narrow the log set.

Search by business fields such as userId=1001 or orderNo=2024052014300001.

Click a traceId to view the complete cross‑service log chain and expand stack traces directly.

Performance & High‑Availability Tips

Enable asynchronous collection (default) and tune hera.log.async-queue-size (e.g., 1024) to avoid blocking the main thread.

Set log level to WARN in production and keep only essential INFO logs for core business.

Batch transmission via hera.log.batch-size (default 50, can be increased to 100) reduces network I/O.

Deploy multiple Hera Agent nodes and list all addresses to prevent single‑point loss.

Agent caches logs locally under /tmp/hera/log/cache when the server is unavailable and resends them after recovery.

Use tiered storage: hot logs in Elasticsearch (7 days) and cold logs in HDFS (30 days).

Mask sensitive fields (e.g., phone, idCard) with hera.log.mask-fields to avoid data leakage.

Configure service‑plus‑environment permissions so only authorized roles can view production logs.

Common Pitfalls & Fixes

Missing custom fields : Ensure the custom field provider is annotated with @Component and returns a non‑null value.

Trace header not propagated : Verify that all services use the same trace-id-header (recommended X-Hera-Trace-Id) and that the gateway forwards it.

High collection overhead : Reduce log verbosity, enlarge the async queue, and monitor Agent thread CPU usage with tools like Arthas.

Bottom‑Line Benefits

Debugging time drops from hours to minutes (e.g., 2 h → 15 min on a large e‑commerce platform).

Storage cost cuts by ~60 % thanks to tiered retention and selective indexing.

Observability improves dramatically: distributed tracing and aggregated statistics turn opaque “black‑box” services into transparent, diagnosable components.