Installation and Usage¶

Prerequisites¶

Python 3.11+ is required for the slacker CLI. The slacker Lambda function uses the Python 3.13 runtime.

The AWS components (slacker Lambda function, DynamoDB tables etc) are installed from the repo using AWS SAM. This will need to be installed first.

SAM is not required for the slacker CLI.

Editorial

AWS SAM used to be installable from PyPI. It may be still, but AWS doesn't seem to support it. The rest of the world seem to manage OK(-ish) with PyPI for far more complex packages than SAM. ¯_(ツ)_/¯

Webhook Setup in Slack¶

Slacker uses Slack's incoming webhooks custom integration mechanism to send messages. The management section for these can be found in Slack here.

There is nothing else you need to install in your workspace.

Note

Token based webhooks are a legacy integration method but they work just fine.

Installing the Slacker AWS Components¶

With AWS SAM installed, the installation / update process for slacker is as follows:

# Clone the repo and prepare the working area (create virtualenv etc)
git clone git@github.com:jin-gizmo/slacker.git
cd slacker
make init

# Activate the venv
source venv/bin/activate

# Do a guided install.
make install

Note

Slacker can be deployed in as many AWS regions and accounts as required.

Info

The CloudFormation stack name should be left as slacker, if at all possible. This affects the naming of the Lambda function and the DynamoDB tables, among other things.

Slacker Lambda Configuration Parameters¶

The guided install process prompts for any required configuration values. The defaults should be fine in most cases but this is what the less obvious ones relating to the CloudFormation stack mean:

Parameter	Description
defaultSideBarColour	Slack messages will have a colour bar displayed down the left margin specified by the value of this field unless overridden for a given source ID in the webhooks table. This can be any hex colour code (prefixed with `#`), or one of the Slack special values `good`, `warning`, or `danger`. This parameter sets the `SLACKER_COLOUR` environment variable for the Lambda function.
dynamoDbReadCapacity	Read capacity units for the DynamoDB table. The default is 5. While this seems quite low, it should be adequate in most environments as a result of caching in the slacker Lambda.
maxMessageLen	The maximum length in bytes of messages sent to Slacker. Longer messages are truncated. This parameter sets the `SLACKER_MSG_LEN` environment variable for the Lambda function.

Other stack parameters are self-explanatory.

Slacker Lambda Environment Variables¶

The slacker Lambda supports the following environment variables.

Name	Description	Default
AWS_ACCOUNT_NAME	An arbitrary label for the AWS account for human consumption.	AWS account alias
LOGLEVEL	One of the standard Python logging levels (`debug`, `info`, ...).	`info`
LOG_MESSAGES	If set to `1`, log messages to CloudWatch prior to processing. See Message Logging.	`1`
SLACKER_COLOUR	The default colour for the bar on the left hand margin of messages sent to Slack unless overridden for a given source ID in the webhooks table. This can be any hex colour code or one of the Slack special values `good`, `warning` or `danger`.	`#bbbbbb`
SLACKER_MSG_LEN	The maximum length in bytes of messages sent to Slacker. Longer messages are truncated.	4000
SLACKER_CACHE_TTL	Number of seconds to cache lookups from the DynamoDB tables.	300

The Slacker CLI¶

The slacker CLI is installed with pip:

pip install jinslacker
slacker --help

It can also be built from the repo:

# Output is in dist/pkg directory
make pkg

Slacker CLI Environment Variables¶

The slacker CLI supports the following environment variables.

Name	Description	Default
SLACKER_APP_NAME	Name of the slacker Lambda function.	`slacker`

CLI Usage¶

Command Usage

usage: slacker [-h] [-v] {check,dump,get,list,put,restart,test} ...

Manage slacker webhooks and rules.

positional arguments:
  {check,dump,get,list,put,restart,test}
    check           Check slacker configuration.
    dump            Dump the DynamoDB webhooks table.
    get             Fetch an entry from the DynamoDB webhooks table.
    list            List source IDs in the DynamoDB webhooks table.
    put             Create / update an entry in the DynamoDB webhooks table.
    restart         Restart the slacker Lambda.
    test            Test a message for processing against a webhooks entry.

options:
  -h, --help        show this help message and exit
  -v, --version     Show version and exit.

Full user guide at https://jin-gizmo.github.io/slacker

Typical usage might be something like this:

# Get help
slacker --help
# Get help on a subcommand
slacker list --help

# List webhooks table source IDs
slacker list

# Download one. Note that this will populate the `account` field in the
# downloaded webhook data.
slacker get my-source-id > my-source-id.yaml

# Test out the rules in a webhook file to see what they do to a message.
slacker test my-source-id.yaml < message.txt

# Upload the webhooks entry back to DynamoDB but keep a backup of the original
slacker put --backup my-source-id-orig.yaml my-source-id.yaml

# Backup all webhooks to a zip file
slacker dump webhooks.zip

Command Line Completion¶

Note

New in v2.8.0.

The slacker CLI can produce command completion scripts for the most common shells (typically zsh or bash).

# Produce the command completion script for zsh
slacker completion --shell zsh

# ... and for bash ...
slacker completion --shell bash

Place the resulting script wherever it needs to go in your environment. For zsh with oh-my-zsh, this would typically be something like ~/.oh-my-zsh/completions/_slacker.

Info

You will probably need to run compinit and/or bashcompinit and/or restart your shell after creating the completion script.

Tip

The bash completion shell will not work on the 20 year old version of bash that ships on macOS. Honestly, just switch to zsh which is now the default shell on macOS anyway.

Adding Message Sources¶

Slacker supports messages received from:

Amazon SNS
CloudWatch Logs
Amazon EventBridge
Direct invocation of the slacker Lambda.

Tip

It is often easier to use the AWS Lambda console, rather than the console for the originating service when setting up Lambda triggers. The former seems to get the permissions correct more consistently. IMO.

Amazon SNS¶

To add an SNS topic as a slacker message source:

Create the SNS topic, if necessary, and get the topic ARN.
Add the topic ARN as a trigger to the slacker Lambda.
Create a new entry in the webhooks table with the sourceId set to the topic ARN, and whatever destination Slack channel and rules are appropriate.

CloudWatch Logs¶

To add a CloudWatch Log group as a slacker message source:

Create the log group, if necessary.
Add a subscription filter to the log group. You can either add filtering at the log group level or in the slacker rules. Note that CloudWatch only permits two subscription filters per log group, which may limit your options.
Create a new entry in the webhooks table with the sourceId set to the log group name prefixed with logs:, and whatever destination Slack channel and rules are appropriate.

Warning

Do not connect the slacker Lambda log group /aws/lambda/slacker as a slacker message source. Trust me on this, do not cross the streams.

Amazon EventBridge¶

Slacker can receive messages from Amazon EventBridge either directly, or via SNS. The target(s) for the EventBridge rule determine the path.

EventBridge Rule Targets without Input Transformation¶

If the EventBridge input message is to be sent to Slacker as-is (without an input transformation), it can either be sent directly with the slacker Lambda as a rule target, or via SNS. In the former case, slacker will use the message source attribute as the sourceId to lookup in the webhooks table. In the latter case, it uses the topic ARN as the sourceId.

EventBridge Rule Targets with Input Transformation¶

If the EventBridge rule is using an input transformation to create a new message, it can be sent to slacker via SNS. Messages received by slacker from SNS use the topic ARN as the sourceId to lookup in the webhooks table.

Alternatively, an EventBridge rule with an input transformation can send a custom object directly to the slacker Lambda. In this case, slacker needs to know which webhooks entry to apply. The input template should include the following fields in the custom object for this purpose:

Name	Required	Type	String
SlackerSourceId	Yes	String	The slacker `sourceId`. This is used as the key into the webhooks table to obtain the appropriate webhooks entry.
SlackerSourceName	No	String	A human readable description for the source. Defaults to the `SlackerSourceId`.

Refer to the AWS documentation for more information.

Direct Invocation¶

Object messages can be sent directly to the slacker Lambda. The message should include the following fields for this purpose:

Name	Required	Type	String
SlackerSourceId	Yes	String	The slacker `sourceId`. This is used as the key into the webhooks table to obtain the appropriate webhooks entry.
SlackerSourceName	No	String	A human readable description for the source. Defaults to the `SlackerSourceId`.

This example shows how to do it using the AWS CLI:

aws lambda invoke --function-name slacker response.json \
    --cli-binary-format raw-in-base64-out \
    --payload '
{
    "SlackerSourceId": "my-source-id",
    "SlackerSourceName": "My App",
    "more": "data",
    "...": "..."
}'