bardin08 / x.serilog.sinks.telegram

This is a sink for the Serilog logger that allows you to log just to your Telegram. For you're convenience this sink can format logs as a summary of events that happened during a period

X.Serilog.Sinks.Telegram

Table of Contents

• X.Serilog.Sinks.Telegram
  • Introduction
  • Features
  • Getting Started
  • Examples
  • Contributing
  • License

Introduction

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

• 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.

• Customizable Formatting: You can configure the format of log messages sent to the Telegram channel, allowing you to tailor them to your preferences and specific requirements.

• Filtering: The sink supports filtering log events before they are dispatched to the Telegram channel, ensuring that only pertinent information is shared.

• Asynchronous Sending: Log events are sent asynchronously to the Telegram channel, minimizing potential impact on your application's performance.

• Easy Configuration: Configuring the sink to work with your Telegram channel is straightforward, and you can find comprehensive information in the Configuration Wiki.

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:

dotnet add package X.Serilog.Sinks.Telegram

2. Configure the Sink: Set up the Telegram sink with the appropriate settings in your application's configuration. Here's an example configuration in C#:

Log.Logger = new LoggerConfiguration()
    .WriteTo.TelegramCore(
        token: botToken,
        chatId: loggingChatId,
        logLevel: LogEventLevel.Verbose)
    .WriteTo.Console()
    .CreateLogger();

3. Start Logging: Once the sink is configured, you can log in using Serilog as usual. Log events will be sent to your Telegram channel.

For more detailed configuration options, please refer to the Configuration Wiki.

Examples

This repository includes several example projects that demonstrate how to use X.Serilog.Sinks.Telegram in various scenarios. These examples can be helpful if you're starting or looking to use a specific feature.

You can find the examples in the following location: X.Serilog.Sinks.Telegram 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 Licensehttps://en.wikipedia.org/wiki/MIT_License.

x.serilog.sinks.telegram's Issues

Time is always written in the UTC format

Describe the bug
There's no way to configure how to configure the message timestamp format. By default, it always use UTC based format.

To Reproduce
No specific actions required

Expected behavior
Timestamp formating can be configured

Screenshots

Add tests for existing and new code

Need fix Wiki

Describe the bug
On page https://github.com/Bardin08/X.Serilog.Sinks.Telegram/wiki/Configuration we see this code example:

var logger = new LoggerConfiguration()
    .Telegram(config =>
    {
        config.Token = "your_telegram_bot_token";
      ...

but it didn't work

instead need:

                logConfig = new LoggerConfiguration()
                    .WriteTo.Telegram(config =>
                    {
                        config.Token = "your_telegram_bot_token";
                      ...

Log entry publish filters

As a user, I want to have custom filters for defining if log entry has to be fixed

Improve documentation

Is your feature request related to a problem? Please describe.
No.

Describe the solution you'd like
Add information about log filters and issues with configuration in v3.
Also, review documentation in general and improve it.

Describe alternatives you've considered
No.

Additional context
No.

Add examples

Simplify internal namespaces

Is your feature request related to a problem? Please describe
Internal namespaces structure is overloaded with useless layers

Describe the solution you'd like
Remove useless layers

User-defined Event Highlights for Special Notifications

Is your feature request related to a problem?

Yes, it takes time to quickly identify and react to critical issues within a flood of log messages. Users need a way to notice essential log events that require urgent attention immediately. I'm always frustrated when critical logs get buried under less important ones, delaying response times.

Describe the solution you'd like

I want a feature that allows users to define specific log events or keywords as "highlights." When a log matches these definitions, it should trigger special notifications distinct from regular log messages. This could involve different formatting, colors, or the inclusion of emojis to denote urgency. The system should allow for configurable alert levels (e.g., warning, critical) with corresponding notification styles to identify an event's severity at a glance quickly.

Describe alternatives you've considered

Another alternative is relying on external monitoring services to filter and alert specific log events, which adds dependencies and potentially increases the notification delay.

Additional context

This enhancement aims to make the Telegram logger a tool for passive monitoring and an active participant in the application's incident management process. By allowing users to customize what constitutes an essential event, the logger becomes much more versatile and valuable across different use cases and scenarios. Integrating this feature with existing functionalities like asynchronous sending and customizable formatting will ensure a cohesive user experience.

Use custom logger to write logs

Describe the solution you'd like
Use the ILogger interface instead of the concrete logger in all internals and let it pass the required logger throw configuration.

Additional context
An opportunity to have a way to pass at any logger and use logging to the telegram.

When not set BatchEmittingRulesConfiguration, got ThrowArgumentNullException

Steps to reproduce the behavior:

1. Get configuration from Wiki example:

var logger = new LoggerConfiguration()
    .Telegram(config =>
    {
        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,
            TimeZone = TimeZoneInfo.Utc
        };
        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();

logger.Information("This is a test log message");

if section

  config.BatchEmittingRulesConfiguration = new BatchEmittingRulesConfiguration
        {
            // Batch Emitting rules configuration here...
        };

is empty or commented, we got error:

   at System.Linq.ThrowHelper.ThrowArgumentNullException(ExceptionArgument argument)
   at System.Linq.Enumerable.Where[TSource](IEnumerable`1 source, Func`2 predicate)
   at X.Serilog.Sinks.Telegram.Configuration.BatchEmittingRulesConfiguration.get_BatchProcessingExecutionHooks()
   at X.Serilog.Sinks.Telegram.Batch.BatchCycleManager..ctor(BatchEmittingRulesConfiguration configuration)
   at X.Serilog.Sinks.Telegram.TelegramSink..ctor(ChannelWriter`1 channelWriter, ILogsQueueAccessor logsQueueAccessor, TelegramSinkConfiguration sinkConfiguration, IMessageFormatter messageFormatter)
   at X.Serilog.Sinks.Telegram.Extensions.LoggerConfigurationTelegramExtensions.Telegram(LoggerSinkConfiguration loggerConfiguration, Action`1 configureAction, IMessageFormatter messageFormatter, LogEventLevel restrictedToMinimumLevel)
   at xxx.Startup.ConfigureServices(IServiceCollection services) in

Expected behavior
Maybe need to update example or use "default" configuration of section BatchEmittingRulesConfiguration

Desktop (please complete the following information):

• OS: Windows 11
• .NET 8.0

Additional context
If I set this config (get from https://github.com/Bardin08/X.Serilog.Sinks.Telegram/wiki/Batch-Emitting-Rules)

                        config.BatchEmittingRulesConfiguration = new BatchEmittingRulesConfiguration()
                        {
                            RuleCheckPeriod = TimeSpan.FromSeconds(5),
                            BatchProcessingRules = new IRule[]
                            {
                                new BatchSizeRule(config.LogsAccessor, batchSize: 10),
                                new OncePerTimeRule(TimeSpan.FromSeconds(30))
                            }.ToImmutableList()
                        };

all works fine

Replace markdown formatting with an HTML one

Describe the solution you'd like
As C# exception's stack trace can contain some characters that are used at markdown formatting it can lead to a problem with displaying a message

Describe alternatives you've considered

1. Replace markdown with HTML
2. Encode markdown symbols

Batch posting rules works invalid if BatchPositingLimit and BatchPostingPeriod are combined

Describe the bug
If both BatchPositingLimit and BatchPostingPeriod are settled a butch of logs delivered only when batch filled (BatchPositingLimit condition).

To Reproduce

1. Set batch posting limit as 5
2. Set batch posting period as 1 min
3. Generate 4 log entries that have to be logged
4. See that batch is not sent
5. Generate one more log entry
6. See that batch sent

Expected behavior
Logs batch sent on any of conditions reached (BatchPositingLimit or BatchPostingPeriod)

Additional context

1. Issue occurs for versions 1.0.0

Workarounds
Use only one of rules which suites more

Implement New Logging Mode: 'Threads' for Grouped Log Management

Is your feature request related to a problem? Please describe.

Yes. The problem arises following a sequence of related log events within a Telegram channel. All logs are posted as separate messages, making tracking and analyzing logs about the same operational issue challenging.

Describe the solution you'd like

I want to introduce a new logging mode called 'Threads'. This mode would automatically group related logs into threads within a Telegram channel, utilizing the comments feature to link logs with similar identifiers. This approach would significantly improve the readability and manageability of logs, especially in complex debugging or incident resolution scenarios. Features of this mode should include:

• Automatic detection and grouping of logs based on configurable criteria (e.g., traceID, spanID).
• Posting related logs as comments under a primary log message to maintain their contextual relationship.
• Customizable settings to define what constitutes a "related" log, allowing teams to adapt the feature to their specific logging needs.

Describe alternatives you've considered

The alternative relies on external tools for log analysis, which adds complexity and dependency on third-party services.

Additional context

Implementing 'Threads' would address the current gap in efficiently managing and analyzing related log events directly within Telegram channels. This feature is especially crucial for monitoring and troubleshooting complex systems, where understanding the sequence and relationship between log events can significantly impact incident response times and effectiveness.

Set up CI/CD for the repo

1. Continuous Integration
   • SemVer version update
   • Build, test, and execute SonarCloud checks
2. Continuous Delivery
   • Push NuGet Package on new Release created, or manually for the existing tag (#32, #33)