Add when-things-do-not-work section

ptarmiganlabs · Jan 10, 2024 · 5aead19 · 5aead19
1 parent 95c9cd7
commit 5aead19
Show file tree

Hide file tree

Showing 229 changed files with 1,817 additions and 222 deletions.
diff --git a/content/en/docs/examples/when things dont work/_index.md b/content/en/docs/examples/when things dont work/_index.md
@@ -0,0 +1,89 @@
+---
+title: "When things don't work as expected"
+linkTitle: "When things don't work"
+weight: 9000
+description: >
+  Tips and tricks for troubleshooting Butler.
+---
+
+Butler is a complex piece of software, and it is not uncommon to run into issues when [setting up and configuring](/docs/getting-started/setup/) Butler.  
+In the vast majority of cases, the issues are caused by misconfiguration, and not by bugs in the tool itself.
+
+This page contains some tips and tricks that can be useful when troubleshooting a Butler instance.
+
+## General things to check
+
+### Is Butler running?
+
+The first thing to check is if Butler is running at all.
+
+If Butler is running as a Windows service, check the Windows Services applet to see if the service is running.
+
+If Butler is running as a Docker container, check the Docker container status with the `docker ps` command.
+
+### Logs
+
+Make sure logging to file is enabled in the Butler configuration file.  
+Take note of the log file location.
+
+Then check the log files for errors and warnings.
+
+In theory errors and warnings can occur as part of normal operation, but that should be rate.  
+If there are errors or warnings during startup, or if there are a lot of errors and warnings, then there is most likely a problem.
+
+You can also try increasing the log level to `verbose` or even `debug` to get more information about what's happening, and where in Butler the problem is occurring.
+
+Logging level is configured in the Butler configuration file or via the `--loglevel` command line parameter (which takes precedence over the configuration file).
+
+## Feature specific issues
+
+### Failed reload alerts not working
+
+Butler offers quite comprehensive support for dealing with failed or aborted reloads tasks.  
+As such there are a number of things that can go wrong and settings that can be misconfigured.
+
+When configured correctly, Butler's logs can look like below.  
+In this example Butler has received a reload task failure event from Qlik Sense, and is now sending out notifications to the following channels:
+
+- Script log archive (all failed reload logs are archived to a folder on disk)
+- InfluxDB (from where the reload failure can be visualized in a Grafana dashboard)
+- Slack
+- Teams
+- Outgoing webhook
+- Email
+
+```text
+2024-01-10T05:47:52.992Z info: SCRIPTLOG STORE: Writing failed task script log: C:\tools\butler\config\scriptlog\2024-01-10\2024-01-10_06-47-52_appId=8f1d1ecf-97a6-4eb5-8f47-f9156300b854_taskId=22b106a8-e7ed-4466-b700-014f060bef16.log
+2024-01-10T05:47:52.994Z info: INFLUXDB RELOAD TASK FAILED: Sending reload task notification to InfluxDB
+2024-01-10T05:47:53.008Z info: SLACK RELOAD TASK FAILED: Rate limiting check passed for failed task notification. Task name: "Reload of Test failing reloads 1 (emojis supported! 🤪)"
+2024-01-10T05:47:53.017Z info: TEAMS RELOAD TASK FAILED: Rate limiting check passed for failed task notification. Task name: "Reload of Test failing reloads 1 (emojis supported! 🤪)"
+2024-01-10T05:47:53.021Z info: WEBHOOK OUT RELOAD TASK FAILED: Rate limiting check passed for failed task notification. Task name: "Reload of Test failing reloads 1 (emojis supported! 🤪)"
+2024-01-10T05:47:53.300Z info: EMAIL RELOAD TASK FAILED ALERT: Rate limiting check passed for failed task notification. Task name: "Reload of Test failing reloads 1 (emojis supported! 🤪)", Recipient: "[email protected]"
+```
+
+{{% notice tip %}}
+Rate limiting is defined in the Butler configuration file.  
+If the rate limiting condition is met, this will be shown as "Rate limiting check passed for failed task notification" in the logs.
+{{% /notice %}}
+
+Things to check:
+
+- Is Butler receiving the reload task events from Qlik Sense?
+  - Check the Butler log files.
+    When Butler receives a reload task event from Qlik Sense, it will check if rate limiting conditions are met, and also log a message about that.
+    If there are no such messages:
+    - Butler has not received the event from Qlik Sense.
+    - Check the XML appender files deployed to the Qlik Sense servers. Make sure they send UDP events to the host and port where Butler is listening.
+    - Try pinging the host where Butler is running, from the Qlik Sense server (`ping <butler host>`). If the ping fails, there is probably a network issue.
+    - Try doing a telnet to the UDP port where Butler is listening from the Qlik Sense server (`telnet <butler host> <butler port>`). If the telnet fails, there is for sure a network issue.
+    - Make sure reload failure events are enabled in the Butler configuration file.
+- Are reload failure events received from some Sense nodes, but not others?
+  - Check the XML appenders on the nodes where the events are not received.
+  - Check the network connectivity between the nodes and the Butler host.
+  - The XML appender files can be identical on all nodes.
+- Are some reload failure events forwarded to destinations, but not others?
+  - Check the Butler log files.
+  - Is rate limiting enabled? If so, check the rate limiting settings in the Butler configuration file.
+  - If events arrive more frequently than the rate limiting settings allow, Butler will not forward all events.
+    A failed rate limiting check will result in a log warning:  
+    `Rate limiting failed. Not sending reload notification email for task ...`
diff --git a/docs/404.html b/docs/404.html
@@ -144,7 +144,7 @@ <h1>Not found</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2019/11/01/v3.0.0-enable-some-rest-api-endpoints-disable-others./index.html b/docs/blog/2019/11/01/v3.0.0-enable-some-rest-api-endpoints-disable-others./index.html
@@ -309,7 +309,7 @@ <h1>v3.0.0: Enable some REST API endpoints, disable others.</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2019/11/29/new-documentation-site-for-butler/index.html b/docs/blog/2019/11/29/new-documentation-site-for-butler/index.html
@@ -328,7 +328,7 @@ <h1>New documentation site for Butler</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2019/11/29/v3.0.1-docker-health-check-is-now...-healthy./index.html b/docs/blog/2019/11/29/v3.0.1-docker-health-check-is-now...-healthy./index.html
@@ -308,7 +308,7 @@ <h1>v3.0.1: Docker health check is now... healthy.</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2020/07/15/v3.1.0-an-armful-of-heart-beats/index.html b/docs/blog/2020/07/15/v3.1.0-an-armful-of-heart-beats/index.html
@@ -314,7 +314,7 @@ <h1>v3.1.0: An armful of heart beats</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2020/10/21/material-added-to-butler-doc-site/index.html b/docs/blog/2020/10/21/material-added-to-butler-doc-site/index.html
@@ -314,7 +314,7 @@ <h1>Material added to Butler doc site</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2020/10/21/v4.0.0-a-senseops-reboot/index.html b/docs/blog/2020/10/21/v4.0.0-a-senseops-reboot/index.html
@@ -324,7 +324,7 @@ <h1>v4.0.0: A SenseOps reboot</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2020/10/27/v4.1.0-file-copying--qlik-sense-useful/index.html b/docs/blog/2020/10/27/v4.1.0-file-copying--qlik-sense-useful/index.html
@@ -311,7 +311,7 @@ <h1>v4.1.0: File copying &#43; Qlik Sense = Useful</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2020/10/28/v4.1.1-fixing-broken-start-sense-task-api-endpoint/index.html b/docs/blog/2020/10/28/v4.1.1-fixing-broken-start-sense-task-api-endpoint/index.html
@@ -309,7 +309,7 @@ <h1>v4.1.1: Fixing broken start Sense task API endpoint</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2020/10/28/v4.1.2-sense-demo-app-can-now-start-reloads/index.html b/docs/blog/2020/10/28/v4.1.2-sense-demo-app-can-now-start-reloads/index.html
@@ -308,7 +308,7 @@ <h1>v4.1.2: Sense demo app can now start reloads</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2020/11/07/v4.2.0-failed-reloads-notify-me/index.html b/docs/blog/2020/11/07/v4.2.0-failed-reloads-notify-me/index.html
@@ -320,7 +320,7 @@ <h1>v4.2.0: Failed reloads? Notify me!</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2021/02/03/file-operations-examples-and-better-setup-instructions/index.html b/docs/blog/2021/02/03/file-operations-examples-and-better-setup-instructions/index.html
@@ -310,7 +310,7 @@ <h1>File operations examples and better setup instructions</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2021/02/03/v4.3.0-bug-fixes-improved-documentation/index.html b/docs/blog/2021/02/03/v4.3.0-bug-fixes-improved-documentation/index.html
@@ -318,7 +318,7 @@ <h2 id="great-features-are-useless-if-no-one-uses-them">Great features are usele
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2021/02/24/v5.0.0-reload-alerting-deluxe/index.html b/docs/blog/2021/02/24/v5.0.0-reload-alerting-deluxe/index.html
@@ -329,7 +329,7 @@ <h2 id="be-the-first-to-know">Be the first to know</h2>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2021/03/03/v5.1.0-sharing-is-caring/index.html b/docs/blog/2021/03/03/v5.1.0-sharing-is-caring/index.html
@@ -345,7 +345,7 @@ <h2 id="go-get-it">Go get it!</h2>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2021/04/12/v5.3.0-key-value-refinement/index.html b/docs/blog/2021/04/12/v5.3.0-key-value-refinement/index.html
@@ -320,7 +320,7 @@ <h2 id="bug-fixes">Bug fixes</h2>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/2023/04/14/butler-blog-moved-to-ptarmiganlabs.com/index.html b/docs/blog/2023/04/14/butler-blog-moved-to-ptarmiganlabs.com/index.html
@@ -307,7 +307,7 @@ <h1>Butler blog moved to ptarmiganlabs.com</h1>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/_print/index.html b/docs/blog/_print/index.html
@@ -1113,7 +1113,7 @@ <h1 id="pg-e203f4e49f0eec978d55acc184959bcc">v3.0.0: Enable some REST API endpoi
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/index.html b/docs/blog/index.html
@@ -654,7 +654,7 @@ <h5 class="mt-0 mb-1"><a href="/blog/2020/10/28/v4.1.1-fixing-broken-start-sense
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/news/_print/index.html b/docs/blog/news/_print/index.html
@@ -392,7 +392,7 @@ <h1 id="pg-9078bb37de50c00f158651c91fcdbe7a">New documentation site for Butler</
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/news/index.html b/docs/blog/news/index.html
@@ -441,7 +441,7 @@ <h5 class="mt-0 mb-1"><a href="/blog/2019/11/29/new-documentation-site-for-butle
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/page/2/index.html b/docs/blog/page/2/index.html
@@ -556,7 +556,7 @@ <h5 class="mt-0 mb-1"><a href="/blog/2019/11/01/v3.0.0-enable-some-rest-api-endp
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/releases/_print/index.html b/docs/blog/releases/_print/index.html
@@ -806,7 +806,7 @@ <h1 id="pg-e203f4e49f0eec978d55acc184959bcc">v3.0.0: Enable some REST API endpoi
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/releases/index.html b/docs/blog/releases/index.html
@@ -656,7 +656,7 @@ <h5 class="mt-0 mb-1"><a href="/blog/2020/10/21/v4.0.0-a-senseops-reboot/">v4.0.
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/blog/releases/page/2/index.html b/docs/blog/releases/page/2/index.html
@@ -410,7 +410,7 @@ <h5 class="mt-0 mb-1"><a href="/blog/2019/11/01/v3.0.0-enable-some-rest-api-endp
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/community/_print/index.html b/docs/community/_print/index.html
@@ -227,7 +227,7 @@ <h2>Develop and Contribute</h2>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>

diff --git a/docs/community/index.html b/docs/community/index.html
@@ -227,7 +227,7 @@ <h2>Develop and Contribute</h2>
 
       </div>
       <div class="col-12 col-sm-4 text-center py-2 order-sm-2">
-        <small class="text-white">&copy; 2023 Ptarmigan Labs AB All Rights Reserved</small>
+        <small class="text-white">&copy; 2024 Ptarmigan Labs AB All Rights Reserved</small>
 
 
 		<p class="mt-2"><a href="/docs/about/">About</a></p>