What logs to collect

There are several logs that can be enabled for diagnosing problems with the CloudConnector and NCHSD. The logs are listed in the following tables.

NOTE: If enabling moderately or highly verbose logs, stream the station output to a file to lessen the impact on performance. Also, saving the file gives you something to refer to later and share with Technical Support, if needed.

CloudConnector logs

Log Name	Description	Verbosity	Notes
cloud.connector	CloudConnector lifecyle events (connect ok/fail, disconnect, ping)	Low	set to FINE for debug
cloud.connector.http	CloudConnector HTTP information	Low	set to FINE for HTTP response codes
cloud.connector.sentience	Sentience-related connector information - authentication, heartbeat, token refresh	Moderate	set to FINE for all debug; set to CONFIG for some basic diagnostics
cloud.iotmsg	IoTHub Message Client information about message data and processing	Moderate to Very High*	set to FINE for basic diagnostics; FINEST for message payload (VERY verbose) ** In most cases where you are only interested in the message contents and not queuing issues, when setting cloud.iotmsg to FINEST, you will also want to set cloud.iotmsg.queue to INFO, as the logger levels inherit from their parent.
cloud.iotmsg.queue			set to FINER for most queue information *At the FINER/FINEST level, the large messages can fill the log very quickly

NCHSD logs

Log Name	Description	Verbosity	Notes
ncloud	General NCHSD (device lifecycle and initial message processing, pointId lookup)	Moderate	This is sort of a catch-all, it includes some alarm and command and security related messages
ncloud.alarm	Alarming information	Low	alarm message delivery
ncloud.command	Command processing	Moderate	Processing for System Commands (except point & cov)
ncloud.history	History export information, discovery/learn	Moderate	set to FINE for updates on history export execution
ncloud.point	Point information	High	Point update, read/write command processing, cov handling
ncloud.point.background	Background update group processing	Low	General execution of point batching (individual update info is in "ncloud.point")
ncloud.point.standard	Standard update group processing	Low	General execution of point batching (individual update info is in "ncloud.point")
ncloud.point.priority	Priority update group processing	Low	General execution of point batching (individual update info is in "ncloud.point")
ncloud.security	Information about command authorization and security	Moderate	Set to CONFIG to see role mapping NOTE: Information about Trust Store mapping is controled by “ncloud” log.
authentication	Information about user authentication in cloud commands	Low	User authentication; non-cloud, but may be useful in identifying failed command reason. See note following this table.

NOTE: The authentication log is protected by a property flag check. This is a hidden property in the AuthenticationService; you must unhide the property (in the AX SlotSheet view of the AuthenticationService, right-click debug > Config Flags and click to uncheck the Hidden flag).

IoTHub device client logs

There are a number of loggers within the Microsoft IoTHub Device Client that can be enabled to diagnose the IoTHub connection behavior in detail. If needed, you may be directed to enable them by Technical Support. It is not recommended to enable these loggers for ordinary users, so they are not listed here. Most of them begin with com.microsoft.azure.sdk.iot.device.

NOTE: If you are asked to enable these logs, remember to disable them by setting to INFO or higher levels as soon as the diagnostics session is completed. Otherwise they can produce large amounts of output that will significantly impact station performance.

Deciding which logs to enable

Choosing which logs to enable requires certain judgment on the part of the user. If you set every log to ALL, they will generate a huge amount of data which makes it harder to debug the problem. Each of the basic NCHSD functions (points, histories, alarms, commands) has a log level beginning with "ncloud". These do not generate a huge amount of data so, they can usually be set to ALL without negatively affecting performance.

For issues with message security and authentication, set ncloud.security and authentication to ALL. The output level is usually low enough to be manageable.
For issues with connection, registration, and connector behavior, set cloud.connector, cloud.connector.http, and cloud.connector.sentience to ALL, as they also generate relatively low output.
For IoTHub concerns, we have a separate log, cloud.iotmsg. This is useful for examining specific message contents but can be extremely verbose, especially for a large system with many points and histories. This can be set to CONFIG or FINE, but use FINER or FINEST with care, and only for brief periods, as the output level is high. At the FINEST/ALL level, this provides the full contents of every message, such as histories. Only use this if the message contents are in question. At the FINE and FINER levels, it generates detailed information. At the CONFIG and INFO levels, it shows general information that can be helpful in tracing the message flow for other issues.

CAUTION: Do not forget to return logger settings to their default INFO levels once your problem is corrected. Leaving the loggers at higher levels of debug can impact system performance, and hide any new problems under a wave of noisy station output. This is especially true for the cloud.iotmsg logger.