Add timezones support and update readme

Author: Bardin08

README.md

@@ -1,68 +1,90 @@
 # X.Serilog.Sinks.Telegram
-X.Serilog.Sinks.Telegram is a Serilog sink that write events to [Telegram](https://telegram.org/) channel or chat.
 
-## Current Statuses
 [![Build status](https://ci.appveyor.com/api/projects/status/n4uj9qfuywrkdrhb/branch/main?svg=true)](https://ci.appveyor.com/project/Bardin08/x-serilog-sinks-telegram/branch/main)
-[![NuGet Badge](https://buildstats.info/nuget/X.Serilog.Sinks.Telegram)](https://www.nuget.org/packages/X.Serilog.Sinks.Telegram/)
 
-## Installation
+[![NuGet](https://img.shields.io/nuget/v/X.Serilog.Sinks.Telegram)](https://www.nuget.org/packages/X.Serilog.Sinks.Telegram)
+[![NuGet Downloads](https://img.shields.io/nuget/dt/X.Serilog.Sinks.Telegram)](https://www.nuget.org/packages/X.Serilog.Sinks.Telegram)
 
-The package can be installed by NuGet manually or within one of the listed commands.
+## Table of Contents
 
-```ps
-PM> Install-Package X.Serilog.Sinks.Telegram -Version 1.0.0
-```
+- [X.Serilog.Sinks.Telegram](#xserilogsinkstelegram)
+  - [Introduction](#introduction)
+  - [Features](#features)
+  - [Getting Started](#getting-started)
+  - [Examples](#examples)
+  - [Contributing](#contributing)
+  - [License](#license)
 
-```sh
-$ dotnet add package X.Serilog.Sinks.Telegram --version 1.0.0
-```
+## Introduction
 
-## Documentation
-For more comprehensive and detailed documentation, please visit our [GitHub Wiki](https://github.com/Bardin08/X.Serilog.Sinks.Telegram/wiki/Overview) pages. Here, you'll find in-depth information about configuration options, usage examples, troubleshooting guides, and more to help you effectively integrate and utilize the X.Serilog.Sinks.Telegram sink in your projects.
+X.Serilog.Sinks.Telegram is an open-source Serilog sink that allows you to send log events to Telegram. It's a convenient way to integrate Telegram as a logging output, enabling you to receive important log information directly in your chat.
 
+## Features
 
-## Usage
+- **Real-time Logging**: The sink offers the ability to send log events to a Telegram channel in real-time, ensuring that you can stay up-to-date with your application's behavior and any issues as they arise.
 
-Check [docs](./docs) folder to find more interesting things that can be useful.
+- **Customizable Formatting**: You have the flexibility to configure the format of log messages sent to the Telegram channel, allowing you to tailor them to your preferences and specific requirements.
 
-### Code-Based Configuration
-The simplest configuration require [Telegram bot token](https://core.telegram.org/bots#generating-an-authentication-token) and [channel ID](https://community.jamaicans.dev/t/get-the-telegram-channel-id/427). Check the enclosed links to understand how to receive them.
+- **Filtering**: The sink supports filtering log events before they are dispatched to the Telegram channel, ensuring that only pertinent information is shared.
 
-```cs
-Log.Logger = new LoggerConfiguration()
-    .WriteTo.Telegram(
-        token: "0000000000:0000_000000000000000000000000000000",
-        chatId: "-0000000000000")
-    .CreateLogger();
-```
+- **Asynchronous Sending**: Log events are sent asynchronously to the Telegram channel, minimizing any potential impact on your application's performance.
 
-For more complex configuration examples please check the related wiki page or browse the examples folder.
+- **Easy Configuration**: Configuring the sink to work with your Telegram channel is straightforward, and you can find comprehensive information in the [Configuration Wiki](https://github.com/Bardin08/X.Serilog.Sinks.Telegram/wiki/Configuration).
 
-Sink also can be configured by JSON configuration file.
-### JSON-Based Configuration
-#### *Microsoft.Extensions.Configuration* package required
-Keys and values are case-insensitive.
+## Getting Started
+
+To begin using the X.Serilog.Sinks.Telegram sink, follow these steps:
+
+1. **Install the Package**: You can install the sink package from NuGet using the following command:
+```shell
+dotnet add package X.Serilog.Sinks.Telegram
+```
 
-```json
-"Serilog": {
-  "Using": [
-    "X.Serilog.Sinks.Telegram"
-  ],
-  "WriteTo": [
+2. **Configure the Sink**: In your application's configuration, set up the Telegram sink with the appropriate settings. Here's an example configuration in C#:
+
+```c#
+var logger = new LoggerConfiguration()
+    .Telegram(config =>
     {
-      "Name": "Telegram",
-      "Args": {
-        "Token": "0000000000:0000_000000000000000000000000000000",
-        "ChatId": "-0000000000000",
-      }
-    }
-  ],
-}
+        config.Token = "your_telegram_bot_token";
+        config.ChatId = "your_chat_id";
+        config.BatchPostingLimit = 10;
+        config.Mode = LoggingMode.Logs;
+        config.FormatterConfiguration = new FormatterConfiguration
+        {
+            UseEmoji = true,
+            ReadableApplicationName = "MyTestApp",
+            IncludeException = true,
+            IncludeProperties = true
+        };
+        config.BatchEmittingRulesConfiguration = new BatchEmittingRulesConfiguration
+        {
+            // Batch Emitting rules configuration here...
+        };
+        config.LogFiltersConfiguration = new LogsFiltersConfiguration
+        {
+            ApplyLogFilters = true,
+            FiltersOperator = LogFiltersOperator.Or,
+            Filters = new List<IFilter> {
+                // Your filters here...
+            }
+        };
+    }, null, LogEventLevel.Debug)
+    .CreateLogger();
 ```
 
-## Roadmap
-Project's roadmap described at [Roadmap](./docs/roadmap.md).
+3. **Start Logging**: Once the sink is configured, you can start logging using Serilog as you normally would. Log events will be sent to your Telegram channel.
+
+For more detailed configuration options, please refer to the [Configuration Wiki](https://github.com/Bardin08/X.Serilog.Sinks.Telegram/wiki/Configuration).
+
+## Examples
+
+This repository includes a number of example projects that demonstrate how to use X.Serilog.Sinks.Telegram in various scenarios. These examples can be very helpful if you're just getting started or looking to use a specific feature.
+
+You can find the examples in the following location: [X.Serilog.Sinks.Telegram Examples](https://github.com/Bardin08/X.Serilog.Sinks.Telegram/tree/main/examples)
 
 ## Contributing
 Feel free to add any improvements you want via pull requests. All pull requests must be linked to an issue.
 
+## License
+This project is licensed under the [MIT License](https://en.wikipedia.org/wiki/MIT_License)https://en.wikipedia.org/wiki/MIT_License.

examples/WebApp/Program.cs

@@ -39,8 +39,9 @@
         {
             UseEmoji = true,
             ReadableApplicationName = "WebApp Example",
-            IncludeException = true,
-            IncludeProperties = true
+            IncludeException = false,
+            IncludeProperties = false,
+            TimeZone = TimeZoneInfo.Utc
         };
         config.BatchPostingLimit = 10;
         config.Mode = LoggingMode.Logs;

src/X.Serilog.Sinks.Telegram/Configuration/FormatterConfiguration.cs

@@ -6,22 +6,52 @@
 public class FormatterConfiguration
 {
     /// <summary>
-    /// Gets a value indicating whether to use emojis in the output.
+    /// Determines whether to replace the log level text definition with emojis.
     /// </summary>
+    ///
+    /// <value>
+    /// A boolean representing the configuration. If true, emojis are used in place of log levels.
+    /// </value>
     public bool UseEmoji { get; init; }
 
     /// <summary>
-    /// Gets the user-friendly name of the application.
+    /// Provides a readable name for the application. 
     /// </summary>
+    ///
+    /// <value>
+    /// The application's name. Useful when different applications are sending logs to the same channel. If null, this property will be ignored.
+    /// </value>
     public string? ReadableApplicationName { get; init; }
 
     /// <summary>
-    /// Gets a value indicating whether to include exception details in the output.
+    /// Determines the handling of exceptions in log messages.
     /// </summary>
+    ///
+    /// <value>
+    /// A boolean representing the configuration. If true, and an exception is not null, the exception is included in the log message as a serialized JSON. This setting is only applicable when TelegramSinkConfiguration.Mode is LoggingMode.Logs.
+    /// </value>
     public bool IncludeException { get; init; }
 
     /// <summary>
-    /// Gets a value indicating whether to include property details in the output.
+    /// Specifies whether to include the log's parameters dictionary in log messages.
     /// </summary>
+    ///
+    /// <value>
+    /// A boolean representing the configuration. If true, the log's parameters dictionary is included in the log message as a JSON. This setting is only applicable when TelegramSinkConfiguration.Mode is LoggingMode.Logs.
+    /// </value>
     public bool IncludeProperties { get; init; }
+
+    /// <summary>
+    /// Sets or gets the time zone used by this sink for log timestamps. 
+    /// </summary>
+    ///
+    /// <value>
+    /// The time zone information. If null, server time will be used.
+    /// </value>
+    /// 
+    /// <remarks>
+    /// This property is specifically for this logger sink. It does not affect other sinks utilized by Serilog.
+    /// Please note that each sink might handle log timestamps based on its individual configuration. To ensure the desired time zone is applied to your logs, you need to set this property for each necessary sink.
+    /// </remarks>
+    public TimeZoneInfo? TimeZone { get; init; }
 }

src/X.Serilog.Sinks.Telegram/Formatters/DefaultAggregatedNotificationsFormatter.cs

@@ -15,15 +15,21 @@ public override List<string> Format(
 
     private List<string> DefaultFormatter(IEnumerable<LogEntry> logEntries, FormatterConfiguration config)
     {
-        var entries = logEntries as LogEntry[] ?? logEntries.ToArray();
-
         var sb = new StringBuilder();
-        logEntries = entries.OrderBy(x => x.UtcTimeStamp);
 
-        var beginTs = logEntries.First().UtcTimeStamp;
-        var endTs = logEntries.Last().UtcTimeStamp;
+        logEntries = logEntries.OrderBy(x => x.UtcTimeStamp).ToList();
+
+        var batchBeginTimestamp = logEntries.First().UtcTimeStamp;
+        var batchEndTimestamp = logEntries.Last().UtcTimeStamp;
+
+        if (config.TimeZone is not null)
+        {
+            batchBeginTimestamp = TimeZoneInfo.ConvertTime(batchBeginTimestamp, config.TimeZone);
+            batchEndTimestamp = TimeZoneInfo.ConvertTime(batchBeginTimestamp, config.TimeZone);
+        }
 
-        sb.Append("<em>[").Append($"{beginTs:G}").Append('—').Append($"{endTs:G}").Append("]</em>").Append(' ')
+        sb.Append("<em>[").Append($"{batchBeginTimestamp:G}").Append('—').Append($"{batchEndTimestamp:G}")
+            .Append("]</em>").Append(' ')
             .Append(config.ReadableApplicationName)
             .AppendLine()
             .AppendLine();

src/X.Serilog.Sinks.Telegram/Formatters/DefaultLogFormatter.cs

@@ -54,7 +54,13 @@ private string FormatMessageInternal(LogEntry logEntry, FormatterConfiguration c
 
         var sb = new StringBuilder();
 
-        sb.Append(level).Append(' ').Append("<em>[").Append($"{logEntry.UtcTimeStamp:G}").Append("]</em>").Append(' ')
+        var timestamp = logEntry.UtcTimeStamp;
+        if (config.TimeZone is not null)
+        {
+            timestamp = TimeZoneInfo.ConvertTime(timestamp, config.TimeZone);
+        }
+
+        sb.Append(level).Append(' ').Append("<em>[").Append($"{timestamp:G}").Append("]</em>").Append(' ')
             .Append(config.ReadableApplicationName);
 
         sb.AppendLine();