Apache Airflow 恢复自定义[email] email_backend发送任务失败/重试告警修复原理与升级检查指南【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow导读本文围绕 Apache Airflow 的email_on_failure/email_on_retry任务告警通道讲解一项关键 bugfix自定义[email] email_backend如 Amazon SES、SendGrid 或组织内部邮件后端此前被无条件路由到SmtpNotifier导致告警丢失本修复将其恢复为通过自定义后端发送。文章将结合 修复条目、邮件配置文档、任务运行时实现 与 适配器源码讲清问题根因、修复后的分发逻辑、两个触发路径worker 与 DAG Processor以及升级前的检查要点。读完你不仅能理解这条 bugfix 的来龙去脉还能立即照做验证自己的部署是否会受影响。背景email_on_failure与email_on_retry的告警链路在 Apache Airflow 中任务的失败与重试告警由两个经典参数控制email_on_failure任务失败时发送告警邮件email_on_retry任务即将重试时发送告警邮件。是否真正发送还取决于任务上是否配置了收件人列表email例如email[opsexample.com]。DAG 中典型的写法如下from airflow import DAG from airflow.operators.bash import BashOperator with DAG(dag_idalert_demo, scheduleNone) as dag: task BashOperator( task_idmaybe_fail, bash_commandexit 1, email[opsexample.com], # 收件人 email_on_failureTrue, # 失败告警 email_on_retryTrue, # 重试告警 retries2, )从源码看Airflow 在DAG Processor进程里专门实现了_execute_email_callbacks函数来处理这两类告警请求见 dag_processing/processor.py其判定逻辑是should_send_email False if request.email_type failure and task.email_on_failure: should_send_email True elif request.email_type retry and task.email_on_retry: should_send_email True if not should_send_email: log.info(Email not sent - task configured with email_on_%sFalse, request.email_type) return也就是说只有任务显式开启了对应开关并且配置了email收件人才会真正进入邮件发送环节。这个是否发送的判定与本次修复无关本次修复的关键在于用什么通道发送。问题根因告警被无条件路由到SmtpNotifierAirflow 支持通过[email] email_backend配置自定义的发信后端默认值是airflow.utils.email.send_email_smtp即走 SMTP 协议见 config.yml 中的定义。社区还提供了基于第三方 API 的替代后端Amazon SES、SendGrid 等配置方式是把email_backend指向对应 provider 的send_email函数详见 email-config.rst。在本次修复之前失败/重试告警的发送路径没有读取[email] email_backend配置而是无条件使用默认的SmtpNotifier来自apache-airflow-providers-smtp。这就造成了一个隐蔽且影响面很大的回归部署了 Amazon SES、SendGrid 或组织内部邮件后端的环境普通邮件如 DAG 中显式调用send_email仍走自定义后端但email_on_failure/email_on_retry触发的任务告警却绕过了自定义后端直接尝试走 SMTP若这些环境根本没有配置可用 SMTP这正是它们选择 SES/SendGrid 的原因告警就会静默丢失且不会报错。修复方案_LegacyEmailBackendNotifier适配器 统一的发送入口本次修复在 Task SDK 中新增了一个关键适配器类_LegacyEmailBackendNotifier见 task-sdk/src/airflow/sdk/execution_time/email_backend.py。它的职责是把旧的、签名为airflow.utils.email.send_email风格的自定义email_backend可调用对象包装成一个 BaseNotifier从而让自定义后端与新的 Notifier 体系对接。它的核心实现要点延迟解析后端在notify()被调用时才执行conf.getimport(email, email_backend, fallback_DEFAULT_EMAIL_BACKEND)而不是静态导入。这样 Task SDK 无需对airflow.utils.email位于 airflow-core产生硬依赖。保持原签名兼容调用时传入conn_id取[email] email_conn_id默认smtp_default与from_email与airflow.utils.email.send_email的调用约定一致。后端未配置时明确报错若解析结果为None抛出AirflowConfigException([email] email_backendis not configured)。真正决定用哪个通道的分发逻辑在_send_error_email_notification见 task-sdk/src/airflow/sdk/execution_time/task_runner.pyemail_backend conf.get(email, email_backend, fallback_DEFAULT_EMAIL_BACKEND) notifier_description SmtpNotifier if email_backend and email_backend ! _DEFAULT_EMAIL_BACKEND: notifier_class _LegacyEmailBackendNotifier notifier_description fconfigured email_backend {email_backend!r} else: try: from airflow.providers.smtp.notifications.smtp import SmtpNotifier except ImportError: log.error( Failed to send task failure or retry email notification: apache-airflow-providers-smtp is not installed. Install this provider to enable email notifications. ) return notifier_class SmtpNotifier可见修复后的决策规则非常清晰[email] email_backend配置使用的发送通道未设置或等于默认值airflow.utils.email.send_email_smtpSmtpNotifier默认保持SmtpNotifier设置了其他自定义后端SES / SendGrid / 内部后端_LegacyEmailBackendNotifier包装并调用该自定义后端默认行为保持不变默认配置下仍走SmtpNotifier这正是修复条目中The default remainsSmtpNotifier的含义。两条告警路径统一收口到同一个函数本次修复覆盖了告警发送的两条完整触发路径确保无论任务在哪一侧失败自定义后端都生效Worker 任务运行路径Task SDK 的 worker 侧在任务结束时调用_send_error_email_notification见 task_runner.py。DAG Processor 回调路径DAG Processor 进程在收到EmailRequest后调用_execute_email_callbacks其内部同样收口到_send_error_email_notification见 dag_processing/processor.py。_send_error_email_notification的 docstring 明确写道Both the worker task-runner path and the DAG-processor callback path funnel through this function, so the resolved backend is used consistently regardless of how the task failedworker 路径与 DAG Processor 路径都汇入此函数因此无论任务以何种方式失败解析出的后端都会被一致使用。这正是修复能够覆盖全部email_on_failure/email_on_retry场景的关键。测试验证DAG Processor 路径尊重自定义后端仓库中的单元测试直接印证了本次修复。test_execute_email_callbacks_uses_custom_email_backend见 tests/unit/dag_processing/test_processor.py做了如下验证配置(email, email_backend): ..._recording_email_backend、email_conn_idmy_smtp、from_emailfromairflow断言SmtpNotifier未被调用mock_smtp_notifier.assert_not_called()断言自定义后端被调用一次且收件人为[testexample.com]、conn_idmy_smtp、from_emailfromairflow。同时在 tests/unit/utils/test_email.py 中test_custom_backend与test_custom_backend_sender也验证了airflow.utils.email.send_email会按配置路由到自定义后端并透传from_email等参数。这些测试共同构成修复行为的回归保障。行为变化与升级检查要点务必逐条核对修复带来两个重要的行为变化升级前请重点检查变化一告警恢复走自定义后端回归修复如果当前部署配置了非默认的[email] email_backendAmazon SES、SendGrid 或组织内部后端升级到包含本修复的版本后email_on_failure/email_on_retry告警将重新通过该自定义后端发送。请确认自定义后端的凭据、email_conn_id指向的连接仍然有效告警模板所需的上下文变量如try_number、max_tries、exception_html、ti.log_url等与自定义后端渲染逻辑兼容在非生产环境先触发一次失败/重试确认告警实际送达。变化二email_backend导入失败不再静默回退破坏性变化修复条目明确指出a configuredemail_backendwhich cannot be imported now fails with a logged error instead of silently falling back to SMTP——配置了但无法导入的email_backend现在会记录错误日志并失败而不再静默回退到 SMTP。这意味着升级前必须确认[email] email_backend的取值仍然能够被解析导入。推荐的检查命令与 email-config.rst 中记录的用法一致# 查看当前生效的 email_backend 配置值 airflow config get-value email email_backend # 在 Python 环境中验证该点路径可以成功导入 python -c import importlib; importlib.import_module(你的.backend模块路径)如果输出值与预期不符例如指向一个已改名或未安装的模块请在升级前修正配置否则升级后所有失败/重试告警都会失败并伴随日志错误。附[email]段的完整配置参考结合 config.yml 与 email-config.rst[email]段可配置项汇总如下[email] # 发送后端默认 SMTP 实现 email_backend airflow.utils.email.send_email_smtp # 后端使用的连接 ID默认 smtp_default可在 UI 中创建 Email/HTTP 类型连接 email_conn_id smtp_default # 发件人地址支持 名称 地址 格式 from_email Airflow airflowexample.com # 是否默认在重试/失败时发送告警默认均为 True default_email_on_retry True default_email_on_failure True # 自定义主题/正文 Jinja2 模板文件路径 subject_template /path/to/my_subject_template_file html_content_template /path/to/my_html_content_template_file # SMTP/IMAP SSL 上下文默认 default可用 none 临时关闭证书校验不推荐 ssl_context default环境变量等价形式export AIRFLOW__EMAIL__EMAIL_BACKENDairflow.utils.email.send_email_smtp export AIRFLOW__EMAIL__EMAIL_CONN_IDsmtp_default export AIRFLOW__EMAIL__FROM_EMAILAirflow airflowexample.com export AIRFLOW__EMAIL__SUBJECT_TEMPLATE/path/to/my_subject_template_file export AIRFLOW__EMAIL__HTML_CONTENT_TEMPLATE/path/to/my_html_content_template_file自定义后端的切换方法详见 email-config.rst安装对应 provider 发行包 → 将email_backend指向其send_email函数的点路径 → 设置email_conn_id指向持有凭据的连接。修复之后这样配置的部署在任务失败/重试告警上也会完整生效。总结问题email_on_failure/email_on_retry告警被无条件路由到SmtpNotifier导致配置了自定义[email] email_backendSES、SendGrid、内部后端的部署收不到告警。修复新增_LegacyEmailBackendNotifier适配器将自定义email_backend包装为 Notifier_send_error_email_notification统一决策worker 与 DAG Processor 两条路径都收口于此默认值仍为SmtpNotifier。升级前必查用airflow config get-value email email_backend确认配置仍可解析导入——因为无法导入的email_backend现在会记录错误并失败而不再静默回退 SMTP。【免费下载链接】airflowApache Airflow - A platform to programmatically author, schedule, and monitor workflows项目地址: https://gitcode.com/GitHub_Trending/ai/airflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考