DiscordLogger Tests Badge Codecov Latest/Minimum Swift Version

? Just a reminder that there is a ? button up there if you liked this project ? ?

Discord Logger

DiscordLogger is a swift-log implementation for sending your logs over to a Discord channel. It uses DiscordBM to communicate with Discord.

Showcase

You can see Vapor community’s Penny bot as a showcase of using this library in production. Penny uses DiscordLogger to send a selected group of important logs to an internal channel, so maintainers can be easily notified of any problems that might occur to her. Penny is available here and you can see DiscordLogger being used here .

How To Use

Make sure you have Xcode 14.1 or above. Lower Xcode 14 versions have known issues that cause problems for libraries.

Make sure you’ve added swift-log and AsyncHTTPClient to your dependancies.

import DiscordLogger
import Logging
import AsyncHTTPClient

/// Make an `HTTPClient`.
/// If you've already made an `HTTPClient` somewhere else, you should use that instead.
let httpClient = HTTPClient(eventLoopGroupProvider: .createNew)

/// Configure the Discord Logging Manager.
DiscordGlobalConfiguration.logManager = await DiscordLogManager(
    httpClient: httpClient
)

/// Bootstrap the `LoggingSystem`. After this, all your `Logger`s will automagically start using `DiscordLogHandler`.
/// Do not use a `Task { }` to avoid possible bugs.
/// Wait before the `LoggingSystem` is bootstrapped.  
await LoggingSystem.bootstrapWithDiscordLogger(
    /// The webhook address to send the logs to. 
    /// You can easily create a webhook using Discord desktop app with a few clicks.
    /// See https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks
    /// There is a 'Making A Webhook' there.
    address: try .url(<#Your Webhook URL#>),
    makeMainLogHandler: StreamLogHandler.standardOutput(label:metadataProvider:)
)

/// Make sure you haven't called `LoggingSystem.bootstrap` anywhere else, because you can only call it once.
/// For example Vapor's templates use `LoggingSystem.bootstrap` on boot, and you need to remove that.

DiscordLogManager comes with a ton of useful configuration options. Here is an example of a decently-configured DiscordLogManager: Read DiscordLogManager.Configuration.init documentation for full info.

DiscordGlobalConfiguration.logManager = await DiscordLogManager(
    httpClient: httpClient,
    configuration: .init(
        aliveNotice: .init(
            address: try .url(<#Your Webhook URL#>),
            /// If nil, DiscordLogger will only send 1 "I'm alive" notice, on boot.
            /// If not nil, it will send a "I'm alive" notice every this-amount too. 
            interval: nil,
            message: "I'm Alive! :)",
            color: .blue,
            initialNoticeMention: .user("970723029262942248")
        ),
        mentions: [
            .warning: .role("970723134149918800"),
            .error: .role("970723101044244510"),
            .critical: .role("970723029262942248"),
        ],
        extraMetadata: [.warning, .error, .critical],
        disabledLogLevels: [.debug, .trace], 
        disabledInDebug: true
    )
)

Example

/// After bootstrapping the `LoggingSystem`, and with the configuration above, but `extraMetadata` set to `[.critical]`
let logger = Logger(label: "LoggerLabel")
logger.warning("Warning you about something!")
logger.error("We're having an error!", metadata: [
    "number": .stringConvertible(1),
    "statusCode": "401 Unauthorized"
])
logger.critical("CRITICAL PROBLEM. ABOUT TO EXPLODE ?")

DiscordLogger Showcase Output

How To Add DiscordLogger To Your Project

To use the DiscordLogger library in a SwiftPM project, add the following line to the dependencies in your Package.swift file:

.package(url: "https://github.com/DiscordBM/DiscordLogger", from: "1.0.0-beta.1"),

Include DiscordLogger as a dependency for your targets:

.target(name: "<target>", dependencies: [
    .product(name: "DiscordLogger", package: "DiscordLogger"),
]),

Finally, add import DiscordLogger to your source code.

Versioning

DiscordLogger will try to follow Semantic Versioning 2.0.0.

Contribution & Support

Any contribution is more than welcome. You can find me in Vapor’s Discord server to discuss your ideas.

GitHub

View Github