mirror of
https://github.com/taoensso/telemere.git
synced 2026-01-28 17:10:33 +00:00
61 lines
7 KiB
HTML
61 lines
7 KiB
HTML
|
<!DOCTYPE html PUBLIC ""
|
||
|
|
"">
|
||
|
|
<html><head><meta charset="UTF-8" /><title>taoensso.telemere.postal documentation</title><link rel="stylesheet" type="text/css" href="css/default.css" /><link rel="stylesheet" type="text/css" href="css/highlight.css" /><script type="text/javascript" src="js/highlight.min.js"></script><script type="text/javascript" src="js/jquery.min.js"></script><script type="text/javascript" src="js/page_effects.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body><div id="header"><h2>Generated by <a href="https://github.com/weavejester/codox">Codox</a></h2><h1><a href="index.html"><span class="project-title"><span class="project-name">Telemere</span> <span class="project-version">1.0.0-beta4</span></span></a></h1><div id="langs"><div class="lang current">clj</div><div class="lang"><a href="index.cljs.html">cljs</a></div></div></div><div class="sidebar primary"><h3 class="no-link"><span class="inner">Namespaces</span></h3><ul><li class="depth-1"><div class="no-link"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>taoensso</span></div></div></li><li class="depth-2"><a href="taoensso.telemere.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>telemere</span></div></a></li><li class="depth-3 branch"><a href="taoensso.telemere.open-telemetry.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>open-telemetry</span></div></a></li><li class="depth-3 branch current"><a href="taoensso.telemere.postal.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>postal</span></div></a></li><li class="depth-3 branch"><a href="taoensso.telemere.streams.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>streams</span></div></a></li><li class="depth-3 branch"><a href="taoensso.telemere.timbre.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>timbre</span></div></a></li><li class="depth-3 branch"><a href="taoensso.telemere.tools-logging.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>tools-logging</span></div></a></li><li class="depth-3"><a href="taoensso.telemere.utils.html"><div class="inner"><span class="tree"><span class="top"></span><span class="bottom"></span></span><span>utils</span></div></a></li></ul></div><div class="sidebar secondary"><h3><a href="#top"><span class="inner">Public Vars</span></a></h3><ul><li class="depth-1"><a href="taoensso.telemere.postal.html#var-a-handler.3Apostal"><div class="inner"><span>a-handler:postal</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.postal.html#var-format-signal-.3Esubject-fn"><div class="inner"><span>format-signal->subject-fn</span></div></a></li><li class="depth-1"><a href="taoensso.telemere.postal.html#var-handler.3Apostal"><div class="inner"><span>handler:postal</span></div></a></li></ul></div><div class="namespace-docs" id="content"><h1 class="anchor" id="top">taoensso.telemere.postal</h1><div class="doc"><pre class="plaintext">Email handler using `postal`,
|
||
|
|
Ref. <<a href="https://github.com/drewr/postal">https://github.com/drewr/postal</a>>.</pre></div><div class="public anchor" id="var-a-handler.3Apostal"><h3>a-handler:postal</h3><h4 class="lang current">clj</h4><div class="usage"><code>(a-handler:postal)</code><code>(a-handler:postal signal)</code></div><div class="doc"><pre class="plaintext"></pre></div></div><div class="public anchor" id="var-format-signal-.3Esubject-fn"><h3>format-signal->subject-fn</h3><h4 class="lang current">clj</h4><div class="usage"><code>(format-signal->subject-fn)</code><code>(format-signal->subject-fn {:keys [max-len subject-signal-key], :or {max-len 128, subject-signal-key :postal/subject}})</code></div><div class="doc"><pre class="plaintext">Experimental, subject to change.
|
||
|
|
Returns a (fn format [signal]) that:
|
||
|
|
- Takes a Telemere signal.
|
||
|
|
- Returns a formatted email subject like:
|
||
|
|
"INFO EVENT :taoensso.telemere.postal/ev-id1 - msg"</pre></div></div><div class="public anchor" id="var-handler.3Apostal"><h3>handler:postal</h3><h4 class="lang current">clj</h4><div class="usage"><code>(handler:postal)</code><code>(handler:postal {:keys [postal/conn-opts postal/msg-opts format-signal-fn format-signal->subject-fn], :or {format-signal-fn (utils/format-signal->str-fn), format-signal->subject-fn (format-signal->subject-fn)}})</code></div><div class="doc"><pre class="plaintext">Experimental, subject to change. Feedback welcome!
|
||
|
|
|
||
|
|
Needs `postal`,
|
||
|
|
Ref. <<a href="https://github.com/drewr/postal">https://github.com/drewr/postal</a>>.
|
||
|
|
|
||
|
|
Returns a (fn handler [signal]) that:
|
||
|
|
- Takes a Telemere signal.
|
||
|
|
- Sends an email with formatted signal content to the configured recipient.
|
||
|
|
|
||
|
|
Useful for emailing important alerts to admins, etc.
|
||
|
|
|
||
|
|
NB can incur financial costs!!
|
||
|
|
See tips section re: protecting against unexpected costs.
|
||
|
|
|
||
|
|
Options:
|
||
|
|
|
||
|
|
`:postal/conn-opts` - Map of connection opts provided to `postal`
|
||
|
|
Examples:
|
||
|
|
{:host "mail.isp.net", :user "jsmith", :pass "a-secret"},
|
||
|
|
{:host "smtp.gmail.com", :user "jsmith@gmail.com", :pass "a-secret" :port 587 :tls true},
|
||
|
|
{:host "email-smtp.us-east-1.amazonaws.com", :port 587, :tls true
|
||
|
|
:user "AKIAIDTP........" :pass "AikCFhx1P......."}
|
||
|
|
|
||
|
|
`:postal/msg-opts` - Map of message options
|
||
|
|
Examples:
|
||
|
|
{:from "foo@example.com", :to "bar@example.com"},
|
||
|
|
{:from "Alice <foo@example.com", :to "Bob <bar@example.com>"},
|
||
|
|
{:from "no-reply@example.com", :to ["first-responders@example.com",
|
||
|
|
"devops@example.com"],
|
||
|
|
:cc "engineering@example.com"
|
||
|
|
:X-MyHeader "A custom header"}
|
||
|
|
|
||
|
|
`:format-signal-fn` - (fn [signal]) => output, see `help:signal-formatters`
|
||
|
|
`:format-signal->subject-fn` - (fn [signal]) => email subject string
|
||
|
|
|
||
|
|
Tips:
|
||
|
|
|
||
|
|
- Sending emails can incur financial costs!
|
||
|
|
Use appropriate dispatch filtering options when calling `add-handler!` to prevent
|
||
|
|
handler from sending unnecessary emails!
|
||
|
|
|
||
|
|
At least ALWAYS set an appropriate `:rate-limit` option, e.g.:
|
||
|
|
(add-handler! :my-postal-handler (handler:postal {<my-handler-opts})
|
||
|
|
{:rate-limit {"Max 1 per min" [1 (enc/msecs :mins 1)]
|
||
|
|
"Max 3 per 15 mins" [3 (enc/msecs :mins 15)]
|
||
|
|
"Max 5 per hour" [5 (enc/msecs :hours 1)]}, ...}), etc.
|
||
|
|
|
||
|
|
- Sending emails is slow!
|
||
|
|
Use appropriate async dispatch options when calling `add-handler!` to prevent
|
||
|
|
handler from blocking signal creator calls, e.g.:
|
||
|
|
(add-handler! :my-postal-handler (handler:postal {<my-handler-opts>})
|
||
|
|
{:async {:mode :dropping, :buffer-size 128, :n-threads 4} ...}), etc.
|
||
|
|
|
||
|
|
- Ref. <<a href="https://github.com/drewr/postal">https://github.com/drewr/postal</a>> for more info on `postal` options.</pre></div></div></div></body></html>
|