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.

For Application Lock-Ups: A Thread Dump is Essential

When an application becomes unresponsive, “hangs,” or “freezes,” it is often caused by a threading issue such as a deadlock or resource contention. In these scenarios, the application is stuck, so log files will stop updating and a heap dump may not reveal the root cause.

For any application lock-up issue, we require a thread dump. A thread dump is a snapshot of the state of all threads within the JVM. It is a vital tool that allows us to see exactly what each thread was doing at a specific moment in time, helping us diagnose deadlocks and other concurrency problems.

For best results, please provide a series of 3-4 thread dumps taken 10-15 seconds apart. This helps us see if threads are stuck or progressing. You can generate a thread dump using the jstack utility included with the JDK: jstack <pid> > threaddump.txt.

A Note on Data Sensitivity and Access

We understand that log files and heap dumps can contain sensitive information, and some customers have internal policies that restrict sharing these artifacts. However, these files are essential tools for our diagnostic process.

Please be aware of our standard support policy on this matter:

Artifacts are non-negotiable: To investigate complex issues like OOM errors or subtle bugs, we must have the required log files and heap dumps available for our own offline analysis.
Screen sharing is not a substitute: Analyzing these files is a meticulous and time-consuming process. It cannot be done effectively during a live screen-sharing session. We need the ability to use our specialized tools and dedicate focused time to the investigation.
We can sign an NDA: To facilitate the secure sharing of these artifacts, we are willing to sign a general Non-Disclosure Agreement (NDA). If your company policy requires an NDA to be in place, please contact us to arrange this ahead of time.
If you cannot provide the required files: We respect your data policies, but if you are unable to provide the artifacts required for our standard support process, we will be unable to support that specific issue.

Extended Support: Live Interactive Debugging

For customers who require a more hands-on approach for issue reproduction, we offer a premium Live Interactive Debugging service. This is a paid add-on that must be purchased in advance.

This service is designed for interactive diagnostics, allowing our developers to work directly with you in your environment. It includes:

Live Screen Sharing Sessions: You can demonstrate the issue and share code live with one of our developers.
Interactive Remote Debugging: We may ask you to connect to our secure support server using a reverse SSH client. This creates a temporary, secure SSH tunnel that allows our developers to connect their local development tools directly to a server in your network, without requiring inbound firewall changes or VPN access on your part.

While this service provides a powerful way to diagnose environment-specific issues, please note that it is an interactive process, not a substitute for providing data. To fully resolve complex problems, we may still require log files or other artifacts to be shared for a conclusive offline analysis.

Please contact us if you would like to learn more about this extended support option.

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 developers support customers from on weekdays 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:

A clear and verbose explanation of the issue, including the expected and actual behavior.
The product being used and the specific version(s) where you are seeing the issue.
A simple, portable, and self-contained reproducible test case with clear instructions.
A complete, unfiltered DEBUG log file from our API (as described above).
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.