diff --git a/README.md b/README.md index 2486df4..cbd4498 100644 --- a/README.md +++ b/README.md @@ -177,8 +177,8 @@ Detailed help is available without leaving your IDE: ### Included handlers -> See ✅ links for **features and usage** -> See 👍 links to **vote on handler** for future addition +See ✅ links below for **features and usage**, +See 👍 links below to **vote on future handlers**: | Target (↓) | Clj | Cljs | | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: | diff --git a/resources/signal-docstrings/signal-options.txt b/resources/signal-docstrings/signal-options.txt index 9bb4696..8e07489 100644 --- a/resources/signal-docstrings/signal-options.txt +++ b/resources/signal-docstrings/signal-options.txt @@ -30,8 +30,6 @@ Signal options (shared by all signal creators): handler output, so a great way to provide custom data/opts for use (only) by custom middleware/handlers. -handler-specific data that can just be ignored by other handlers - If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs! [1] `java.time.Instant` or `js/Date` diff --git a/src/taoensso/telemere/utils.cljc b/src/taoensso/telemere/utils.cljc index 0f9af35..e03d03c 100644 --- a/src/taoensso/telemere/utils.cljc +++ b/src/taoensso/telemere/utils.cljc @@ -645,6 +645,14 @@ (require '[jsonista.core :as jsonista]) (pr-signal-fn {:pr-fn jsonista/write-value-as-string ...}) + Motivation: + Why use this util instead of just directly using the print function + given to `:pr-fn`? Signals are optimized for cheap creation and easy handling, + so may contain things like nil values and duplicated content. + + This util efficiently clean signals of such noise, helping reduce + storage/transmission size, and making key info easier to see. + See also `format-signal-fn` for human-readable output." ([] (pr-signal-fn nil)) ([{:keys [pr-fn, incl-kvs? incl-nils? incl-newline? incl-keys] :as opts diff --git a/wiki/4-Handlers.md b/wiki/4-Handlers.md index d7497ba..f6e864b 100644 --- a/wiki/4-Handlers.md +++ b/wiki/4-Handlers.md @@ -1,32 +1,32 @@ Signal handlers process created signals to **do something with them** (analyse them, write them to console/file/queue/db, etc.). -Telemere includes a number of signal handlers out-the-box, and more may be available via the [community](./8-Community#handlers). +Telemere includes a number of signal handlers out-the-box, and more may be available via the [community](./8-Community#handlers-and-tools). You can also easily [write your own handlers](#writing-handlers) for any output or integration you need. # Included handlers -> See ✅ links for **features and usage** -> See 👍 links to **vote on handler** for future addition +See ✅ links below for **features and usage**, +See 👍 links below to **vote on future handlers**: -| Target (↓) | Clj | Cljs | -| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: | -| [Apache Kafka](https://kafka.apache.org/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | -| [AWS Kinesis](https://aws.amazon.com/kinesis/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | -| Console | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#handler:console) | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#handler:console) | -| Console (raw) | - | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#handler:console-raw) | -| [Datadog](https://www.datadoghq.com/) | [👍](https://github.com/taoensso/roadmap/issues/12) | [👍](https://github.com/taoensso/roadmap/issues/12) | -| Email | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.postal#handler:postal) | - | -| [Graylog](https://graylog.org/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | -| [Jaeger](https://www.jaegertracing.io/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | -| [Logstash](https://www.elastic.co/logstash) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | -| [OpenTelemetry](https://opentelemetry.io/) | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.open-telemetry#handler:open-telemetry) | [👍](https://github.com/taoensso/roadmap/issues/12) | -| [Redis](https://redis.io/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | -| SQL | [👍](https://github.com/taoensso/roadmap/issues/12) | - | -| [Slack](https://slack.com/) | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.slack#handler:slack) | - | -| TCP socket | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.sockets#handler:tcp-socket) | - | -| UDP socket | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.sockets#handler:udp-socket) | - | -| [Zipkin](https://zipkin.io/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | +| Target (↓) | Clj | Cljs | +| :--------------------------------------------- | :-----------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: | +| [Apache Kafka](https://kafka.apache.org/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | +| [AWS Kinesis](https://aws.amazon.com/kinesis/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | +| Console | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#handler:console) | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#handler:console) | +| Console (raw) | - | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere#handler:console-raw) | +| [Datadog](https://www.datadoghq.com/) | [👍](https://github.com/taoensso/roadmap/issues/12) | [👍](https://github.com/taoensso/roadmap/issues/12) | +| Email | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.postal#handler:postal) | - | +| [Graylog](https://graylog.org/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | +| [Jaeger](https://www.jaegertracing.io/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | +| [Logstash](https://www.elastic.co/logstash) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | +| [OpenTelemetry](https://opentelemetry.io/) | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.open-telemetry#handler:open-telemetry) | [👍](https://github.com/taoensso/roadmap/issues/12) | +| [Redis](https://redis.io/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | +| SQL | [👍](https://github.com/taoensso/roadmap/issues/12) | - | +| [Slack](https://slack.com/) | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.slack#handler:slack) | - | +| TCP socket | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.sockets#handler:tcp-socket) | - | +| UDP socket | [✅](https://cljdoc.org/d/com.taoensso/telemere/CURRENT/api/taoensso.telemere.sockets#handler:udp-socket) | - | +| [Zipkin](https://zipkin.io/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | # Configuring handlers diff --git a/wiki/5-Migrating.md b/wiki/5-Migrating.md index 16f5a64..17a6cf4 100644 --- a/wiki/5-Migrating.md +++ b/wiki/5-Migrating.md @@ -20,7 +20,7 @@ Migrating from Timbre to Telemere should be straightforward **unless you depend Where Timbre uses the term "appender", Telemere uses the more general "handler". Functionally they're the same thing. -Check which **Timbre appenders** you use, and whether a similar handler is [currently included](./4-Handlers#included-handlers) with Telemere or available via the [community](./8-Community#handlers). +Check which **Timbre appenders** you use, and whether a similar handler is [currently included](./4-Handlers#included-handlers) with Telemere or available via the [community](./8-Community#handlers-and-tools). If not, you may need to [write something yourself](./4-Handlers#writing-handlers). diff --git a/wiki/8-Community.md b/wiki/8-Community.md index 7cbed30..faf612d 100644 --- a/wiki/8-Community.md +++ b/wiki/8-Community.md @@ -4,22 +4,22 @@ My plan for Telemere is to offer a **stable core of limited scope**, then to foc If you spot issues with any linked resources, please **contact the relevant authors** to let them know! Thank you! 🙏 - [Peter](https://www.taoensso.com) -# Handlers +# Handlers and tools -Includes libraries or examples for handlers (see [Writing handlers](./4-Handlers#writing-handlers)), middleware, handler utils (e.g. formatters), etc.: +Includes libraries or examples for handlers (see [Writing handlers](./4-Handlers#writing-handlers)), middleware, handler utils (e.g. formatters), tools for analyzing signals, etc.: -| Date | Link | Description | -| :--- | :--- | :------------------------------------------------------------ | -| - | - | Your link here? [PRs](../wiki#contributions-welcome) welcome! | +| Date | Link | Type | Description | +| :--- | :--- | ---- | :------------------------------------------------------------ | +| - | - | - | Your link here? [PRs](../wiki#contributions-welcome) welcome! | # Learning Includes videos, tutorials, demo projects, etc.: -| Date | Link | Description | -| :--------- | :---------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | -| - | - | Your link here? [PRs](../wiki#contributions-welcome) welcome! | -| - | [Official Slack channel](https://www.taoensso.com/telemere/slack) | For questions, support, etc. | -| - | [GitHub issues](https://github.com/taoensso/telemere/issues) | For questions, support, bug reports, PRs, etc. | -| 2024-06-12 | [YouTube](https://www.youtube.com/watch?v=uyApiNg6h7Y) | [Los Angeles Clojure Users Group](https://www.meetup.com/los-angeles-clojure-users-group/) collaborative learning session (107 mins) | -| 2024-04-18 | [YouTube](https://www.youtube.com/watch?v=-L9irDG8ysM) | Official Telemere announcement demo (24 mins) | +| Date | Link | Type | Description | +| :--------- | :---------------------------------------------------------------- | ------- | :----------------------------------------------------------------------------------------------------------------------------------- | +| - | - | - | Your link here? [PRs](../wiki#contributions-welcome) welcome! | +| - | [Official Slack channel](https://www.taoensso.com/telemere/slack) | Support | For questions, support, etc. | +| - | [GitHub issues](https://github.com/taoensso/telemere/issues) | Support | For questions, support, bug reports, PRs, etc. | +| 2024-06-12 | [YouTube](https://www.youtube.com/watch?v=uyApiNg6h7Y) | | [Los Angeles Clojure Users Group](https://www.meetup.com/los-angeles-clojure-users-group/) collaborative learning session (107 mins) | +| 2024-04-18 | [YouTube](https://www.youtube.com/watch?v=-L9irDG8ysM) | Demo | Official Telemere announcement demo (24 mins) |