feat: enhance documentation and add new features for Seq logger integration

Author: amigin

README.md

@@ -1,90 +1,77 @@
-## Usage of my_logger
+# my-logger
 
+A logger for Rust applications. Every record is printed to the console and handed to the plugged consumers. The Seq logger is such a consumer: it sends the records to [Seq](https://datalust.co/seq) or to my-logger-server.
 
-### How to use it in your application
-
-
-Plug it
+## Plug it
 
 ```toml
 [dependencies]
-my-logger = { tag = "max_version", git = "https://github.com/MyJetTools/my-logger.git" }
+my-logger = { tag = "x.x.x", git = "https://github.com/MyJetTools/my-logger.git" }
 ```
 
+`tag` is the latest of [the tags](https://github.com/MyJetTools/my-logger/tags).
 
-Put one of these lines at any place in your code
-```rust
-
-// writing information line
-my_logger::LOGGER.write_info("process_name", 
-  "message", 
-  LogEventCtx::new()
-    .add("field1","value1")
-    .add("field2","value2")
-    .add("field3","value3")
-);
-
-// writing warning line
-my_logger::LOGGER.write_warning("process_name",
-  "message",
-  LogEventCtx::new()
-    .add("field1","value1")
-    .add("field2","value2")
-    .add("field3","value3")
-);
+Write a record at any place of the code:
 
-// writing error line
-my_logger::LOGGER.write_error("process_name",
-  "message",
-  LogEventCtx::new()
-    .add("field1","value1")
-    .add("field2","value2")
-    .add("field3","value3")
+```rust
+use my_logger::LogEventCtx;
+
+my_logger::LOGGER.write_info(
+    "process_name",
+    "message",
+    LogEventCtx::new()
+        .add("field1", "value1")
+        .add("field2", "value2"),
 );
+```
 
-// writing fatal error line
-my_logger::LOGGER.write_fatal_error("process_name",
-  "message",
-  LogEventCtx::new()
-    .add("field1","value1")
-    .add("field2","value2")
-    .add("field3","value3")
-);
+## Plug the Seq logger
 
-// writing fatal debug error line
-my_logger::LOGGER.write_fatal_debug("process_name",
-  "message",
-  LogEventCtx::new()
-    .add("field1","value1")
-    .add("field2","value2")
-    .add("field3","value3")
-);
+To send the records to Seq or to my-logger-server, turn the `my-seq-logger` feature on:
 
+```toml
+[dependencies]
+my-logger = { tag = "x.x.x", git = "https://github.com/MyJetTools/my-logger.git", features = [
+    "my-seq-logger",
+] }
+async-trait = "*"
+tokio = { version = "*", features = ["full"] }
 ```
 
-### How to configure
-Some context values can be pre-populated by adding the line in the **fn main()**
+Give it the connection string and enable it once, at the start of the application:
+
 ```rust
-#[tokio::main]
-async fn main() {
-   my_logger::LOGGER.populate_params("key","value");
-   my_logger::LOGGER.populate_params("key2","value2");   
+use std::sync::Arc;
+
+use my_logger::my_seq_logger::{SeqLogger, SeqSettings};
+
+pub struct SettingsReader;
+
+#[async_trait::async_trait]
+impl SeqSettings for SettingsReader {
+    async fn get_conn_string(&self) -> String {
+        "url=http://127.0.0.1:5341;apikey=my-api-key;product=my-product".to_string()
+    }
 }
-```
-To configure application name and version method can be used
-```rust
+
 #[tokio::main]
 async fn main() {
-   my_logger::LOGGER.populate_app_and_version(env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
+    my_logger::LOGGER.populate_app_and_version(env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
+
+    SeqLogger::enable_from_connection_string(Arc::new(SettingsReader)).await;
 }
 ```
 
-# my-seq-logger
-Seq Logger
-
-Please Use wiki to read documentation
-https://github.com/MyJetTools/my-seq-logger/wiki
+A service built on service-sdk needs none of this: `ServiceContext::new` makes both calls itself and takes the connection string from `seq_conn_string` of the settings.
 
+## Features
 
-### 0.2.1
-* Settings now are read each fail case
+| Feature | In short |
+|---|---|
+| [Levels, context and macros](docs/writing-logs.md) | `write_info`, `write_warning`, `write_error`, `write_fatal_error` and `write_debug`, each with a context of keys and values; the `write_log_*!` macros. |
+| [Parameters of every record](docs/populated-params.md) | `Application`, `Version`, `EnvInfo` and the ones of your own, added to each record which is sent. |
+| [Console and counters](docs/console-and-counters.md) | Every record is printed to the console and counted by its level. |
+| [Consumers](docs/consumers.md) | A destination of your own for the records. |
+| [Seq logger](docs/seq-logger.md) | Sends the records to Seq or to my-logger-server in the background and writes a panic as a fatal error. |
+| [Connection string](docs/seq-connection-string.md) | `url`, `apikey`, `product`, `timeout` and `queuesize` of the Seq logger, read again before every request. |
+| [Product scope](docs/seq-connection-string.md#product-scope) | `product=my-product` names the product scope of my-logger-server the records go to. |

docs/console-and-counters.md

@@ -0,0 +1,33 @@
+# Console and counters
+
+## Console
+
+Every record is printed to the console as soon as it is written, with or without consumers plugged:
+
+```
+2026-10-12T09:24:22.984955+00:00 Info
+Process: process_name
+Message: message
+Context: {"field1": "value1", "field2": "value2"}
+-------------------
+```
+
+- `Info`, `Warning` and `Debug` go to stdout, `Error` and `FatalError` go to stderr.
+- The `Context` line is there when the record has a context.
+- The [parameters of every record](populated-params.md) are not printed.
+
+## Counters
+
+The records are counted by their level from the start of the application:
+
+```rust
+let errors = my_logger::LOGGER.get_errors_amount();
+```
+
+| Method | Counts |
+|---|---|
+| `get_infos_amount()` | `Info` |
+| `get_warnings_amount()` | `Warning` |
+| `get_errors_amount()` | `Error` |
+| `get_fatal_errors_amount()` | `FatalError` |
+| `get_debugs_amount()` | `Debug` |

docs/consumers.md

@@ -0,0 +1,33 @@
+# Consumers
+
+A consumer is a destination of the records. Every record written after a consumer is plugged is handed to it; any number of consumers can be plugged. The [Seq logger](seq-logger.md) is a consumer.
+
+```rust
+use std::sync::Arc;
+
+use my_logger::{MyLogEvent, MyLoggerConsumer};
+
+pub struct MyConsumer;
+
+impl MyLoggerConsumer for MyConsumer {
+    fn write_log(&self, log_event: Arc<MyLogEvent>) {
+        // put the record into a queue of your own
+    }
+}
+
+my_logger::LOGGER.plug_consumer(Arc::new(MyConsumer));
+```
+
+`write_log` is called on the thread which writes the record, before the write returns. It must not block and has no Tokio runtime to rely on: put the record into a queue and do the work in the background.
+
+## MyLogEvent
+
+| Field | |
+|---|---|
+| `dt` | When the record is written. |
+| `level` | `Info`, `Warning`, `Error`, `FatalError` or `Debug`. |
+| `process` | The process of the record. |
+| `message` | The message of the record. |
+| `context` | The keys and values of the record: `None` when there are none. |
+
+The [parameters of every record](populated-params.md) are not a part of the event: a consumer takes them with `my_logger::LOGGER.get_populated_params()`.

docs/populated-params.md

@@ -0,0 +1,20 @@
+# Parameters of every record
+
+Parameters populated once are added to every record the [Seq logger](seq-logger.md) sends.
+
+```rust
+my_logger::LOGGER.populate_app_and_version(env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"));
+my_logger::LOGGER.populate_params("Region", "eu");
+```
+
+| Call | Adds |
+|---|---|
+| `populate_app_and_version(name, version)` | `Application` and `Version`. With the `ENV_INFO` environment variable set - `EnvInfo` with its value as well. |
+| `populate_params(key, value)` | A parameter of your own. The key is a `&'static str`, the value is a `&'static str` or a `String`. |
+
+- Populate them at the start of the application: a record sent before that goes without them.
+- Every call adds. A key populated twice is sent twice, so each of them is called once.
+- They are not printed to the console.
+- `my_logger::LOGGER.get_populated_params()` returns what is populated.
+
+`Application` is also what my-logger-server finds the product scope of a record by, when the connection string names no [product](seq-connection-string.md#product-scope).

docs/seq-connection-string.md

@@ -0,0 +1,54 @@
+# Connection string
+
+What the [Seq logger](seq-logger.md) is set up with. The application gives it through `SeqSettings::get_conn_string` - see [readme](../README.md#plug-the-seq-logger).
+
+```
+url=http://127.0.0.1:5341;apikey=my-api-key;product=my-product;timeout=10
+```
+
+`key=value` pairs separated by `;`. The keys are in lower case, with no spaces around them and no `;` after the last pair. Only the first `=` of a pair separates, so a value may have `=` in it - but not `;`.
+
+| Key | | Default | |
+|---|---|---|---|
+| `url` | required | | Where the records are sent: `{url}/api/events/raw`. An `https://` one needs [TLS turned on](seq-logger.md#https). |
+| `apikey` | optional | none | Sent as the `X-Seq-ApiKey` header. |
+| `product` | optional | none | The product scope of the records - see [Product scope](#product-scope). |
+| `timeout` | optional | `10` | Seconds a request waits for the response. |
+| `queuesize` | optional | no limit | How many records wait to be sent; a record over that is dropped. |
+| `flushlogschunk` | optional | `50` | A number; read and not used. |
+| `flushdelay` | optional | `1` | A number; read and not used. |
+
+## Product scope
+
+my-logger-server keeps and searches the records by product scope. `product` names the scope of everything the application writes: it is sent as the `scope` header with every request.
+
+```
+url=http://my-logger-server:8000;product=my-product
+```
+
+- A product is `a-z`, `0-9`, `-` and `_`, 64 characters at most. Spaces around it are cut off and upper case is turned to lower case: `product=My-Product` is sent as `my-product`.
+- Anything else - an empty value as well - [panics](#a-string-which-can-not-be-parsed). The server ignores a scope it can not use without a word, so the logger does not let one through.
+- Without `product` no header is sent. The server then finds the scope by the `Application` of a record, and takes its default scope when none matches.
+- The server does not ask for a scope to be set up beforehand: a product with a typo in it becomes a scope of its own.
+- Seq itself has no product scopes and takes no notice of the header.
+
+## Changes on the fly
+
+The string is read again before every request, so a change needs no restart:
+
+- `url`, `apikey`, `product` and `timeout` apply from the next request.
+- `queuesize` is taken at the start only.
+
+## A string which can not be parsed
+
+| What is wrong | What happens |
+|---|---|
+| No `url` | Not a panic: `Can not parse Logs settings` is printed to stderr and the string is read again every 5 seconds. Nothing is sent until then. |
+| An unknown key - `Url`, `ApiKey` in upper case as well | panic |
+| A pair without `=` - a `;` after the last pair as well | panic |
+| `timeout`, `queuesize`, `flushlogschunk` or `flushdelay` which is not a number | panic |
+| A `product` which can not name a scope | panic |
+
+At the start a panic stops the application, with the reason in stderr.
+
+Do not let the string turn into one which panics while the application is running: nothing is sent and the records written meanwhile are lost until it is fixed.

docs/seq-logger.md

@@ -0,0 +1,69 @@
+# Seq logger
+
+A [consumer](consumers.md) which sends the records to [Seq](https://datalust.co/seq) or to my-logger-server. It comes with the `my-seq-logger` feature of `my-logger` as `my_logger::my_seq_logger`. How to plug it: [readme](../README.md#plug-the-seq-logger). What it is set up with: [connection string](seq-connection-string.md).
+
+## Start
+
+`SeqLogger::enable_from_connection_string(settings).await` is called once, at the start of the application, inside a Tokio runtime. It:
+
+1. Sets the panic hook - see [Panics](#panics).
+2. Reads the connection string. Without `url` in it the call does not return: it prints `Can not parse Logs settings` and reads the string again every 5 seconds. A string which can not be parsed otherwise [panics](seq-connection-string.md#a-string-which-can-not-be-parsed).
+3. Starts the task which sends the records. It runs on the runtime the call is awaited on and sends for as long as that runtime lives.
+4. Plugs itself into `my_logger::LOGGER` and prints `Seq Logs writer is started`.
+
+A second call plugs a second sender, and every record is sent twice.
+
+Writing a record needs no runtime: it is put into a queue in memory, from any thread.
+
+## How the records are sent
+
+- The task takes everything there is in the queue and sends it as one request. What is written while a request is on its way goes with the next one.
+- A request carries up to 2 MB of records; the rest goes in the requests after it.
+- With `queuesize` in the connection string the queue holds that many records, and a record written into a full queue is dropped. Without it the queue has no limit.
+
+The request is `POST {url}/api/events/raw?clef`:
+
+| Header | |
+|---|---|
+| `Content-Type` | `application/vnd.serilog.clef` |
+| `X-Seq-ApiKey` | `apikey` of the connection string, when it is there. |
+| `scope` | `product` of the connection string, when it is there - see [Product scope](seq-connection-string.md#product-scope). |
+
+The body is a record per line, the lines separated by `\r\n`:
+
+```json
+{"@l":"Info","@t":"2026-10-12T09:24:22.984955","Process":"process_name","@m":"message","Application":"my-app","Version":"0.1.0","orderId":15,"comment":"hello"}
+```
+
+| Field | |
+|---|---|
+| `@l` | `Info`, `Warning`, `Error`, `Fatal` or `Debug`. |
+| `@t` | When the record is written, UTC. |
+| `Process` | The process of the record. |
+| `@m` | The message of the record. |
+| the rest | The [parameters of every record](populated-params.md), then the context of the record. A context value which reads as a number, `true`, `false` or `null` is written as such, any other one as a string. |
+
+## When a request fails
+
+A request is tried 4 times, then its records are dropped:
+
+- **No response** - the server is not reachable, or does not answer within `timeout`. Each attempt prints `Attempt: N Error while uploading logs to seq` to stderr, the attempts are a second apart.
+- **A status other than 200-209.** The attempts follow one another with no pause and print nothing.
+
+## Panics
+
+`enable_from_connection_string` replaces the panic hook of the process. A panic anywhere in the application is written as a `FatalError` record with the process `Panic Handler`, the panic message as the message, and `Location` and `PanicInfo` in the context.
+
+The record is printed to the console at once and sent in the background as any other one, so a panic which ends the process may not get to the server.
+
+## HTTPS
+
+An `https://` url needs a TLS provider feature of [flurl](https://github.com/MyJetTools/fl-url) - `with-ring-tls` or `with-rust-tls` - turned on by the application; service-sdk has the features of the same names. Without one every request fails with `FlUrl does not support https` in stderr and the records are dropped.
+
+## Environment variables
+
+| Variable | |
+|---|---|
+| `SEQ_DEBUG` | Set to anything - every request and the response to it are printed to the console. |
+| `SEQ_COMPRESS` | Set to anything - a request over 1 MB is sent gzipped. |
+| `ENV_INFO` | Sent as `EnvInfo` with every record - see [Parameters of every record](populated-params.md). |