Logging Configuration

Owned by Vinaya Mayya
Last updated: Jul 30, 2023
4 min read

The as-shipped Ed-Fi ODS / API uses the Apache log4net framework to assist developers and operations staff log system output at a variety of output levels and to a variety of output targets. The log4net documentation provides an overview of the framework capabilities and options. The documentation is excellent, so we won't repeat the basics here.

Logging settings for the ODS / API itself and the ODS / API Administration portal can be configured separately. This page provides example logging configurations for specific scenarios.

Default Release Configuration

This configuration is found in the as-shipped ODS / API source. This configuration routes all log messages at the WARN level or above to a rolling file log. This will log to a single file with up to two backup files, and the space taken by each file will not exceed 20MB. This represents the default configuration for a release build.

<log4net>
  <appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
    <threshold value="WARN" />
    <file value="WebApiLog.log" />
    <appendToFile value="true" />
    <maximumFileSize value="20MB" />
    <maxSizeRollBackups value="7" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread,%property{ApiClientId}] %-5level %logger - MESSAGE: %message%newline %exception" />
    </layout>
  </appender>
  <logger name="NHibernate">
    <level value="WARN"/>
  </logger>
  <root>
    <appender-ref ref="RollingFileAppender" />
  </root>
</log4net>

Default Local Developer Configuration

This configuration routes all logging messages at the INFO level or above to the Trace output (i.e., Console), and also provides a file appender for a stable log file to review. In addition, this configuration provides a separate Request-Response log file, which logs ERROR level request-response details containing ApiClientId, Request Url, Request Method, Response Code, and Response Message for all Resource endpoints. This represents the default configuration for a debug build.

<?xml version="1.0" encoding="utf-8" ?>
<log4net>
  <appender name="TraceAppender" type="log4net.Appender.TraceAppender">
    <threshold value="INFO" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread,%property{ApiClientId}] %-5level %logger{1}.%method [%line] - MESSAGE: %message%newline %exception" />
    </layout>
  </appender>
  <appender name="RollingFile" type="log4net.Appender.RollingFileAppender">
    <threshold value="WARN" />
    <file value="WebApiLog.log" />
    <appendToFile value="true" />
    <maximumFileSize value="100KB" />
    <maxSizeRollBackups value="7" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread,%property{ApiClientId}] %-5level %logger - MESSAGE: %message%newline %exception" />
    </layout>
  </appender>
  <appender name="ConsoleAppender" type="log4net.Appender.ConsoleAppender">
    <threshold value="INFO" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread,%property{ApiClientId}] %-5level %logger{1} - %message%newline" />
    </layout>
  </appender>
  <appender name="AppInsightsAppender" type="Microsoft.ApplicationInsights.Log4NetAppender.ApplicationInsightsAppender, Microsoft.ApplicationInsights.Log4NetAppender">
    <threshold value="WARN" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%message%newline" />
    </layout>
  </appender>
  <logger name="NHibernate">
    <level value="WARN"/>
  </logger>
  <root>
    <appender-ref ref="ConsoleAppender" />
    <appender-ref ref="RollingFile" />
    <appender-ref ref="TraceAppender" />
    <appender-ref ref="AppInsightsAppender" />
  </root>
  <logger name="RequestResponseDetailsLogger" additivity="false">
    <level value="ERROR" />
    <appender-ref ref="RequestResponseDetailsFileAppender" />
  </logger>
  <appender name="RequestResponseDetailsFileAppender" type="log4net.Appender.RollingFileAppender">
    <threshold value="ERROR" />
    <file value="WebApiRequestResponseDetailsLog.log"/>
    <appendToFile value="true"/>
    <maximumFileSize value="100KB" />
    <maxSizeRollBackups value="7" />
    <layout type="log4net.Layout.PatternLayout">
      <conversionPattern value="%date [%thread] %-5level ClientId:%property{ApiClientId} RequestUrl:%property{RequestUrl} RequestMethod:%property{RequestMethod} ResponseCode:%property{ResponseCode} ResponseMessage:%message%n" />
    </layout>
  </appender> 
</log4net>

To disable Request-Response logs, remove both logger RequestResponseDetailsLogger and appender RequestResponseDetailsFileAppender from the configuration file.

Example Support Configuration

In production, it's often useful to log more activity such as when troubleshooting a difficult-to-reproduce issue. This example configuration routes all logging messages at the DEBUG level or above (i.e., all logging messages) to a rolling file log. This will log a large amount of information and should not be left on after reproducing the issue for the support ticket. It increases the rolling size-per-file value to 100MB to ensure all the data is collected, but reduces the number of backup files to one single file. After enabling this configuration, detailed files can be inspected to aid in troubleshooting.

<log4net>
  <appender name="RollingFileAppender" type="log4net.Appender.RollingFileAppender">
    <threshold value="DEBUG" />
    <file value="WebApiLog.log" />
    <appendToFile value="true" />
    <maximumFileSize value="100MB" />
    <maxSizeRollBackups value="7" />
    <layout type="log4net.Layout.PatternLayout">       
       <conversionPattern value="%date [%thread,%property{ApiClientId}] %-5level %logger - MESSAGE: %message%newline %exception" />      
    </layout>
  </appender>
  <logger name="NHibernate">
    <level value="WARN"/>
  </logger>
  <root>
    <appender-ref ref="RollingFileAppender" />
  </root>
</log4net>

To further aid production troubleshooting, RequestResponseDetailsLogger can be configured to log request/response JSON to the ODS associated with the API request. See How To: Enable logging API request and response content for details. 

Developers' Guide Contents

Find out more about how to develop platforms based on the Ed-Fi ODS / API v7.0: