How Hera Transforms SpringBoot Logging: A Step‑by‑Step Integration Guide

Why Traditional Logging Fails in Distributed Systems

Engineers often waste hours searching across dozens of servers for null‑pointer exceptions, tracing failed payments, or reproducing intermittent timeouts because logs are scattered, lack business‑level aggregation, and miss crucial trace IDs.

Hera’s Core Value: Solving Three Fundamental Problems

Log Fragmentation – Traditional SpringBoot logs reside locally or in simple ELK stacks, requiring manual server access or complex multi‑field queries. Hera introduces business‑level tags that let you filter logs by user, order ID, or environment instantly.

Broken End‑to‑End Traceability – Without a unified trace ID, linking gateway, service, and database logs can take hours. Hera injects a trace ID into every request, enabling cross‑service log stitching.

High Storage Cost – Full‑volume log retention is expensive, while sampled logs lose important data. Hera supports tiered storage: critical logs kept 30 days in Elasticsearch, non‑critical logs archived to HDFS for 7 days, cutting storage costs by up to 60 %.

Architecture: Hera’s Layered Model for SpringBoot

Log Collection Layer – Hera Agent is embedded in the SpringBoot process, capturing logs without code changes and allowing custom fields such as businessType, env, and userId.

Platform Layer – Core service that parses fields, routes logs based on business rules, and stores them.

Storage Layer – Primary logs go to Elasticsearch for fast queries; archival logs go to HDFS to reduce cost.

Analysis Layer – Provides full‑text search, trace visualization, and aggregation statistics.

Interaction Layer – Web console and OpenAPI let developers query logs quickly.

Step‑by‑Step Integration

1. Environment Preparation

Deploy the Hera platform (recommended version 2.5+). Add the starter dependency to your 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 starter -->
<dependency>
  <groupId>com.hera</groupId>
  <artifactId>hera-trace-spring-boot-starter</artifactId>
  <version>2.5.3</version>
</dependency>

2. Core Configuration (application.yml)

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

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

3. Implement Custom Field Provider (optional)

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

4. Logging Without Code Changes

Existing SLF4J/Logback statements work unchanged. Hera automatically enriches each log entry with the configured custom fields and trace ID.

@Service
public class OrderService {
    private static final Logger log = LoggerFactory.getLogger(OrderService.class);

    public Order createOrder(OrderCreateDTO dto) {
        Order order = new Order();
        order.setOrderNo(generateOrderNo());
        order.setUserId(dto.getUserId());
        order.setAmount(dto.getAmount());

        log.info("Order created successfully, orderNo: {}, userId: {}", order.getOrderNo(), order.getUserId());
        try {
            orderMapper.insert(order);
        } catch (Exception e) {
            log.error("Order creation failed, orderNo: {}, reason: {}", order.getOrderNo(), e.getMessage(), e);
            throw new BusinessException("Order creation failed");
        }
        return order;
    }
}

5. Cross‑Service Traceability

When trace is enabled, Hera injects X-Hera-Trace-Id into HTTP headers. In the console, entering a trace ID shows the complete log chain across services.

# Order service log (traceId: 8f9d7e6c5b4a39281706)
2024-05-20 14:30:00 [INFO] com.example.order.service.OrderService - Order created, orderNo: 2024052014300001, userId: 1001

# Payment service log (same traceId)
2024-05-20 14:30:02 [INFO] com.example.pay.service.PayService - Payment succeeded, orderNo: 2024052014300001, amount: 99.00

6. Using the Hera Console

Select service name and environment to narrow the log set.

Filter by business fields, e.g., userId=1001 or orderNo=2024052014300001.

Click a trace ID to view the full end‑to‑end flow; click the stack button on error logs to see the complete exception stack.

Performance & High‑Availability Tips

Asynchronous Collection – Hera Agent buffers logs (default queue 512). Increase with hera.log.async-queue-size=2048 for high‑throughput workloads.

Log Level Control – Set hera.log.level=WARN in production to suppress noisy DEBUG logs.

Batch Transmission – Adjust hera.log.batch-size=100 to reduce network calls.

Agent Cluster – Deploy multiple agents and list all addresses to avoid a single point of failure.

Local Cache – When agents are unreachable, logs are cached under /tmp/hera/log/cache and replayed after recovery.

Security & Auditing

Mask sensitive fields via hera.log.mask-fields=phone:138****,idCard:310*1234.

Configure role‑based access so developers see only test‑environment logs, while production logs are restricted to ops and architects.

All console actions (view, export) are recorded for audit.

Common Pitfalls & Solutions

Missing Custom Fields – Ensure the HeraCustomFieldProvider implementation is a Spring bean and returns a non‑null value.

Trace Loss Across Services – Verify that every service uses the same trace-id-header and that the gateway forwards it.

High Collection Overhead – Reduce log verbosity, enlarge the async queue, and monitor the agent thread CPU with tools like Arthas.

Conclusion

Integrating Hera with SpringBoot is not merely a UI upgrade; it establishes the observability foundation for distributed systems. By centralizing logs, providing business‑level filtering, enabling one‑click traceability, and offering cost‑effective tiered storage, Hera cuts incident‑resolution time from hours to minutes and reduces storage expenses by up to 60 %.