2024-04-29 07:21:13 +00:00
< !DOCTYPE html PUBLIC ""
"">
2024-04-29 10:21:02 +00:00
< 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-beta5< / 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`,
2024-04-29 07:21:13 +00:00
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 >
