shuuten 0.2.0

Last-stop signals for automation failures.

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