Logs and IP Capturing ‐ How To Provide The Right Information

Logs and IP Capturing

For many many, issues, logs and IP captures are the main source to see, what causes trouble.

Therefore you read

• If you have logs, please provide them
• If you have tcpdump captures (wireshark), please provide them.

when you create a new issue. This guide shows, how to do so.

Logs

Californium uses slf4j as logging API. If logs are wanted, a implementation of that API is required. The Californium's demo-apps are using logback for that.

Logs for Californium's demo-apps

If you use one of the demo-apps, enabling logs is done by configuring logback with a "logback.xml" file.

<configuration>

	<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
		<!-- encoders are assigned the type ch.qos.logback.classic.encoder.PatternLayoutEncoder 
			by default -->
		<encoder>
			<pattern>%d{HH:mm:ss.SSS} %level [%logger{0}]: %msg%n</pattern>
		</encoder>
	</appender>

	<root level="DEBUG" >
		<appender-ref ref="STDOUT" />
	</root>

</configuration>

This file is usually store in "src/main/resources" in the supporting demo-apps.

(Note: not all demo-apps may support it, but adding the "logback.xml" enables it.)

Logs for custom apps

If you want to create logs for your own application, you may use also logback. To do so, logback must be added to the maven dependencies of your project:

<dependencies>
        ...
	<!-- runtime dependencies -->
	<dependency>
		<groupId>ch.qos.logback</groupId>
		<artifactId>logback-classic</artifactId>
		<scope>runtime</scope>
	</dependency>
</dependencies>

Also add the configuration file "logback.xml" as describe above.

IP Capturing

Many issues requires details of the communcation to be answered. This should give some hint to collect them.

IP Capturing Tools - Unix (Ubuntu 18.04)

Belong many tools, two are in my opinion specially useful:

• tcpdump
• wireshark

The first tcpdump is a simple command line tool, which allows to collect data on "headless" units. The second wireshark is a pwoerful UI Tool, which allows to collect and/or analyze that collected data.

Tcpdump

Tcpdump comes with rich feature set. In order to analyze the capture later with wireshark, it must be started with

sudo tcpdump -s 0 -w <filename>.pcap -i any '(udp port 5683) or (udp port 5684) or (udp port 53)'

That starts to capture all coap (udp port 5683), dtls (udp port 5684), and dns (udp port 53) and stores the captured traffic in the provided file. If you want to stop the capture, press Ctrl-C, or use the "-c numberORecords" option of tcpdump. That results in a .pcap file, which then may be further analyzed using wireshark.

Wireshark

Wireshark

Wireshark - Ubuntu

Wireshark is very powerful tool. It offers a UI to analyze the data and see the details. It maybe used to collect the data itself or to load a capture from tcpdump. For append capture data to Californium issues, it's frequently required to select a subset and save only the intended packets. To do so, either fist stop the current capture, if wireshark is used for capturing, or load the capture file from tcpdump.

Here WireShark is used to capture the traffic. "dns or dtls" filter are applied to only see the related packets (if the issues is for dtls). That current capture need to be stopped before being able to export packages. Therefore press the red button at the left top. If the current capture is stopped or a tcpdump capture is loaded, then the menu "File -> Export Specified Packets ..." is active and could be selected.

When "Export Specified Packets ..." is selected, this dialog appears. Usually it pays off, to limit the range to the intended subset by using the number range. Please do a final check, if the exported capture contains only the packages intended for the issue. Please zip that capture and then append it by "drag&drop" to the issue.