Home

Shuuten Signal — last-stop signals for automation failures¶

Shuuten sends structured Slack and email alerts when your Python automations fail — especially in AWS Lambda and ECS — with minimal setup and zero dependencies.

終点 (Shūten) means "final stop" in Japanese — the point where a workflow ends and signals that something needs attention.

📖 Documentation · ⭐ Star on GitHub

Quick start (AWS Lambda)¶

import shuuten

@shuuten.capture
def lambda_handler(event, context):
    shuuten.debug('debug info')      # not sent
    shuuten.error('domain error')    # sent to Slack
    1 / 0                            # sent with stack trace

Set one environment variable and you’re done (see Slack webhook setup):

export SHUUTEN_SLACK_WEBHOOK_URL="https://hooks.slack.com/services/..."

Why Shuuten?¶

Built for failure paths — only ERROR+ signals are sent by default
Zero dependencies — no SDKs, agents, or background workers
Designed for AWS — Lambda, ECS tasks, and containers work out of the box
Logging-native — uses familiar logging semantics
Opinionated but minimal — small surface area, easy to reason about

Installation¶

pip install shuuten             # no dependencies (Slack, local logging)
pip install "shuuten[email]"    # SES email (boto3) outside AWS Lambda

Usage patterns¶

Structured logging (logging-style)¶

import shuuten

def handler(event, context):
    shuuten.info('hello')        # not sent
    shuuten.error('bad input')   # sent to Slack if configured

Explicit logger + email notifications¶

Requires SES env vars (SHUUTEN_SES_FROM, SHUUTEN_SES_TO). Email is sent via AWS SES if configured.

import shuuten

shuuten.init(shuuten.Config(app='my-app', env='dev'))
log = shuuten.get_logger(__name__)


@shuuten.capture(workflow='my-workflow')
def handler(event, context):
    log.critical('Something went wrong')  # sent to Slack + Email (if configured)

Manual context control (advanced)¶

import shuuten

def handler(event, context):
    token = shuuten.detect_and_set_context(context)
    try:
        ...
    finally:
        shuuten.reset_runtime_context(token)

The capture() decorator works for ECS tasks as well (via ECS metadata v4).

Configuration¶

You can configure Shuuten via Config in code or environment variables.

Variable	Description	Default
`SHUUTEN_APP`	Application name (used for grouping/metadata)	auto
`SHUUTEN_ENV`	Environment name (`prod`, `dev`, `staging`, etc.)	auto
`SHUUTEN_MIN_LEVEL`	Minimum level sent to destinations	`ERROR`
`SHUUTEN_EMIT_LOCAL_LOG`	Emit local structured log when notifying	`true`
`SHUUTEN_QUIET_LEVEL`	Silence noisy third-party logs (e.g. boto)	`WARNING`
`SHUUTEN_DEDUPE_WINDOW_S`	Slack dedupe window (seconds); `0` disables	`30`

Slack¶

Variable	Description
`SHUUTEN_SLACK_WEBHOOK_URL`	Slack Incoming Webhook URL
`SHUUTEN_SLACK_FORMAT`	`blocks` or `plain`

Email (SES)¶

Variable	Description
`SHUUTEN_SES_FROM`	Verified SES sender
`SHUUTEN_SES_TO`	Comma-separated recipient list
`SHUUTEN_SES_REPLY_TO`	Optional reply-to address
`SHUUTEN_SES_REGION`	Optional SES region

Supported destinations¶

Slack (Incoming Webhooks)
Email (AWS SES)

Note: When running in AWS (e.g. Lambda or ECS), the execution role must be allowed to send email via SES. See AWS docs.

Roadmap¶

PagerDuty and other alerting destinations
Context manager for exception capture
Optional "exceptions-only" alerting mode
Expanded ECS and EKS support

Credits¶

Created with Cookiecutter using https://github.com/audreyfeldroy/cookiecutter-pypackage