警报和报告
用户可以配置自动警报和报告,将仪表板或图表发送到电子邮件收件人或 Slack 频道。
- 警报在达到 SQL 条件时发送
- 报告按计划发送
警报和报告默认情况下处于禁用状态。要启用它们,您需要进行一些设置,此处进行了说明。
要求
公共部分
在您的 superset_config.py
或 superset_config_docker.py
"ALERT_REPORTS"
功能标志 必须设置为 True。- CeleryConfig 中的
beat_schedule
必须包含reports.scheduler
的计划。 - 至少必须配置其中一项,具体取决于您要使用什么
- 电子邮件:
SMTP_*
设置 - Slack 消息:
SLACK_API_TOKEN
- 电子邮件:
禁用模拟运行模式
只要 ALERT_REPORTS_NOTIFICATION_DRY_RUN = True
(其在 docker/pythonpath_dev/superset_config.py
中的默认值),就会截取屏幕截图,但不会实际发送任何消息。要禁用模拟运行模式并开始接收电子邮件/Slack 通知,请将 ALERT_REPORTS_NOTIFICATION_DRY_RUN
设置为 False
,位于 superset 配置 中。
在您的 Dockerfile
- 您必须安装一个无头浏览器,用于截取图表和仪表板的屏幕截图。目前仅支持 Firefox 和 Chrome。
如果您选择 Chrome,您还必须在
superset_config.py
中将WEBDRIVER_TYPE
的值更改为"chrome"
。
注意:如果您按照 在本地安装 Superset 的步骤操作,则 dev docker 映像中包含所有必需的组件(Firefox 无头浏览器、Redis、Postgres 数据库、celery worker 和 celery beat)。您只需添加本指南中描述的必需配置变量即可(请参阅 详细配置
)。
如果您运行的是非 dev docker 映像(例如,像 apache/superset:3.1.0
这样的稳定版本),则该映像不包含无头浏览器。只有 superset_worker
容器需要此无头浏览器才能浏览到目标图表或仪表板。您可以安装和配置无头浏览器 - 请参阅下面的“自定义 Dockerfile”部分 - 或者在通过 docker compose
部署时,修改您的 docker-compose.yml
文件以对 worker 容器使用 dev 映像,对 superset_app
容器使用稳定版本映像。
注意:在此上下文中,“dev 映像”与相应的非 dev 映像具有相同的应用程序软件,只是捆绑了额外的工具。因此,像 3.1.0-dev
这样的映像在稳定性、功能和生产环境中运行方面与 3.1.0
相同。Superset 的实际“开发中”版本 - 最前沿且不稳定 - 在 Docker Hub 上没有使用版本号进行标记,并且将在 Superset UI 中显示版本 0.0.0-dev
。
Slack 集成
要将警报和报告发送到 Slack 频道,您需要在工作区中创建一个新的 Slack 应用程序。
- 连接到您的 Slack 工作区,然后前往 [https://api.slack.com/apps]
- 创建一个新的应用程序。
- 转到“OAuth 和权限”部分,并为您的应用程序授予以下范围
incoming-webhook
files:write
chat:write
- 在“OAuth 和权限”部分的顶部,单击“安装到工作区”。
- 为您的应用程序选择一个默认频道,然后继续。(您可以通过将 Superset 应用程序邀请到该频道来发布到任何频道)。
- 该应用程序现在应该已安装在您的工作区中,并且应该已创建“Bot 用户 OAuth 访问令牌”。将该令牌复制到
superset_config.py
中的SLACK_API_TOKEN
变量中。 - 重新启动服务(或运行
superset init
)以提取新的配置。
注意:当您配置警报或报告时,Slack 频道列表将使用没有前导“#”的频道名称,例如,使用 alerts
而不是 #alerts
。
Kubernetes 特定
- 您必须有一个
celery beat
pod 正在运行。如果您使用的是 GitHub 存储库中 helm/superset 下包含的图表,则需要在您的值覆盖中添加supersetCeleryBeat.enabled = true
。 - 您可以查看有关 Kubernetes 安装 的专用文档以获取更多详细信息。
Docker Compose 特定
您必须在 docker-compose.yml
中拥有
- 一个 Redis 消息代理
- PostgreSQL 数据库而不是 SQLlite
- 一个或多个
celery worker
- 一个
celery beat
此过程在 Docker swarm 环境中也适用,您只需将 Deploy:
添加到 Superset、Redis 和 Postgres 服务以及您的 swarm 的特定配置即可。
详细配置
以下配置需要添加到 superset_config.py
文件中。此文件在映像运行时加载,其中的任何配置都将覆盖在 config.py
中找到的默认配置。
您可以在 GitHub 存储库中 superset/config.py 中找到有关默认 config.py
中每个字段的文档。
您需要用您的自定义 Redis、Slack 和/或 SMTP 配置替换默认值。
Superset 使用 Celery beat 和 Celery worker(s) 来发送警报和报告。
- beat 是调度程序,它告诉 worker 何时执行其任务。此计划是在您创建警报或报告时定义的。
- worker 将处理在触发警报或报告时需要执行的任务。
在 CeleryConfig
中,只有 beat_schedule
与此功能相关,CeleryConfig
的其余部分可以根据您的需要进行更改。
from celery.schedules import crontab
FEATURE_FLAGS = {
"ALERT_REPORTS": True
}
REDIS_HOST = "superset_cache"
REDIS_PORT = "6379"
class CeleryConfig:
broker_url = f"redis://{REDIS_HOST}:{REDIS_PORT}/0"
imports = (
"superset.sql_lab",
"superset.tasks.scheduler",
)
result_backend = f"redis://{REDIS_HOST}:{REDIS_PORT}/0"
worker_prefetch_multiplier = 10
task_acks_late = True
task_annotations = {
"sql_lab.get_sql_results": {
"rate_limit": "100/s",
},
}
beat_schedule = {
"reports.scheduler": {
"task": "reports.scheduler",
"schedule": crontab(minute="*", hour="*"),
},
"reports.prune_log": {
"task": "reports.prune_log",
"schedule": crontab(minute=0, hour=0),
},
}
CELERY_CONFIG = CeleryConfig
SCREENSHOT_LOCATE_WAIT = 100
SCREENSHOT_LOAD_WAIT = 600
# Slack configuration
SLACK_API_TOKEN = "xoxb-"
# Email configuration
SMTP_HOST = "smtp.sendgrid.net" # change to your host
SMTP_PORT = 2525 # your port, e.g. 587
SMTP_STARTTLS = True
SMTP_SSL_SERVER_AUTH = True # If your using an SMTP server with a valid certificate
SMTP_SSL = False
SMTP_USER = "your_user" # use the empty string "" if using an unauthenticated SMTP server
SMTP_PASSWORD = "your_password" # use the empty string "" if using an unauthenticated SMTP server
SMTP_MAIL_FROM = "[email protected]"
EMAIL_REPORTS_SUBJECT_PREFIX = "[Superset] " # optional - overwrites default value in config.py of "[Report] "
# WebDriver configuration
# If you use Firefox, you can stick with default values
# If you use Chrome, then add the following WEBDRIVER_TYPE and WEBDRIVER_OPTION_ARGS
WEBDRIVER_TYPE = "chrome"
WEBDRIVER_OPTION_ARGS = [
"--force-device-scale-factor=2.0",
"--high-dpi-support=2.0",
"--headless",
"--disable-gpu",
"--disable-dev-shm-usage",
"--no-sandbox",
"--disable-setuid-sandbox",
"--disable-extensions",
]
# This is for internal use, you can keep http
WEBDRIVER_BASEURL = "http://superset:8088" # When running using docker compose use "http://superset_app:8088'
# This is the link sent to the recipient. Change to your domain, e.g. https://superset.mydomain.com
WEBDRIVER_BASEURL_USER_FRIENDLY = "http://localhost:8088"
您还需要指定以哪个用户名渲染仪表板。通常,仪表板和图表对未经授权的请求不可访问,这就是为什么 worker 需要接管现有用户的凭据以截取快照的原因。
默认情况下,警报和报告以警报/报告对象的拥有者的身份执行。要使用固定的用户帐户,只需按如下方式更改配置(此示例中为 admin
)
from superset.tasks.types import ExecutorType
THUMBNAIL_SELENIUM_USER = 'admin'
ALERT_REPORTS_EXECUTE_AS = [ExecutorType.SELENIUM]
请参考代码库中的 ExecutorType
以了解其他执行程序类型。
重要说明
- 请注意 celery 的并发设置(使用
-c 4
)。Selenium/webdriver 实例可能会消耗服务器上的大量 CPU/内存。 - 在某些情况下,如果您发现大量泄漏的 geckodriver 进程,请尝试使用
celery worker --pool=prefork --max-tasks-per-child=128 ...
运行您的 celery 进程。 - 建议为
sql_lab
和email_reports
任务运行单独的 worker。这可以通过task_annotations
中的queue
字段来完成。 - 如果 celery worker 无法通过其默认值
http://0.0.0.0:8080/
访问 Superset,请在您的配置文件中调整WEBDRIVER_BASEURL
。
还可以通过配置文件指定每个报告执行之间的最小间隔
# Set a minimum interval threshold between executions (for each Alert/Report)
# Value should be an integer
ALERT_MINIMUM_INTERVAL = int(timedelta(minutes=10).total_seconds())
REPORT_MINIMUM_INTERVAL = int(timedelta(minutes=5).total_seconds())
或者,您可以将函数分配给 ALERT_MINIMUM_INTERVAL
和/或 REPORT_MINIMUM_INTERVAL
。这对于根据需要动态检索值很有用
def alert_dynamic_minimal_interval(**kwargs) -> int:
"""
Define logic here to retrieve the value dynamically
"""
ALERT_MINIMUM_INTERVAL = alert_dynamic_minimal_interval
自定义 Dockerfile
如果您运行的是已发布 Superset 映像的 dev 版本,例如 apache/superset:3.1.0-dev
,则您应该可以使用上述方法。
但是,如果您正在构建自己的映像,或者从非 dev 版本开始,则需要一个 webdriver(和无头浏览器)来捕获图表和仪表板的屏幕截图,然后将其发送给收件人。以下是如何修改 Dockerfile 以使用 Firefox 或 Chrome 截取屏幕截图。
使用 Firefox
FROM apache/superset:3.1.0
USER root
RUN apt-get update && \
apt-get install --no-install-recommends -y firefox-esr
ENV GECKODRIVER_VERSION=0.29.0
RUN wget -q https://github.com/mozilla/geckodriver/releases/download/v${GECKODRIVER_VERSION}/geckodriver-v${GECKODRIVER_VERSION}-linux64.tar.gz && \
tar -x geckodriver -zf geckodriver-v${GECKODRIVER_VERSION}-linux64.tar.gz -O > /usr/bin/geckodriver && \
chmod 755 /usr/bin/geckodriver && \
rm geckodriver-v${GECKODRIVER_VERSION}-linux64.tar.gz
RUN pip install --no-cache gevent psycopg2 redis
USER superset
使用 Chrome
FROM apache/superset:3.1.0
USER root
RUN apt-get update && \
wget -q https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb && \
apt-get install -y --no-install-recommends ./google-chrome-stable_current_amd64.deb && \
rm -f google-chrome-stable_current_amd64.deb
RUN export CHROMEDRIVER_VERSION=$(curl --silent https://chromedriver.storage.googleapis.com/LATEST_RELEASE_102) && \
wget -q https://chromedriver.storage.googleapis.com/${CHROMEDRIVER_VERSION}/chromedriver_linux64.zip && \
unzip chromedriver_linux64.zip -d /usr/bin && \
chmod 755 /usr/bin/chromedriver && \
rm -f chromedriver_linux64.zip
RUN pip install --no-cache gevent psycopg2 redis
USER superset
如果您使用 Chrome,请不要忘记在您的配置中设置 WEBDRIVER_TYPE
和 WEBDRIVER_OPTION_ARGS
。
故障排除
报告可能无法正常工作的原因有很多。尝试以下步骤检查特定问题。
确认功能标志已启用,并且您具有足够的权限
如果您在 Superset UI 的设置下拉菜单的“管理”部分中没有看到“警报和报告”,则需要启用 ALERT_REPORTS
功能标志(见上文)。启用另一个功能标志并检查它是否生效,以验证您的配置文件是否已加载。
以管理员用户身份登录以确保您具有足够的权限。
检查 Celery 工作程序的日志
这是有关问题的最佳信息来源。在 docker compose 部署中,您可以使用类似 docker logs superset_worker --since 1h
的命令来执行此操作。
检查 Web 浏览器和 Web 驱动程序安装
要截取屏幕截图,工作程序将使用无头浏览器访问仪表板或图表,然后截取屏幕截图。如果您能够将图表发送为 CSV 或文本,但无法发送为 PNG,则您的问题可能出在浏览器上。
标签以 -dev
结尾的 Superset docker 镜像已安装 Firefox 无头浏览器和 geckodriver。您可以通过进入 Superset 工作程序并运行 firefox --headless
,然后运行 geckodriver
来测试这些是否已安装并在正确的路径中。这两个命令都应该启动这些应用程序。
如果您自己处理该软件的安装,或者希望使用 Chromium,请自行验证以确保无头浏览器在工作程序环境中成功打开。
发送测试电子邮件
与电子邮件服务器连接无效的一个症状是在您的日志中收到 [Errno 110] Connection timed out
错误,当报告尝试发送时。
通过测试确认您的出站电子邮件配置是否正确。以下是最简单的测试,用于在端口 25 上运行的未经身份验证的电子邮件 SMTP 电子邮件服务。如果您通过 SSL 发送,例如,请研究 Superset 的代码库如何发送电子邮件,然后使用这些命令和参数进行测试。
在您的工作程序环境中启动 Python,替换所有示例值,然后运行
import smtplib
from email.mime.multipart import MIMEMultipart
from email.mime.text import MIMEText
from_email = '[email protected]'
to_email = '[email protected]'
msg = MIMEMultipart()
msg['From'] = from_email
msg['To'] = to_email
msg['Subject'] = 'Superset SMTP config test'
message = 'It worked'
msg.attach(MIMEText(message))
mailserver = smtplib.SMTP('smtpmail.example.com', 25)
mailserver.sendmail(from_email, to_email, msg.as_string())
mailserver.quit()
这应该发送一封电子邮件。
可能的修复
- 一些云主机禁用传出的未经身份验证的 SMTP 电子邮件以防止垃圾邮件。例如,Azure 默认情况下会阻止某些机器上的端口 25。启用该端口或使用其他发送方法。
- 使用您在该设置中验证有效的另一组 SMTP 凭据。
从工作程序浏览到您的报告
工作程序可能无法访问该报告。它将使用 WEBDRIVER_BASEURL
的值来浏览到该报告。如果该路由无效,或者呈现工作程序无法通过的身份验证挑战,则报告屏幕截图将失败。
通过尝试 curl
您在工作程序的错误日志中看到的报告的 URL 来检查这一点。例如,从工作程序环境中运行 curl http://superset_app:8088/superset/dashboard/1/
。您可能会收到不同的响应,具体取决于仪表板是否存在 - 例如,您可能需要更改该 URL 中的 1
。如果您的日志中有一个来自失败的报告屏幕截图的 URL,那么这是一个很好的起点。目标是确定 WEBDRIVER_BASEURL
的有效值,并确定 HTTPS 或身份验证等问题是否正在重定向您的工作程序。
在启用了身份验证措施(如 HTTPS 和单点登录)的部署中,让工作程序直接导航到在同一位置运行的 Superset 应用程序可能是有意义的,从而避免了需要登录。例如,对于 docker compose 部署,您可以使用 WEBDRIVER_BASEURL="http://superset_app:8088"
,并在您的 TALISMAN_CONFIG
中设置 "force_https": False,
。
将查询安排为报告
您可以选择允许您的用户直接在 SQL Lab 中安排查询。这是通过向保存的查询添加额外的元数据来完成的,这些元数据随后会被外部调度程序(如 Apache Airflow)拾取。
要允许安排查询,请将以下内容添加到配置文件中的 SCHEDULED_QUERIES
中
SCHEDULED_QUERIES = {
# This information is collected when the user clicks "Schedule query",
# and saved into the `extra` field of saved queries.
# See: https://github.com/mozilla-services/react-jsonschema-form
'JSONSCHEMA': {
'title': 'Schedule',
'description': (
'In order to schedule a query, you need to specify when it '
'should start running, when it should stop running, and how '
'often it should run. You can also optionally specify '
'dependencies that should be met before the query is '
'executed. Please read the documentation for best practices '
'and more information on how to specify dependencies.'
),
'type': 'object',
'properties': {
'output_table': {
'type': 'string',
'title': 'Output table name',
},
'start_date': {
'type': 'string',
'title': 'Start date',
# date-time is parsed using the chrono library, see
# https://npmjs.net.cn/package/chrono-node#usage
'format': 'date-time',
'default': 'tomorrow at 9am',
},
'end_date': {
'type': 'string',
'title': 'End date',
# date-time is parsed using the chrono library, see
# https://npmjs.net.cn/package/chrono-node#usage
'format': 'date-time',
'default': '9am in 30 days',
},
'schedule_interval': {
'type': 'string',
'title': 'Schedule interval',
},
'dependencies': {
'type': 'array',
'title': 'Dependencies',
'items': {
'type': 'string',
},
},
},
},
'UISCHEMA': {
'schedule_interval': {
'ui:placeholder': '@daily, @weekly, etc.',
},
'dependencies': {
'ui:help': (
'Check the documentation for the correct format when '
'defining dependencies.'
),
},
},
'VALIDATION': [
# ensure that start_date <= end_date
{
'name': 'less_equal',
'arguments': ['start_date', 'end_date'],
'message': 'End date cannot be before start date',
# this is where the error message is shown
'container': 'end_date',
},
],
# link to the scheduler; this example links to an Airflow pipeline
# that uses the query id and the output table as its name
'linkback': (
'https://airflow.example.com/admin/airflow/tree?'
'dag_id=query_${id}_${extra_json.schedule_info.output_table}'
),
}
此配置基于 react-jsonschema-form,并将向 SQL Lab 添加一个名为“安排”的菜单项。单击菜单项时,将弹出一个模态窗口,用户可以在其中添加安排查询所需的元数据。
然后可以从端点 /api/v1/saved_query/
检索此信息,并用于安排其 JSON 元数据中包含 schedule_info
的查询。对于 Airflow 以外的调度程序,可以轻松地将其他字段添加到上面的配置文件中。