Help Me Help You: A Guide to Effective Technical Support

As maintainers of commercial and open-source Java SSH APIs, our primary goal is to provide a stable, secure, and performant foundation for your applications. We love seeing the value-added solutions you build with our tools. When issues arise, we are committed to helping you resolve them as quickly as possible. When you reach out for help, you get support directly from the developers who build and maintain the APIs, ensuring you receive the highest level of expertise.

However, the support process is a partnership. To diagnose and fix complex issues effectively, we rely on clear, complete, and concise information from you. This article outlines the key artifacts and information we need to ensure a swift resolution, helping you get back to building great things.

The Golden Rule: If I Can’t Reproduce It, I Can’t Fix It

This is the most critical principle of software support. Many times, an issue is specific to a particular environment, configuration, or implementation detail. While you may be able to reproduce an issue consistently in your own lab, we cannot begin to fix a problem that we cannot observe ourselves.

If our core, reference implementations do not exhibit the issue, it strongly suggests the problem lies within the specific context of your implementation.

To help us, please make every effort to provide:

• A simple, portable, and self-contained code example that reproduces the issue.
• Clear, step-by-step instructions on how to run the example and trigger the problem.

The faster we can reproduce an issue, the faster we can resolve it. Time spent creating a reproducible test case is an investment that pays dividends in resolution speed.

The Power of Logs: Your Most Important Artifact

Logs provide a detailed narrative of what the API is doing, thinking, and seeing. Vague descriptions of a problem are no substitute for the raw data provided by a DEBUG level log. For any issue you report, we will require a complete and unfiltered DEBUG log file.

Critically, we only want to see log output from our own APIs. Customer application logs, while useful for you, create noise that slows down our analysis.

How to Provide Clean Logs

• Maverick Legacy 1.8.x & Maverick Synergy (Modern Versions): In modern versions of our products, logging is exclusively output to our own dedicated file. Please provide this file.
• Maverick Legacy (Older Versions): Earlier versions used the SLF4J facade, which could mix our API logs with your application’s logs. If you are using Log4J with SLF4J, please configure it to isolate our loggers.

Here is a sample Log4J configuration to create a separate file containing only our API’s output:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE log4j:configuration SYSTEM "log4j.dtd">
<log4j:configuration xmlns:log4j="[http://jakarta.apache.org/log4j/](http://jakarta.apache.org/log4j/)">

    <!-- Appender for Maverick-specific logs -->
    <appender name="MaverickFile" class="org.apache.log4j.RollingFileAppender">
        <param name="File" value="maverick.log"/>
        <param name="MaxFileSize" value="10MB"/>
        <param name="MaxBackupIndex" value="5"/>
        <layout class="org.apache.log4j.PatternLayout">
            <param name="ConversionPattern" value="%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n"/>
        </layout>
    </appender>

    <!-- Isolate Maverick loggers to the MaverickFile appender -->
    <logger name="com.maverick" additivity="false">
        <level value="DEBUG"/>
        <appender-ref ref="MaverickFile"/>
    </logger>

    <logger name="com.sshtools" additivity="false">
        <level value="DEBUG"/>
        <appender-ref ref="MaverickFile"/>
    </logger>

    <!-- Your existing root logger for your application logs -->
    <root>
        <priority value="INFO"></priority>
        <appender-ref ref="YourAppenderName"/>
    </root>

</log4j:configuration>
Code language: HTML, XML (xml)

How to Submit Logs and Output

• For full log files: Please send log files as an email attachment or upload them directly to the support ticket on our website. When you are logged in, our portal supports file uploads up to 5TB, so there should be no issue uploading large log files or heap dumps. Do not paste large log files into a ticket comment, as our system will reject comments with too much text.
• For short snippets (< 10 lines) or command output: If you want to include a small excerpt or command output, you can paste it directly into a ticket comment. Our website editor uses Markdown, so please wrap the text in triple backticks (“`) to ensure it is formatted correctly and readable.

For example:

```
java -version
java version "11.0.12" 2021-07-20 LTS
Java(TM) SE Runtime Environment 18.9 (build 11.0.12+8-LTS-237)
Java HotSpot(TM) 64-Bit Server VM 18.9 (build 11.0.12+8-LTS-237, mixed mode)
```

For Out-Of-Memory (OOM) Errors: A Heap Dump is Mandatory

An Out-Of-Memory error is one of the most complex issues to diagnose. A log file can tell us what was happening when the error occurred, but it cannot tell us what was consuming the memory.

For any OOM issue, we require a heap dump. A heap dump is a snapshot of the application’s memory that allows us to perform a forensic analysis and pinpoint the exact objects that are causing the memory exhaustion.

You can securely upload heap dumps directly to your support ticket via our customer portal. We cannot proceed with an OOM investigation without one.

Setting Expectations on Communication and Escalations

We understand that when you have an issue, it can be a high priority for your business. Please be assured that if your ticket is in an “Open” state, it is in our queue and we are working on it.

• Constant Updates: Asking for constant updates when a ticket has not been idle for long does not expedite the process. If we have new information or require more from you, we will update the ticket.
• Ticket Status: If a ticket is marked as “Pending,” it means we are waiting for information from you (e.g., logs, a heap dump, a reproducible test case). The ball is in your court.
• Escalations: Statements like “this has been escalated to our management” serve no purpose. All customers receive the same high standard of support, and tickets are prioritized based on their technical severity and your support level. These statements do not alter a ticket’s position in the queue.
• Working Hours and Timezones: We support customers across the globe. Our support team operates from 9am to 6pm GMT/BST (UK time). Tickets and updates received outside of these hours will be addressed on the next business day. We appreciate your patience and understanding of these time differences.

Your Pre-Flight Checklist for a New Ticket

Before raising a new support issue, please ensure you have collated the following:

1. A clear and verbose explanation of the issue, including the expected and actual behavior.
2. The product being used and the specific version(s) where you are seeing the issue.
3. A simple, portable, and self-contained reproducible test case with clear instructions.
4. A complete, unfiltered DEBUG log file from our API (as described above).
5. For OOM errors, a heap dump.

By providing this information upfront, you enable us to help you more effectively. This partnership ensures that we can spend our time solving your problem, not asking for the information needed to start. Thank you for your cooperation.