https://github.com/stevapple/swift-log-telegram
Send SwiftLog messages to any Telegram chat.
https://github.com/stevapple/swift-log-telegram
Last synced: 10 months ago
JSON representation
Send SwiftLog messages to any Telegram chat.
- Host: GitHub
- URL: https://github.com/stevapple/swift-log-telegram
- Owner: stevapple
- License: mit
- Created: 2020-04-07T08:25:46.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-05-27T12:55:05.000Z (about 3 years ago)
- Last Synced: 2025-08-02T17:00:09.663Z (11 months ago)
- Language: Swift
- Size: 48.8 KB
- Stars: 31
- Watchers: 1
- Forks: 3
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# LoggingTelegram ✈️
Welcome to **LoggingTelegram** – a logging backend for [SwiftLog](https://github.com/apple/swift-log) that sends log messages by a [Telegram Bot](https://core.telegram.org/bots).
Inspired by and forked from [LoggingSlack](https://github.com/wlisac/swift-log-slack).
## Installation 📦
LoggingTelegram requires Xcode 11 or a Swift 5.2 toolchain with the Swift Package Manager.
Add the LoggingTelegram package as a dependency to your `Package.swift` file.
```swift
.package(url: "https://github.com/stevapple/swift-log-telegram.git", from: "0.0.1")
```
Add LoggingTelegram to your target's dependencies.
```swift
.target(name: "Example", dependencies: ["LoggingTelegram"])
```
Then start using by:
```swift
import LoggingTelegram
```
## Usage 📝
### Setup a Telegram Bot
LoggingTelegram uses [Telegram Bot API](https://core.telegram.org/bots/api) to send log messages to any Telegram chat.
You can chat with [BotFather](https://t.me/BotFather) to create a new bot and get its API token. The config methods are described [here](https://core.telegram.org/bots#6-botfather).
You need to pass the token to `TelegramLogHandler.init` to set it up.
### Get a Target Chat ID
You can access a chat by its ID. There are various ways to get the ID of a chat, some are discussed in [this thread](https://stackoverflow.com/questions/31078710/how-to-obtain-telegram-chat-id-for-a-specific-user).
You can create a group chat with `TelegramGroup.id(_:Int)`, a channel with `TelegramChannel.id(_:Int)` and a user chat with `TelegramUser.id(_:Int)`.
Alternatively, you can create a channel by its name: `TelegramChannel.name(_:String)`, remember to drop `@` prefix.
### Bootstrap SwiftLog
LoggingTelegram is intended to be used as a secondary logging backend to send urgent log messages directly to Telegram.
You can use SwiftLog's `MultiplexLogHandler` to setup LoggingTelegram with another logging backend.
```swift
import Logging
import LoggingTelegram
let channel = TelegramChannel.name("test").mentioning([1, 3]).mentioning("2")
LoggingSystem.bootstrap { label in
MultiplexLogHandler([
// Setup TelegramLogHandler with your API Token and Chat instance
TelegramLogHandler(label: label, token: "Your Bot Token Here", chat: channel),
// Setup the standard logging backend to enable console logging
StreamLogHandler.standardOutput(label: label),
// Setup multiple TelegramLogHandlers
// TelegramLogHandler(label: label, token: "Your (Another) Bot Token Here", chat: TelegramGroup.id(123))
])
}
```
Since SwiftLog does not support parallel logs and that network connection takes time, loggers after the `TelegramLogHandler` may need to wait for its HTTP request sometimes.
If you want to get the precise timestamp at the console, you may put `TelegramLogHandler` after `StreamLogHandler`:
```swift
import Logging
import LoggingTelegram
let channel = TelegramChannel.name("test").mentioning([1, 3]).mentioning("2")
LoggingSystem.bootstrap { label in
MultiplexLogHandler([
StreamLogHandler.standardOutput(label: label),
TelegramLogHandler(label: label, token: "Your Bot Token Here", chat: channel),
TelegramLogHandler(label: label, token: "Your (Another) Bot Token Here", chat: TelegramGroup.id(123))
])
}
```
### Create and Use a Logger
You can now use SwiftLog as usual and critical log messages are sent directly to Telegram. Test code as below.
```swift
import Logging
let logger = Logger(label: "com.example.ExampleApp.main")
logger.critical("Oops, something went wrong!")
```
### Check Logger Outputs
The logger will send a Telegram message as a bot (if the level matches) and a console message since both logging backends were setup. The example above gives the following outputs:
```plain
2020-04-07T16:05:25+0800 critical: Oops, something went wrong!
```
### Configure Log Level
Only messages of [log level](https://github.com/apple/swift-log#log-levels) `critical` are sent to Telegram by default.
You can adjust the minimal log level for a specific `TelegramLogHandler` by setting its `logLevel` property, or initializing with a `level` property.
```swift
var handler = TelegramLogHandler(label: "test", token: "Your Bot Token Here", chat: TelegramGroup.id(123), level: .error)
// Unrecommended! Low log levels may burden the server and abuse the Telegram function
handler.logLevel = .info
```
You can change the default for all `TelegramLogHandler`s by changing the value of `telegramLogDefaultLevel`.
```swift
telegramLogDefaultLevel = .error
```
Remember, the `TelegramLogHandler.logLevel` property has a priority to `telegramLogDefaultLevel`.
### @Someone in a Group Chat or a Channel
You can mention someone in a group chat or a channel, simply by the various `.mentioning()` APIs, listed below:
```swift
import LoggingTelegram
var chat = TelegramChannel.name("test")
// By TelegramUser
let users = [1,2].map { TelegramUser.id($0) }
chat = chat.mentioning(users) // Returns a new TelegramChannel instance
// You can use his username to mention a user
let user = TelegramUser.name("testme")
chat = chat.mentioning(user)
// By TelegramRawId (A more flexible alias of the "TelegramUser" version)
chat = chat.mentioning(.id(3))
chat = chat.mentioning([.name("newtest"), .id(4)])
// By User ID
chat = chat.mentioning(5)
chat = chat.mentioning([6,7,8])
// By Username
chat = chat.mentioning("test 1")
chat = chat.mentioning(["test 2", "test 3"])
```
In brief, the chaining style is recommended when creating a chat:
```swift
import LoggingTelegram
TelegramChannel.name("test").mentioning([.id(1), .name("2"), .id(3)])
// or
TelegramChannel.name("test").mentioning([1, 3]).mentioning("2")
```
### Mute the Messages
To not disturb subscribers, you may need to mute the message. You can pass a `mute: Bool` to the initializer to make it silent:
```swift
TelegramLogHandler(label: label, token: "Your Bot Token Here", chat: channel, mute: true)
```
The mentioned users won't be muted.
## Attention ⚠️
You should know what you're doing though this package. Do not use it at client-side to protect the subscribers' info and your Bot Token.