Introduction

Recently a colleague of mine shared a design doc in which he mentioned

Callsite configuration for logging is strongly preferred for ……

Now this was the first time I thought about callsite vs logger configuration. So here we go.

What is Callsite Configuration?

Callsite configuration applies logging settings directly to the code location where the logging call occurs. For instance, if you have a line like:

• Python Example:

  logger.info(f"Order processed successfully: {order_id}")
  

• JVM Example:

  logger.info("Order processed successfully: {}", orderId);
  

Callsite configuration allows you to specify details such as:

• Log level (e.g., info, debug).
• Formatting of the message.
• Whether the log message should even be emitted.

This method provides fine-grained control, making it easier to:

• Adjust logging behavior for specific scenarios.
• Suppress unnecessary logs from overwhelming your system.
• Tailor logs for better debugging or performance insights.

Since callsite configuration operates at the source of the logging call, it takes precedence over broader logger settings.

What is Logger Configuration?

Logger configuration, on the other hand, applies rules to all logs emitted by a specific logger. This is typically managed through centralized configuration files, such as:

• sepia.yaml for Python applications.
• logback.xml for JVM-based applications.

Logger configuration is often used for third-party libraries like Kafka or Redis, where you can’t modify the logging calls directly. It allows you to:

• Set log levels globally for a library (e.g., suppressing verbose logs from Redis or Kafka).
• Control output destinations (e.g., log files, console).
• Apply global formatting.

While logger configuration is powerful, its broad scope can lead to excessive or insufficient logging. It’s most useful for managing logs in codebases outside your control.

Why is Callsite Configuration Preferred?

1. Precision
   Callsite configuration lets you adjust logging behavior exactly where it matters. This ensures that logs are actionable and relevant, reducing noise.

2. Debugging Efficiency
   Fine-tuning logs at the source of an issue makes debugging faster. Developers can emit detailed logs for complex operations without cluttering the rest of the system.

3. Overrides Broad Rules
   Since callsite configurations take precedence, they allow developers to bypass general logger settings when specific adjustments are needed.

4. Third-Party Exceptions
   Logger configuration is a fallback for third-party libraries where callsite control isn’t possible. However, this should be the exception, not the norm.

Example: Combining Callsite and Logger Configurations

Python Example

Imagine an application that uses Redis for caching. You might configure logs like this:

• Callsite Configuration:

  if logger.isEnabledFor(logging.DEBUG):
      logger.debug(f"Processing cache entry for key: {key}")
  

• Logger Configuration (sepia.yaml):

  loggers:
    redis:
      level: WARN
      handlers:
        - console
  

Here, callsite configuration manages log verbosity for your application code, while logger configuration ensures Redis’s internal logs don’t overwhelm the system.

JVM Example

Now imagine a Java application using Kafka for messaging. You might configure logs like this:

• Callsite Configuration:

  if (logger.isDebugEnabled()) {
      logger.debug("Processing message with key: {}", messageKey);
  }
  

• Logger Configuration (logback.xml):

  <configuration>
      <logger name="org.apache.kafka" level="WARN"/>
      <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
          <encoder>
              <pattern>%d{yyyy-MM-dd HH:mm:ss} [%thread] %-5level %logger{36} - %msg%n</pattern>
          </encoder>
      </appender>
      <root level="INFO">
          <appender-ref ref="CONSOLE"/>
      </root>
  </configuration>
  

Here, callsite configuration provides fine-grained control for your Kafka-related logs, while logger configuration keeps Kafka’s verbose logs at a manageable level.

Best Practices for Logging Configurations

1. Use Callsite Configurations for Your Code
   Apply logging settings directly in your application code to maintain control and precision.

2. Fallback to Logger Configurations for Third-Party Libraries
   Use logger configurations sparingly to manage logs from libraries or systems you can’t modify.

3. Document Logging Policies
   Maintain clear documentation on when to use callsite versus logger configurations to ensure consistency across your codebase.

4. Monitor and Adjust
   Periodically review logs to ensure they provide actionable insights without overwhelming storage or analysis tools.

Resources

• Python Logging Documentation
• Logback Documentation
• 12-Factor App: Logs
• Redis Logging Configuration Guide
• Kafka Logging Configuration Guide