extern/apprise
1
0
Fork 0
mirror of https://github.com/caronc/apprise.git synced 2024-12-12 18:01:08 +01:00
Code Issues Packages Projects Releases Wiki Activity

Updated Troubleshooting (markdown)

Chris Caron 2019-08-14 09:22:49 -04:00
parent 6fd2c48b61
commit cb141681f3
1 changed files with 9 additions and 9 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
Troubleshooting.md

@ -13,9 +13,9 @@ If the output appears cryptic, or you feel that you've exhausted all avenues, Do
Just be cautious as the debugging information can potentially expose personal information (such as your password and/or private access tokens) to the screen. Please remember to erase this or swap it with some random characters before posting such a thing publicly.
## To Much Data and Overflow Directive
Out of the box, apprise passes _everything_ you give it right along to the source. Some sources can handle a large surplus of data; others might not deal with it as well and just not post anything at all.
Out of the box, Apprise passes _everything_ you give it right along to the notification source. Some sources can handle a large surplus of data; others might not deal with it as well and as a result, your notification doesn't seem to go through).
Apprise has a somewhat non-elegant way of handling this situation; but it's much better than nothing. You simply need to tack on the **overflow** switch somewhere in your Apprise URL; for example:
Apprise has a somewhat non-elegant way of handling this situation; but it's better than nothing. You simply need to tack on the **overflow** switch somewhere in your Apprise URL; for example:
* `schema://path/?overflow=split`
* `schema://path/?overflow=truncate`
* `schema://path/?overflow=upstream`
@ -25,16 +25,16 @@ The possible **overflow=** options are defined as:
| Variable | Description
| ----------- | ----------- |
| **split** | This will break the message body (and title if required) into as many smaller chunks (based on the confines of the service itself) and send out multiple messages in order to deliver everything.<br/><br/>For example, Twitter restricts public tweets to 280 characters. If your Apprise/Twitter URL was updated to look like `twitter://<auth data>/?overflow=split`, A message of say 1000 characters would be broken (and sent) via 4 smaller messages (280 + 280 + 280 + 160).
| **truncate** | This just ensures that regardless of how much content you're sending to an remote notification service, all of it's contents will be truncated to fit within a single message. This means that any data that exceeds the maximum message side will just be removed for the message itself.
| **upstream** | Let the upstream notification service handle all of the data passed to it. Apprise will not mangle/change it's content in any way.<br/>**Note**: This is the default configuration option used when the `overflow=` directive is not set.
| **split** | This will break the message body into as many smaller chunks as it takes to ensure the full delivery of what you wanted to notify with. The smaller chunk sizes are based on the very restrictions put out by the notification service itself.<br/><br/>For example, _Twitter_ restricts public tweets to 280 characters. If your Apprise/Twitter URL was updated to look like this: `twitter://<auth data>/?overflow=split`, A message of say 1000 characters would be broken (and sent) via 4 smaller messages (280 + 280 + 280 + 160).
| **truncate** | This just ensures that regardless of how much content you're passing along to a remote notification service, the contents will never exceed the restrictions set by the service itself.<br/><br/>Take our _Twitter_ example again (which restricts public tweets to 280 characters), If your Apprise/Twitter URL was updated to look like this: `twitter://<auth data>/?overflow=truncate`, A message of say 1000 characters would only send the first 280 characters to it. The rest would just be _truncated_ and ignored.
| **upstream** | Simply let the the upstream notification service handle all of the data passed to it (large or small). Apprise will not mangle/change it's content in any way.<br/>**Note**: This is the default configuration option used when the `overflow=` directive is not set.
Please note that the **overflow=** option isn't a perfect solution:
* It can fail for services like Telegram which can take content in the format of both _HTML_ and _Markdown_. If you're using _HTML_, then there is a very strong possibility that both the upstream and/or truncate option could cut your message in the middle of an un-closed HTML tag. Telegram doesn't fair to well to this and in the past (at the time of writing this wiki entry) would error and not display the data.
* It doesn't elegantly wrap/truncate messages the end of a word (near the message limits). It just makes a cut right at the limit itself. Similarly with `?overflow=split` this hard cut happens throughout all of the messages needed to still send all of the content needed.
* The `overflow=split` can work against you too, especially if you're using apprise to send thousands of log entries accidentally to you via a SMS message. Be prepared to get hundreds of text messages to re-construct all of the data you asked it to deliver! :wink:
* It can fail for services like Telegram which can take content in the format of _HTML_ (in addition to _Markdown_). If you're using _HTML_, then there is a very strong possibility that both the `overflow=split` and/or `overflow=truncate` option could cut your message in the middle of an un-closed HTML tag. Telegram doesn't fair to well to this and in the past (at the time of writing this wiki entry) would error and not display the data.
* It doesn't elegantly split/truncate messages the end of a word (near the message limits). It just makes a cut right at the notification services hard limit itself.
* The `overflow=split` can work against you. Consider a situation where you send thousands of log entries accidentally to you via an SMS notification service. Be prepared to get hundreds of text messages to re-construct all of the data you asked it to deliver! This may or may not be what you wanted to happen; in this case, perhaps `overflow=truncate` is a better choice. Some services might even concur extra costs on you if you exceed a certain message threshold. The point is, just be open minded when you choose to enable the _split_ option with notification services that have very small message size limits. The good news that each supported notification service on the [Apprise Wiki](https://github.com/caronc/apprise/wiki) identifies what each hard limit is set to.
So while this is a viable solution for most services; consider that it may not work perfectly for all.
So while the overflow _switch_ is a viable solution for most notification services; consider that it may not work perfectly for all.
## Special Characters and URL Conflicts
Apprise is built around URLs. Unfortunately URLs have pre-reserved characters it uses as delimiters that help distinguish one argument/setting from another.