|
| 1 | +--- |
| 2 | +sidebar_position: 21 |
| 3 | +id: Diagnostics |
| 4 | +title: Diagnostics & Reporting Issues |
| 5 | +description: Use the built-in diagnostics tool and learn how to report issues effectively |
| 6 | +tags: |
| 7 | + - Diagnostics |
| 8 | + - Troubleshooting |
| 9 | + - Support |
| 10 | +--- |
| 11 | + |
| 12 | +# Diagnostics & Reporting Issues |
| 13 | + |
| 14 | +Stirling PDF includes a built-in diagnostics tool inside Docker containers that collects logs, configuration, system information, and application metrics into a single archive. This is the fastest way to gather the information needed when troubleshooting or reporting issues. |
| 15 | + |
| 16 | +--- |
| 17 | + |
| 18 | +## Running the Diagnostics Tool |
| 19 | + |
| 20 | +Open an interactive shell inside the running container and invoke the tool: |
| 21 | + |
| 22 | +```bash |
| 23 | +docker exec -it <container_name> diag |
| 24 | +``` |
| 25 | + |
| 26 | +The following aliases all work identically: `diag`, `debug`, `diagnostic`, `diagnostics`, `stirling-diagnostics`. |
| 27 | + |
| 28 | +:::caution Interactive Terminal Required |
| 29 | +The diagnostics tool requires an interactive terminal (`-it` flag). It will not run in non-interactive or headless sessions. |
| 30 | +::: |
| 31 | + |
| 32 | +--- |
| 33 | + |
| 34 | +## Collection Modes |
| 35 | + |
| 36 | +When you run the tool, you'll be prompted to choose a collection mode. |
| 37 | + |
| 38 | +### Auto Mode (Recommended) |
| 39 | + |
| 40 | +Select option **1** when prompted. Auto mode collects: |
| 41 | + |
| 42 | +- Application logs from the last 24 hours |
| 43 | +- Configuration files from `/configs` |
| 44 | +- System information (OS, CPU, memory, disk, Java version) |
| 45 | +- Application metrics and health endpoints |
| 46 | + |
| 47 | +This is sufficient for most issue reports. |
| 48 | + |
| 49 | +### Custom Mode |
| 50 | + |
| 51 | +Select option **2** for granular control over what gets collected: |
| 52 | + |
| 53 | +| Prompt | Default | What It Collects | |
| 54 | +|---|---|---| |
| 55 | +| Output directory | `/configs` | Where to save the archive | |
| 56 | +| Days of logs | 1 | How many days of logs to include | |
| 57 | +| Include /configs | Yes | Configuration files | |
| 58 | +| Include /customFiles | No | Custom files (excluding PDFs and images) | |
| 59 | +| Include /pipeline | No | Pipeline working files (excluding PDFs) | |
| 60 | +| Include /tmp/stirling-pdf | No | Temporary processing files | |
| 61 | +| Include system information | Yes | OS, CPU, RAM, disk, Java/Python versions | |
| 62 | +| Include environment variables | No | Full environment dump | |
| 63 | +| Fetch metrics endpoints | Yes | Application status, health, and load data | |
| 64 | +| Include UI data endpoints | No | Sign, pipeline, and OCR endpoint data | |
| 65 | +| Redact sensitive information | Yes | Apply redaction filters (see below) | |
| 66 | + |
| 67 | +### Redaction Options |
| 68 | + |
| 69 | +When redaction is enabled, you can selectively mask: |
| 70 | + |
| 71 | +- **Secrets/tokens/passwords** - Redacts Authorization headers, API keys, passwords, and similar credentials |
| 72 | +- **URL hosts/domains** - Masks hostnames in URLs |
| 73 | +- **Email addresses** - Replaces email addresses with `[REDACTED_EMAIL]` |
| 74 | +- **Host/Domain/Server fields** - Masks values in host-related configuration fields |
| 75 | + |
| 76 | +:::caution |
| 77 | +Always enable redaction if you plan to share the diagnostics bundle publicly (for example, in a GitHub issue). However, redaction is not perfect and may miss some sensitive values - always review the output manually before sharing publicly. You can disable redaction for private support channels if full detail is needed. |
| 78 | +::: |
| 79 | + |
| 80 | +--- |
| 81 | + |
| 82 | +## What Gets Collected |
| 83 | + |
| 84 | +The diagnostics bundle is a `.tar.gz` archive saved to the output directory (default: `/configs`). It contains: |
| 85 | + |
| 86 | +``` |
| 87 | +stirling-diagnostics-YYYYMMDD-HHMMSS.tar.gz |
| 88 | +├── summary.txt # Collection metadata and settings |
| 89 | +├── bundle/ |
| 90 | +│ ├── logs/ # Application log files |
| 91 | +│ ├── configs/ # Configuration files (settings.yml, etc.) |
| 92 | +│ ├── system/ # System information |
| 93 | +│ │ ├── uname.txt # Kernel version |
| 94 | +│ │ ├── os-release # OS distribution info |
| 95 | +│ │ ├── meminfo.txt # Memory details |
| 96 | +│ │ ├── cpuinfo.txt # CPU details |
| 97 | +│ │ ├── df.txt # Disk usage |
| 98 | +│ │ ├── free.txt # Memory summary |
| 99 | +│ │ ├── ps.txt # Running processes |
| 100 | +│ │ ├── java-version.txt # Java runtime version |
| 101 | +│ │ └── python-version.txt # Python version |
| 102 | +│ ├── metrics/ # Application metrics |
| 103 | +│ │ ├── api/v1/info/status.json |
| 104 | +│ │ ├── api/v1/info/uptime.json |
| 105 | +│ │ ├── api/v1/info/health.json |
| 106 | +│ │ ├── api/v1/info/requests.json |
| 107 | +│ │ ├── api/v1/info/load.json |
| 108 | +│ │ ├── actuator/health.json |
| 109 | +│ │ └── actuator/prometheus.txt |
| 110 | +│ ├── env/ # Environment variables (if requested) |
| 111 | +│ └── tree/ # Directory listings |
| 112 | +│ ├── logs.txt |
| 113 | +│ ├── configs.txt |
| 114 | +│ ├── customFiles.txt |
| 115 | +│ ├── pipeline.txt |
| 116 | +│ ├── tessdata.txt # Installed OCR language packs |
| 117 | +│ └── tessdata-mount.txt |
| 118 | +``` |
| 119 | + |
| 120 | +PDFs, images, and compressed archives are always excluded from collection. |
| 121 | + |
| 122 | +### Retrieving the Bundle |
| 123 | + |
| 124 | +After the tool finishes, copy the archive out of the container: |
| 125 | + |
| 126 | +```bash |
| 127 | +docker cp <container_name>:/configs/stirling-diagnostics-*.tar.gz ./ |
| 128 | +``` |
| 129 | + |
| 130 | +--- |
| 131 | + |
| 132 | +## AOT Diagnostics |
| 133 | + |
| 134 | +If you are running with AOT (Ahead-of-Time) compilation enabled (`STIRLING_AOT_ENABLE=true`), an additional diagnostics tool is available: |
| 135 | + |
| 136 | +```bash |
| 137 | +docker exec -it <container_name> aot-diag |
| 138 | +``` |
| 139 | + |
| 140 | +This tool diagnoses AOT cache generation failures, particularly on ARM64/aarch64 platforms. It checks cache integrity, JVM compatibility, and can run smoke tests. |
| 141 | + |
| 142 | +Aliases: `aot-diag`, `aot-diagnostics` |
| 143 | + |
| 144 | +--- |
| 145 | + |
| 146 | +## How to Report Issues |
| 147 | + |
| 148 | +When you encounter a problem with Stirling PDF, choose the right channel depending on the nature of your issue. |
| 149 | + |
| 150 | +### GitHub Issues - Bug Reports & Feature Requests |
| 151 | + |
| 152 | +For reproducible bugs and feature requests, open an issue at: |
| 153 | +**https://github.com/Stirling-Tools/Stirling-PDF/issues** |
| 154 | + |
| 155 | +The repository includes issue templates for bug reports and feature requests that will guide you through providing the right information. |
| 156 | + |
| 157 | +When submitting a bug report, include as much detail as possible: the diagnostics bundle (run `diag` in your container first), steps to reproduce the issue, expected vs. actual behavior, your deployment method (Docker, bare metal, Kubernetes), Stirling PDF version (visible in the UI footer or in `summary.txt` from the diagnostics bundle), and any commands, API requests, or actions you were performing when the issue occurred. The more context you provide, the faster it can be resolved. |
| 158 | + |
| 159 | +### Discord Community - Questions & Discussion |
| 160 | + |
| 161 | +For quick questions, troubleshooting help, and community discussion: |
| 162 | +**https://discord.gg/HYmhKj45pU** |
| 163 | + |
| 164 | +Discord is the best place for configuration help, setup questions, sharing workarounds with other users, general discussion about features and usage, and getting faster informal feedback before filing a formal issue. It's also great for following up on GitHub issues and having deeper conversations with the community. |
| 165 | + |
| 166 | +### Email Support |
| 167 | + |
| 168 | +For enterprise customers and licensing inquiries: |
| 169 | +**support@stirlingpdf.com** |
| 170 | + |
| 171 | +For security vulnerabilities: |
| 172 | +**security@stirlingpdf.com** or use the [GitHub Security Advisory](https://github.com/Stirling-Tools/Stirling-PDF/security) process. |
| 173 | + |
0 commit comments