By the end of the logging tutorial you should feel comfortable logging messages and understand logging level using the IIoT Edge App SDK. There is nothing extremely special about the logging capability of the SDK compared to open source loggers, but it (like all others) has its own configuration settings which is integrally tied to the SDK's configuration capabilities.

Logging is required by the SDK to allow the SDK the ability to log information about itself.

Before you begin

You should have completed the Getting Started section to integrate the AgoraIoT.Edge.App.SDK into your project before starting and have a project ready to use with the tutorial.

In general, most logging can be accomplished just using String Extensions for Logging, which is what this tutorial focuses on.

From the IDE, open Program.cs within the Console application created in the Getting Started tutorial and copy the code below into it:

public class Program
{
    public static void Main(string[] args)
    {
        "Starting".LogHeading();
        "Hello from Module!".LogWarn();
        $"The current local time is {DateTime.Now}.".LogInfo();
        "A debug message".LogDebug();
        "A trace message".LogTrace();
        "Stopping".LogHeading();
    }
}

from agoraiot import logger
import time
logger.heading("Starting")
logger.warn("Hello from Module!")
logger.info(f"The current local time is {time.now()}.")
logger.debug("A debug message")
logger.trace("A trace message")
logger.heading("Stopping")

Run the application. You should see the output similar to what is below in the application's Console window.

-------------------------------------------------------------------------------
(33)                                                                   Starting
-------------------------------------------------------------------------------
W(36) - Hello from Module!
I(36) - The current local time is 5/3/2022 5:17:13 PM.
-------------------------------------------------------------------------------
(37)                                                                   Stopping
-------------------------------------------------------------------------------

Within the log, each message begins with the first letter of the LogLevel followed by the number of milliseconds since the application started in parentheses. If the LogLevel of the message being written is LogLevel.Info, the message will not contain the file, line number, and member name.

Notice that the Debug and Trace messages did not appear. This is because the Logging Level defaults to LogLevel.Info and above. To adjust the level of logging messages output by the Logger for troubleshooting and development use the AEA2:LogLevel configuration setting. Assigning LogLevel sets the minimum level to be output, which corresponds to the LogLevel enumeration.

• Trace (0): Finest level of logging
• Debug (1): Used for debugging - specifically log values that should not go to Release
• Info (2): General logging information - filename, line number, and method are not included
• Warn (3): Used to indicate something is not happening as expected
• Error (4): Indicates an error occurred, but not fatally. Errors are used to indicate that the configuration error or unexpected software problem. It should not be used to log problems with the workflow or process that the application is performing.
• Fatal (5): Generally used just before the application is giving up, just before it stops.
• Off (6): Turns off all logging.

Additionally, the level of logging can be adjusted using configuration and by setting the level directly on the logger.

{
    ...
    "AEA2": {
        "LogLevel": "Debug"
    }
    ...
}

Programmatically, the default logging level can be overridden calling the appropriate method on the logger.

[!IMPORTANT] Setting LogLevel programmatically via the logger API can have unexpected results because Configuration changes will cause the LogLevel to be reset. To override any configuration setting, use configuration overrides.

using static Agora.SDK;

Log.SetLevel(Agora.Logging.LogLevel.Debug);

from agoraiot import logger, LogLevel

logger.set_level(LogLevel.DEBUG)

using static Agora.SDK;

Config.Overrides["AEA2:LogLevel"] = "Debug";
Config.Build();

from agoraiot import config

config.overrides["AEA2:LogLevel"] = "Debug"
config.build();