shuuten 0.3.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).

Structured logging with extra

Works with both shuuten.info() and log = shuuten.get_logger(__name__) — any logger using ShuutenJSONFormatter.

Attach structured context with data

Pass a dict under the data key in extra to merge fields top-level into the JSON log output:

shuuten.info('Incoming event', extra={
    'data': {
        'method': 'POST',
        'path': '/slack/events',
        'status': 200,
    }
})
# → {"ts": ..., "level": "info", "msg": "Incoming event", "method": "POST", "path": "/slack/events", "status": 200, ...}

Note: Keys in data must not conflict with shuuten's built-in output fields (ts, fn, file, lineno, level, msg, logger, stack, kind, shuuten, exc). A ValueError is raised if they do:

ValueError: shuuten: extra 'data' keys ['msg'] conflict with built-in log output fields.

Attach internal shuuten context

Use the shuuten key to attach structured metadata that is nested under a shuuten field in the output:

shuuten.info('Processing request', extra={'shuuten': {'caller': 'my_fn', 'request_id': '123'}})
# → {"ts": ..., "msg": "Processing request", "shuuten": {"caller": "my_fn", "request_id": "123"}, ...}

Log a dict or list directly as msg

Pass a Python dict or list directly as the message — it will be embedded as a native JSON object rather than a stringified representation:

shuuten.info({'event': 'app_requested', 'app_id': 'A123', 'scopes': ['incoming-webhook']})
# → {"ts": ..., "msg": {"event": "app_requested", "app_id": "A123", "scopes": [...]}, ...}

This also works with shuuten.get_logger():

log = shuuten.get_logger(__name__)
log.info({'event': 'app_requested', 'app_id': 'A123'})

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