Logging

There are two ways to send logs to Auralog from Java, and you can freely mix them.

1. Direct API

Call the Auralog static facade directly:

import ai.auralog.Auralog;
import java.util.Map;

Auralog.debug("cache hit", Map.of("key", "user:42"));
Auralog.info("user signed in", Map.of("userId", "123"));
Auralog.warn("slow query", Map.of("durationMs", 1240));
Auralog.error("payment failed", Map.of("orderId", "abc"));
Auralog.fatal("db connection lost");

// Attach an exception to any error/fatal:
try {
    risky();
} catch (Exception e) {
    Auralog.error("task crashed", Map.of("task", "ingest"), e);
}

All methods are overloaded for (message), (message, metadata), (message, Throwable), and (message, metadata, Throwable).

2. SLF4J bridge (recommended for existing codebases)

If your project already uses SLF4J (via Logback, Log4j2, or the facade directly), adding ai.auralog:auralog-slf4j to the classpath routes every SLF4J call — including from third-party libraries like Spring, Hibernate, Jackson, Kafka clients — to Auralog.

import ai.auralog.Auralog;
import ai.auralog.AuralogConfig;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

Auralog.init(AuralogConfig.builder().apiKey("...").environment("production").build());

Logger log = LoggerFactory.getLogger(MyClass.class);
log.info("user signed in {}", userId);
log.error("payment failed", exception);

Level mapping

SLF4J level	Auralog level
TRACE	debug
DEBUG	debug
INFO	info
WARN	warn
ERROR	error

Logger name as metadata

Every log emitted via the SLF4J bridge includes the logger name (LoggerFactory.getLogger(MyClass.class) gives you com.example.MyClass) as metadata.logger so you can filter by origin class in the dashboard.

Exceptions

logger.error("crashed", throwable) attaches the full stack trace automatically.

Combining with global metadata

If you’ve configured globalMetadata, it is shallow-merged with the per-call metadata before the entry is sent. Per-call keys win on collision:

Auralog.init(AuralogConfig.builder()
    .apiKey("aura_...")
    .globalMetadata(() -> Map.of("userId", CurrentUser.get()))
    .build());

log.warn("rate limited route={}", "/api/checkout");
// wire metadata: {userId=u_42, logger=com.example.MyClass}

This is also how SLF4J-routed library logs (Spring, Hibernate, Kafka clients, etc.) and uncaught exceptions get attribution — they pick up globalMetadata automatically since they have no per-call object of their own.

When to use which

• Greenfield project: direct API. Clean call sites, no SLF4J config to learn.
• Existing codebase using logging.Logger or SLF4J: bridge. Zero rewrites, catches library logs too.
• Both: fine. Use Auralog.info(...) at critical paths, let the bridge catch the long tail.