luciano/telemere
1
0
Fork 0
mirror of https://github.com/taoensso/telemere.git synced 2026-02-13 14:55:17 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

[doc] Misc improvements

Browse source
This commit is contained in:
Peter Taoussanis 2024-08-21 23:53:24 +02:00
parent 331bea7a51
commit a77021e436
6 changed files with 44 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
README.md
View file

@ -177,8 +177,8 @@ Detailed help is available without leaving your IDE:
### Included handlers ### Included handlers
> See ✅ links for **features and usage** See ✅ links below for **features and usage**,
> See 👍 links to **vote on handler** for future addition See 👍 links below to **vote on future handlers**:
| Target (↓) | Clj | Cljs | | Target (↓) | Clj | Cljs |
| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: | | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: |

2
resources/signal-docstrings/signal-options.txt
View file

@ -30,8 +30,6 @@ Signal options (shared by all signal creators):
handler output, so a great way to provide custom data/opts for use handler output, so a great way to provide custom data/opts for use
(only) by custom middleware/handlers. (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! If anything is unclear, please ping me (@ptaoussanis) so that I can improve these docs!
[1] `java.time.Instant` or `js/Date` [1] `java.time.Instant` or `js/Date`

8
src/taoensso/telemere/utils.cljc
View file

@ -645,6 +645,14 @@
(require '[jsonista.core :as jsonista]) (require '[jsonista.core :as jsonista])
(pr-signal-fn {:pr-fn jsonista/write-value-as-string ...}) (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." See also `format-signal-fn` for human-readable output."
([] (pr-signal-fn nil)) ([] (pr-signal-fn nil))
([{:keys [pr-fn, incl-kvs? incl-nils? incl-newline? incl-keys] :as opts ([{:keys [pr-fn, incl-kvs? incl-nils? incl-newline? incl-keys] :as opts

42
wiki/4-Handlers.md
View file

@ -1,32 +1,32 @@
Signal handlers process created signals to **do something with them** (analyse them, write them to console/file/queue/db, etc.). 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. You can also easily [write your own handlers](#writing-handlers) for any output or integration you need.
# Included handlers # Included handlers
> See ✅ links for **features and usage** See ✅ links below for **features and usage**,
> See 👍 links to **vote on handler** for future addition See 👍 links below to **vote on future handlers**:
| Target (↓) | Clj | Cljs | | Target (↓) | Clj | Cljs |
| :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: | | :--------------------------------------------- | :-----------------------------------------------------------------------------------------------------------------: | :-----------------------------------------------------------------------------------------------: |
| [Apache Kafka](https://kafka.apache.org/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - | | [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) | - | | [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 | [✅](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) | | 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) | | [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) | - | | 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) | - | | [Graylog](https://graylog.org/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - |
| [Jaeger](https://www.jaegertracing.io/) | [👍](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) | - | | [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) | | [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) | - | | [Redis](https://redis.io/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - |
| SQL | [👍](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) | - | | [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) | - | | 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) | - | | 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) | - | | [Zipkin](https://zipkin.io/) | [👍](https://github.com/taoensso/roadmap/issues/12) | - |
# Configuring handlers # Configuring handlers

2
wiki/5-Migrating.md
View file

@ -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. 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). If not, you may need to [write something yourself](./4-Handlers#writing-handlers).

24
wiki/8-Community.md
View file

@ -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) 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 | | Date | Link | Type | Description |
| :--- | :--- | :------------------------------------------------------------ | | :--- | :--- | ---- | :------------------------------------------------------------ |
| - | - | Your link here? [PRs](../wiki#contributions-welcome) welcome! | | - | - | - | Your link here? [PRs](../wiki#contributions-welcome) welcome! |
# Learning # Learning
Includes videos, tutorials, demo projects, etc.: Includes videos, tutorials, demo projects, etc.:
| Date | Link | Description | | Date | Link | Type | Description |
| :--------- | :---------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------- | | :--------- | :---------------------------------------------------------------- | ------- | :----------------------------------------------------------------------------------------------------------------------------------- |
| - | - | Your link here? [PRs](../wiki#contributions-welcome) welcome! | | - | - | - | Your link here? [PRs](../wiki#contributions-welcome) welcome! |
| - | [Official Slack channel](https://www.taoensso.com/telemere/slack) | For questions, support, etc. | | - | [Official Slack channel](https://www.taoensso.com/telemere/slack) | Support | For questions, support, etc. |
| - | [GitHub issues](https://github.com/taoensso/telemere/issues) | For questions, support, bug reports, PRs, 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-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) | | 2024-04-18 | [YouTube](https://www.youtube.com/watch?v=-L9irDG8ysM) | Demo | Official Telemere announcement demo (24 mins) |