Configuration

Documentation: Telegram Sink Configuration Settings

In the context of the Telegram Sink for logging, several configuration classes and enums are available. These classes provide a way to configure the sink according to specific needs.

Table of Contents

1. TelegramSinkConfiguration
2. LoggingMode
3. BatchEmittingRulesConfiguration
4. FormatterConfiguration
5. LogsFiltersConfiguration
6. LogQueryBuilder
7. TelegramSinkDefaults
8. Usage Examples

TelegramSinkConfiguration

This is the primary configuration class which contains settings required for the operation of the Telegram Sink.

Property	Type	Description
Token	string	Token for Telegram API access.
ChatId	string	Identifies the chat to which log messages will be posted.
BatchPostingLimit	int	The maximum number of events to post in a single batch.
Mode	LoggingMode	Sets the logging mode.
FormatterConfiguration	FormatterConfiguration	Configuration for formatting logs.
BatchEmittingRulesConfiguration	BatchEmittingRulesConfiguration	Configuration for rules on emitting batches.
LogFiltersConfiguration	LogsFiltersConfiguration	Configuration for filtering logs.

Configuration validating rules:

1. Token and ChatId are mandatory, not empty, null or whitespace.
2. BatchPostingLimit is equal to or greater than 0.
   Note: if it's 0, every log will be sent to the telegram if it passes filtering and log-level checks. Remember that it's better to avoid batchPostingLimit = 0 for performance reasons`.
3. FormatterConfiguration is not null.

LoggingMode

An enum that allows for the choice between two log representations.

A. Logs: Log messages will be published to the specified Telegram channel.
B. AggregatedNotifications: Messages will contain info about all notifications received during a batch period or batch limit.

BatchEmittingRulesConfiguration

Configuration class for managing batch-emitting rules.

Property	Type	Description
RuleCheckPeriod	TimeSpan	Check period for batch emit rules.
BatchProcessingRules	IImmutableList	The batch processing rules to be applied.

FormatterConfiguration

Settings for formatting log messages.

Property	Type	Description
UseEmoji	bool	Indicates whether to use emojis in the output.
ReadableApplicationName	string	User-friendly name of the application.
IncludeException	bool	Indicates whether to include exception details in the output.
IncludeProperties	bool	Indicates whether to include property details in the output.
TimeZone	TimeZoneInfo?	Indicates which time zone to use in the output timestamp. If null, server time will be used.

LogsFiltersConfiguration

Configuration class for applying log filters.

Property	Type	Description
ApplyLogFilters	bool	Indicates whether to apply log filters.
LogQueryBuilder	LogQueryBuilder	List of filters to be applied.

LogQueryBuilder

Fluent API-based filter builder. This allows for the configuration of log filtering based on the convenient API.

TelegramSinkDefaults

Contains the default configuration values for the Telegram Sink.

Usage Examples

You can configure Telegram sink using 2 methods. For quickstart, you can use the TelegramCore method. For advanced configuration, you can use the Telegram method.

For a quick start, you can use the TelegramCore method

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

Here is an example of how to configure the Telegram Sink using advanced configuration:

    Log.Logger = new LoggerConfiguration()
        .WriteTo.Telegram(config =>
        {
            config.Token = token;
            config.ChatId = tgChatId;

            config.Mode = LoggingMode.Logs;

            config.BatchPostingLimit = TelegramSinkDefaults.BatchPostingLimit;
            config.BatchEmittingRulesConfiguration = new BatchEmittingRulesConfiguration
            {
                RuleCheckPeriod = TimeSpan.FromSeconds(30), // Check batch emitting rules each 30 seconds
                BatchProcessingRules = new List<IRule>()
                {
                    new BatchSizeRule(config.LogsAccessor, 5), // emit batch when logs queue length
                                                              // equals or greater than 5
                    new OncePerTimeRule(TimeSpan.FromMinutes(5)) // emit batch each 5 minutes
                }.ToImmutableList()
            };
            config.FormatterConfiguration = new FormatterConfiguration
            {
                UseEmoji = true,
                ReadableApplicationName = "MyTestApp",
                IncludeException = true,
                IncludeProperties = true,
                TimeZone = TimeZoneInfo.Utc
            };
            config.LogFiltersConfiguration = new LogsFiltersConfiguration
            {
                ApplyLogFilters = false,
            };
        }, null!, LogEventLevel.Debug)
        .CreateLogger();

This code configures the TelegramSinkConfiguration instance through a delegate and an extension method. This provides a more fluent API and makes the configuration step more transparent and straightforward. You would add further sinks and then create the logger from your loggerConfiguration.

Also, add your own batch emitting rules and filters per your requirements. Replace your_telegram_bot_token and your_chat_id with your Telegram bot token and chat ID.

Important: Always validate the configuration towards the end before using it to instantiate an object. This is to ensure that the provided settings are valid and appropriate for the operation of the Telegram sink.