simple-slacklogger 0.0.3

Application-level event tracking with Slack

Intro

slacklogger is a simple Python package that logs application-level events to your Slack channels. The package includes a function decorator, a regular function, and some settings to play around with. Here's how everything works.

Installation

To install slacklogger, use pip.

pip install simple-slacklogger

Getting Started

To start using slacklogger you'll need to create a Slack app in your Workspace. This is pretty straightforward:

• Once you've signed up for a Slack account head over to the Slack Apps page.
• Click on Create New App, name your app, and choose your Workspace.
• Click on the Create App button.
• Click on Oauth & Permissions in the left sidebar.
• Add the 'chat:write.public' Oauth Scope under the Bot Token Scopes section. This will also add the 'chat:write' scope.
• On the same page, at the top, click the Install App to Workspace button.
• Click Allow on the next screen.
• Save the generated Bot User OAuth Access Token.
• Head over to the Slack homepage and launch your workspace in your browser.
• Head to the channel where you want your app to post logs, and note the path value in the URL after the final '/'. It will look something like D05ZAYNAASL. Copy this as well.

Now that you have your Slack channel_id and access_token, you can initialize slacklogger.

import slacklogger

slacklogger.creds = {
    "channel_id": "YOUR_CHANNEL_ID",
    "access_token": "YOUR_ACCESS_TOKEN"
}

Slacklogger Decorator

The slacklogger.log decorator wraps around any function and runs before your main function. For example:

@slacklogger.log(message="It works")
def my_function():
    print("Hooray, it worked!")

"It works" will be logged in your Slack channel before "Hooray, it works" is printed in your app. If you want something more granular...

Slacklogger Function

slacklogger.send_log works much the same way as the decorator, except it doesn't automatically extract your function's name and script path - you can do that with an included helper function, my_details, which takes the function's name as a parameter.

from slacklogger.helpers import my_details

def new_user(name: str):
    print("Creating new user...")
    func_name, script_path = my_details(new_user) 
    slacklogger.send_log(
        message=f"Created new user: {name}",
        function_name=func_name,
        script_path=script_path
    )

Note that if your function is in a class, and you're using the my_details helper function, prepend your function's name with self - for example, my_details(self.new_user).

from slacklogger.helpers import my_details

class User:
    def __init__(self):
        pass

    def new_user(self, name: str):
        print("Creating new user...")
        func_name, script_path = my_details(self.new_user) # <= add 'self'
        slacklogger.send_log(
            message=f"Created new user: {name}",
            function_name=func_name,
            script_path=script_path
        )

Slacklogger Options

For both the decorator and the function, only the message parameter is required, but you can also define the level, any tags, and the timezone (this defaults to UTC).

@slacklogger.log(
    message="My Message",
    level="info",
    tags=["#first", "#test"],
    timezone="America/New_York",
)
def my_function():
    print("Hooray, it worked!")

This will output something akin to the following in your Slack:

The regular function has the same options, along with function_name and script_path as we saw above.

def new_user(name: str):
    print("Creating new user...")
    func_name, script_path = my_details(new_user) 
    slacklogger.send_log(
        message=f"Created new user: {name}",
        leve="info",
        tags=["#new_user", "#users"]
        function_name=func_name,
        script_path=script_path,
        timezone="America/New_York"
    )

Settings

You can define two settings after you enter your credentials: date_format and level_colors. The date_format setting refers to how the log date and time are displayed. The level_colors setting allows you to define a dict of level names and their corresponding hex color codes.

import slacklogger

slacklogger.creds = {
    "channel_id": "MY_CHANNEL_ID",
    "access_token": "MY_ACCESS_TOKEN"
}

slacklogger.settings = {
    "date_format": "%b %d, %Y | %H:%M:%S %Z",
    "level_colors": {
        "default": "#007300",
        "debug": "#007300",
        "info": "#0000e5",
        "warn": "#e5e500",
        "error": "#e59400",
        "fatal": "#ff0000"
    }
}

The above values are the default settings slacklogger uses.

To create your own date formatting, check out this cheat sheet for strftime directives.

slacklogger.settings["date_format"] = "%b %d, %H:%M"

For level_colors, you can add any name and hex color code you need to slacklogger.settings["level_colors"] - or overwrite the entire dict.

slacklogger.settings["level_colors"]["ntk"] = "#730073"

You can use color-hex.com to choose color hex codes for your levels.

Using the example directly above, we can add a new level ('ntk', or 'Nice to Know') to the decorator or regular function.

@slacklogger.log(
    message="NTK Example",
    level="ntk",
    tags=["#level", "#test"],
    timezone="America/New_York",
)
def my_function():
    print("New level acquired!")

You'll see an output like this:

Timezone

To change the timezone, simply change the timezone parameter in either the decorator or the function. Check this Wiki link for relevant timezone names.

def timezone_test(name: str):
    print("Testing new timezone...")
    slacklogger.send_log(
        message="Testing Timezone",
        level="debug",
        timezone="Europe/Lisbon" # <= change this
    )

You should see something like this using the above code (notice that function_name, script_path, and tags are omitted, as they're all optional).