DataHub Monte Carlo 连接器完全指南断言建模、告警/事件摄入与监控运行历史同步【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub导读本文基于 DataHub 开源仓库中的 Monte Carlo 数据源连接器文档系统讲解如何将 Monte Carlo 数据可观测平台上的监控器monitor、自定义 SQL 规则custom rule与告警/事件alert/incident同步为 DataHub 的 Assertion断言体系并可选摄入监控器运行历史与实测指标值。读完本文你将掌握该连接器的完整配置方式、跨平台 URN 映射原理、断言建模规则comparisons→CustomAssertionInfo的映射细节、告警与事件联动机制、运行历史摄入的取舍以及常见故障排查方法。连接器能力总览Monte Carlo 是面向数仓与湖表的开源数据可观测平台DataHub 仓库内文档描述为 data observability platform持续监控表的 freshness、volume、schema 与字段质量问题并在指标越界时产生告警/事件。本连接器源码位于 metadata-ingestion/src/datahub/ingestion/source/montecarlo/将其摄入为 DataHubAssertion体系使数据集原生 Validation/Assertions 标签页直接呈现 Monte Carlo 的观测覆盖与事件历史。连接器能力要点摄入 Monte Carlomonitors与custom (SQL) rules建模为 DataHubCUSTOM类型断言摄入alerts/incidents建模为断言上的AssertionRunEvent失败事件可选摄入monitor run historygetJobExecutions与measured metric valuesgetMetricsV4生成SUCCESS运行事件可选在数据集Incidents标签页创建 DataHubIncident实体支持connection_to_platform_map显式映射与auto_map_connection_types自动推断两种跨平台 URN 解析路径支持状态化摄入stateful ingestion与断言软删除并内置两道安全护栏。前置条件在摄入 Monte Carlo 元数据之前需要满足Monte Carlo Cloud 账户——该连接器不支持自托管/本地部署版本。API Key 对mcd_idmcd_token需具备 monitors、custom rules、alerts 和 catalog 的读取权限可在 Monte Carlo UI 的Settings → API下创建。为每个需要摄入的 Monte Carlo warehouse 配置connection_to_platform_map条目确保被监控资产的 URN 与仓库侧数据源连接器产出的 URN 对齐。跨平台 URN 映射Cross-platform URN mappingMonte Carlo 的 MCONMCONaccountresource-uuidtabledb.schema.table并不编码 DataHub 平台信息。连接器通过getTable将每个 MCON 解析为具体表再依据connection_to_platform_map为每个 Monte Carlo warehouse 固定platform、platform_instance、env从而让产出的数据集 URN 与 Snowflake、BigQuery 等仓库源连接器的 URN 对齐。这是默认且最安全的解析路径资产所在 warehouse 不在映射表中时会被跳过并告警。若为每个 warehouse 维护条目不现实可开启auto_map_connection_types: true自动推断对不在connection_to_platform_map中的 warehouse根据其连接类型snowflake、bigquery、redshift…推断 DataHub 平台无法识别的连接类型回退到default_platform。但自动推断出的数据集 URN 使用顶层platform_instance与env而非每 warehouse 的值因此只适合每个平台单一实例的部署多实例部署下可能把断言挂到错误数据集优先使用connection_to_platform_map。connection_to_platform_map的每个 key 是 Monte Carlowarehouse resource UUID而非显示名可通过以下任一方式获取从资产 MCON 提取resource UUID 是第三个分隔段即MCONaccountresource-uuidtable...中的resource-uuid从 Monte Carlo UI 查看Settings → Integrations选择 warehouse复制其 resource UUID通过 API 查询在 Monte Carlo GraphQL playground 中执行getUser { account { warehouses { uuid name connectionType } } }每个 warehouse 的uuid即为 key。自动映射的连接类型Auto-mapped connection types当 warehouse 不在connection_to_platform_map中时连接器将其 Monte CarloconnectionTypegetTable返回的WarehouseModelConnectionType枚举值映射为 DataHub 平台。源码中的映射表定义于 constants.pyCONNECTION_TYPE_TO_PLATFORM支持的自动映射如下Monte Carlo 连接类型DataHub 平台snowflakesnowflakebigquerybigqueryredshiftredshiftmysqlmysqloracleoracleteradatateradataclickhouseclickhousedremiodremiodb2db2starburst_enterprisetrinostarburst_galaxytrinodatabricks/databricks-sql/databricks-metastoredatabrickssparksparkprestoprestohivehiveglueglueathenaathena其他任何连接类型以及 Monte Carlo 报告为transactional_db的 warehouse不会被自动映射连接器记录告警并跳过该资产而不是猜测平台。transactional_db是一个涵盖 PostgreSQL、SQL Server、Synapse、SAP HANA、Azure SQL 等的类别无法映射到单一 DataHub 平台——必须为每个此类 warehouse 显式添加connection_to_platform_map条目。Azure SQL 与 SAP HANA 同样在 Monte Carlo 侧被报告为transactional_db需要显式映射。完整配置 Recipe 与参数说明官方样例配置位于 montecarlo_recipe.yml配置模型定义于 config.py。以下是完整配置骨架source: type: montecarlo config: # --- Authentication --- api_id: ${MCD_ID} # Monte Carlo API key id (mcd_id) api_token: ${MCD_TOKEN} # Monte Carlo API key token (mcd_token) # api_endpoint: https://api.getmontecarlo.com/graphql # override the MCD endpoint # --- Warehouse - DataHub platform mapping --- connection_to_platform_map: mc-warehouse-uuid: platform: snowflake # DataHub platform name (snowflake, bigquery, redshift, ...) platform_instance: prod # warehouse platform instance (NOT Monte Carlos) env: PROD # Override URN casing for this warehouse only. convert_urns_to_lowercase: true # Fallbacks for warehouses NOT listed in the map above. # default_platform: postgres # target_platform_instance: prod # target_env: PROD # Auto-map a warehouses Monte Carlo connectionType to a DataHub platform. auto_map_connection_types: true # --- What to ingest --- include_assertions: true # monitors custom rules - Assertion entities include_alerts: true # alerts/incidents - AssertionRunEvent failures alerts_lookback_days: 30 # how far back to fetch alerts (default: 30 days) # emit_incidents_on_failure: true # opt in to also create Incident entities # Ingest monitor run history measured metric values as SUCCESS run events. run_events_lookback_days: 7 # query window in days (must be a positive integer) run_events_first: 5 # max runs fetched per monitor (default: 5) # --- Filtering --- # monitor_pattern: # allow: # - .*freshness.* # monitor_type_pattern: # deny: # - VOLUME # domain_ids: # - mc-domain-uuid # --- Rate limiting (client-side) --- # rate_limit_requests_per_second: 5 # rate_limit_burst: 10 # rate_limit_daily: 5000 # --- URN casing (recipe level) --- # convert_urns_to_lowercase: true # --- Stateful ingestion / soft-deletion --- # stateful_ingestion: # enabled: true sink: # sink configs关键参数与源码级说明认证相关config.pyapi_id/api_token必填mcd_id/mcd_token密钥对通过pycarlo.core.Session程序化注入不读环境变量。api_endpoint可选覆盖默认 MCD GraphQL 端点。平台映射相关config.pyconnection_to_platform_mapDict[str, MonteCarloPlatformDetail]key 为 warehouse resource UUID。每个条目包含platform必填配置加载时用 connector registry 的platform_id集合做校验拼写错误会在加载阶段快速失败并给出相近拼写建议见 config.py 的_validate_platform_value、platform_instance、env、convert_urns_to_lowercase可选覆盖。auto_map_connection_types默认false。default_platform仅在auto_map_connection_types: true时生效配置校验器会强制这一点见 config.py。target_platform_instance/target_env作用于自动映射/回退 warehouse 的数据集 URN与 Monte Carlo 自身实例无关。摄入范围相关config.pyinclude_assertions默认true摄入 monitors custom rules 为 Assertion 实体。include_alerts默认true依赖include_assertions配置校验器强制因为 alert run event 要挂到 assertion 上见 config.py。alerts_lookback_days默认 30告警回看窗口。emit_incidents_on_failure默认false为每个告警额外创建 Incident 实体。run_events_lookback_days可选正整数设置后摄入运行历史与实测指标None不设置保持仅 FAILURE 的旧行为。依赖include_assertions。run_events_first默认 5每个 monitor 抓取的最多运行次数getJobExecutions的first参数。过滤与限流monitor_pattern/monitor_type_patternAllowDenyPattern正则过滤名字与类型如FRESHNESS、VOLUME。domain_ids按 Monte Carlo 域 UUID 限定摄入范围。rate_limit_requests_per_second/rate_limit_burst客户端令牌桶限流rate_limit_burst单独设置会被配置校验器拒绝config.py。注意burst 未设置时容量取max(1.0, rate)保证亚秒级速率下首请求不被卡住client.py。rate_limit_daily每日 API 调用预算按 UTC 日历日超限会让本次运行失败DailyCallBudgetExceeded而非阻塞到次日这是 per-run 上限不跨运行共享。断言建模Assertion ModelingMonte Carlo 的每个 monitor 与自定义 SQL 规则都被建模为 DataHubCUSTOM断言其原生comparisons数据被映射到结构化的CustomAssertionInfo字段从而让 Monte Carlo 断言与 dbt、Great Expectations 共用同一套描述组件渲染。对于每个 monitor/rulecomparisons[0]第一个比较条件驱动结构化字段scope当 comparison 携带列引用field/fields时为DATASET_COLUMN否则为DATASET_ROWS表级与行谓词检查。这与 dbt 的列-行启发式一致。operatorMonte Carlo 比较操作符映射到AssertionStdOperatorEQ→EQUAL_TO、GT/GTE/LT/LTE/NEQ、INSIDE_RANGE→BETWEEN、IS_NULL→NULL、IS_NOT_NULL→NOT_NULL。没有干净 DataHub 对应物的操作符AUTO*、NOOP、OUTSIDE_RANGE回退到_NATIVE_。完整映射表在 constants.pyMC_OPERATOR_TO_STD_OPERATOR注意OUTSIDE_RANGE刻意不映射到NOT_IN因为 BETWEEN 的取反语义与 NOT_IN 不同_NATIVE_是更诚实的选择。aggregationMonte Carlo 指标映射到AssertionStdAggregationrow_count→ROW_COUNT、distinct_count→UNIQUE_COUNT、null_count→NULL_COUNT、null_rate→NULL_PROPORTION、min/max/mean/median/stddev/sum。未映射指标回退_NATIVE_映射表见 constants.py。该映射表刻意保持稀疏——只为语义明确的指标添加条目空缺是安全的。fields由 comparison 的field/fields构建的 schema-field URN。MC 的field是单列fields是多列两者皆可选表级/行谓词检查两者都不带。字段 URN 按名称尽力而为CustomAssertionInfo.field/fields的UrnValidation exist:false见 assertion.py。parameters阈值映射到AssertionStdParametersBETWEEN→minValue/maxValue标量比较→value实现见 assertion.py 的_std_parameters。Monte Carlo 原生类型保留在nativeType原生字段severity、data-quality dimension、resource id、comparison type、metric放入nativeParameters。customProperties只保留 DataHub 内部关联键mc_monitor_uuid。对于自定义 SQL 规则原始 SQL 表达式存入customAssertion.logic。复合规则的处理Monte Carlo 规则可携带多个独立 comparison而 DataHub 断言模型是单 comparison 的。连接器将comparisons[0]映射到上述结构化字段并把其余 comparisons 折叠进customAssertion.logicJSON 形式因此复合规则仍被完整表示。这保住了一个 monitor → 一个 assertion URN的方案告警与运行事件的关联逻辑无需改动。实现见 assertion.py其余 comparisons 序列化为紧凑 JSON 追加到logic若已有 custom SQL 则换行拼接。无 comparisons 的回退未返回comparisons或 comparisons 格式错误的 monitor 回退到scope DATASET_ROWS_NATIVE_operator/aggregation镜像 dbt 的 unknown-test-no-column 模式仍走共享渲染路径并在nativeType/nativeParameters携带原生字段。此外_NATIVE_operator 且带lower_threshold/upper_threshold的原生范围操作符如OUTSIDE_RANGE会将上下界补充到nativeParameters避免原生范围比较的边界信息丢失assertion.py。断言 URN 的确定性断言 URN 由MonteCarloAssertionKey(platformmontecarlo, monitor_uuiduuid, instanceplatform_instance)的 GUID 生成assertion.py跨摄入运行稳定、可重复。描述优先取 monitor 的description缺失时回退到name避免 UI 渲染通用的 A custom externally reported Assertion 占位文案assertion.py。告警与事件摄入Alert and Incident IngestionMonte Carlo 的 alerts/incidents 被摄入为对应断言上的AssertionRunEvent失败事件。每个事件携带时间戳、Monte Carlo 告警 ID以及告警原生的 severity/priority/sub-type放入nativeResults。告警还可能引用多个 monitor连接器选择第一个实际已摄入断言的 monitor 进行关联避免首个 monitor 被过滤/未解析时整条告警被丢弃assertion.py。Incident 实体可选当emit_incidents_on_failure开启默认关闭时连接器为每个告警/事件额外创建 DataHubIncident实体urn:li:incident:…。事件通过IncidentSource(typeASSERTION_FAILURE, sourceUrnassertion)反向链接断言失败会同时出现在被监控数据集的Incidents标签页与 Assertions 标签页。确定性 URNincident URN 由(assertion_urn, alert_uuid)的 MD5 哈希确定性推导重新摄入同一告警会更新既有 incident 而非创建重复实体assertion.py。类型标识incident 类型为CUSTOMcustomType为MONTE_CARLO/alert_typeUI 可区分 Monte Carlo 事件与其他来源告警的 subTypes 与 severity 写入描述。为什么不默认开启Monte Carlo 告警会随时间自行解决但连接器没有信号发出IncidentState.RESOLVED转换见后文 Limitations开启后可能累积陈旧的ACTIVE事件。仅当你在 DataHub 侧另行管理事件解决流程时才开启。实现上刻意不给 incident 实体发出StatusClassaspect——OSS GMS 将IncidentInfo注册为 Incident 的 aspect 但不接受其上的Status会返回 HTTP 422仅incidentInfoaspect 即可创建实体assertion.py。运行历史与实测指标值Run History and Measured Metric Values默认情况下连接器只发出告警驱动的FAILURE运行事件。要额外摄入 Monte Carlo 的 monitor运行历史getJobExecutions与实测指标值getMetricsV4即每个 monitor 运行实际计算出的数值将run_events_lookback_days设为正整数 N。开启后对每个已摄入的 monitor连接器抓取最近 N 天内的运行数量由run_events_first封顶默认 5将每个SUCCESS运行发出为AssertionRunEventstatus COMPLETE、result.type SUCCESS最新的 SUCCESS 运行在AssertionResult上携带实测指标值——标准指标落入类型化槽位rowCount、missingCount、unexpectedCount、actualAggValue其余回退到nativeResults更早的 SUCCESS 运行只携带每次运行的执行元数据totalResultCount、evaluatedRecordCount、exceptionsFAILURE运行仍走告警驱动路径不产生重复事件。实测值到类型化槽位的映射MC_METRIC_TO_RESULT_SLOT见 constants.pytotal_row_count/row_count→rowCount、null_count/missing_count→missingCount、unexpected_count→unexpectedCountnull_rate、distinct_count、min/max/mean/median/stddev/sum等标量聚合落入actualAggValueMC_METRIC_TO_AGG_VALUEconstants.py其余指标降级到nativeResults。阈值upper_threshold/lower_threshold也会以nativeResults的key_threshold_upper/lower形式带上。关键取舍与优化细节run_events_lookback_days限定查询窗口而非运行数量——run_events_first才封顶数量。开启后每个已摄入 monitor 大约增加一次getJobExecutions调用 每个指标一次getMetricsV4调用用rate_limit_daily限制额外 API 开销。保持run_events_lookback_days未设置None即维持仅 FAILURE 的历史行为。指标点按(mcon, metric_name)在本次运行内缓存多个 monitor 共享同一张表时不重复拉取source.py。TABLE monitor 只拉取total_row_countTABLE monitor 声明四个 comparison 指标但只有total_row_count会从getMetricsV4返回数据点其余三个是非标准名称、返回零个点只拉取有效指标可避免每个 TABLE monitor 浪费三次 API 调用TABLE_METRICS_TO_FETCHconstants.py。自定义指标custom_value_based_metric_uuid前缀被跳过getMetricsV4对这类指标返回零个点自定义指标走独立 surfaceCUSTOM_METRIC_PREFIXconstants.py。运行事件以is_primary_source False发出陈旧实体清理永远不会触碰它们——断言实体本身仍会因 monitor 从 Monte Carlo 消失而被软删除经由 monitor-definition 主路径但其运行历史被保留。限制Limitations运行历史为可选功能不设置run_events_lookback_days时连接器只发出FAILURE运行事件来自告警/事件不会合成周期性的SUCCESS事件与实测指标值。指标关联是尽力而为getMetricsV4对表级指标不填充jobExecutionUuid无法做逐运行 join。实测值以最新 SUCCESS 运行携带最近测量值的方式进行时间相关性附加并非证明同一运行的匹配。从源码看MonteCarloMetricPoint.job_execution_uuid对表级指标为 nullclient.py印证了这一设计。MCON 解析每个被监控资产需要一次getTable调用将其 MCON 解析为仓库表结果按 MCON 缓存。资产所在 warehouse 不在connection_to_platform_map中时被跳过并告警除非开启auto_map_connection_types此时从 warehouse 连接类型推断平台无法识别的类型回退default_platform。断言类型化所有 monitor 与 rule 都建模为CUSTOM断言。其原生comparisons数据映射到结构化的CustomAssertionInfo字段原生类型/参数放在nativeType/nativeParameters但不会被强制转成DataHub 类型化的 freshness/volume/SQL/field 断言 schema。仅支持 Monte Carlo Cloud需要 Monte Carlo Cloud 账户与 API key 对不支持自托管部署。Incident 停留在 ACTIVE开启emit_incidents_on_failure时每个告警创建ACTIVE状态的 Incident。连接器只在alerts_lookback_days窗口内拉取告警而已解决的告警通常不再出现在 Monte Carlo 告警流中因此没有信号发出IncidentState.RESOLVED转换——DataHub 侧事件可能在底层告警已解决后仍累积在ACTIVE状态。这是emit_incidents_on_failure默认关闭的原因。故障排查Troubleshooting被监控资产被跳过并告警若看到类似Could not resolve MCON to a DataHub dataset URN的告警说明该资产的 warehouse 不在connection_to_platform_map中。解决方案为告警中显示的 warehouse resource UUID 添加映射条目或开启auto_map_connection_types从 warehouse 连接类型推断平台未识别类型回退default_platform。从源码看未映射平台时MconResolver._platform_detail返回None解析器记录mcons_unmapped_platform并给出可操作的提示显式映射、default_platform或开启自动映射见 mcon_resolver.py。断言 URN 与仓库源不匹配断言 URN 由 Monte Carlo monitor ID 键控但目标数据集 URN 经由connection_to_platform_map解析或从 warehouse 连接类型自动映射回退default_platform。若platform、platform_instance或env与仓库源连接器使用的值不一致断言将不会出现在正确数据集上。需将connection_to_platform_map中的值与仓库源配置对齐。几个常导致静默错挂的细节platform_instance是 Monte Carlo 的不是 warehouse 的顶层platform_instance字段属于 Monte Carlo 自身实例它会将该实例盖章到断言实体的dataPlatformInstanceaspect 上不会应用到 warehouse 数据集 URN。对connection_to_platform_map中列出的 warehouse在每条目中设置实例对自动映射的 warehouse不在表中使用target_platform_instance——留空意味着这些 URN 上没有平台实例比猜测更安全。自动映射 warehouse 的envtarget_env独立于 Monte Carlo 自身的env控制自动映射 warehouse URN 的环境未设置时回退到顶层env两者通常一致。若你的 warehouse 源使用不同环境请显式设置。标识符大小写数据集 URN 大小写在 recipe 层控制不按平台硬编码。匹配的connection_to_platform_map条目上的convert_urns_to_lowercase覆盖在设置时优先级最高——对大小写敏感的 Snowflake/Redshift 部署其 warehouse 源以convert_urns_to_lowercase: false运行设置为false使断言定位到相同大小写的数据集。否则顶层convert_urns_to_lowercase生效true强制全局小写不设置则保留大小写。若你的 warehouse 源小写化如 Snowflake 配convert_urns_to_lowercase: true请将顶层标志设为true。实现上full_table_id中的冒号被替换为点以匹配 DataHub 的点分database.schema.table形式大小写逻辑见 mcon_resolver.py。畸形的 table idMonte Carlofull_table_id无法解析为database.schema.table三个点分段时跳过并告警而不是为一个不存在的数据集生成 URNmcon_resolver.py。摄入后没有断言出现请依次验证API key 在 Monte Carlo UI 中具备 monitors、custom rules 和 alerts 的读取权限至少有一个 monitor 处于激活状态且已触发过告警连接器只摄入有关联资产和告警的 monitorconnection_to_platform_map覆盖了被监控资产使用的全部 warehouse 连接。此外源码中还有一道零断言护栏若扫描到 monitor/rule 且尝试构建但最终发出零条断言多半是connection_to_platform_map配置错误或 MCON 全部无法解析运行会记录 failure 并提示检查平台映射见 source.py。注意被命名/类型过滤规则有意丢弃的条目不计入attempted因此 deny-all 或严格过滤不会误报。状态化摄入与软删除状态化摄入stateful_ingestion配置块是可选的——starter recipe 默认注释掉。启用后Monte Carlo 中已不存在的断言会在运行结束时从 DataHub 软删除。两道安全护栏防止糟糕的运行触发软删除零断言护栏若本次运行尝试构建断言但发出零条所有 monitor 解析失败运行记录 failure 且跳过陈旧删除。部分失败护栏若任何 monitor 或自定义规则因瞬时错误网络抖动、API 错误、getTable期间的意外异常构建失败运行记录 failure 且跳过陈旧删除——即使大多数 monitor 构建成功也如此覆盖零断言护栏漏掉的区间如 100 个 monitor 中 40 个遇到瞬时getTable错误。永久性失败表确实消失、或平台未映射不会触发此护栏——这些是合法的删除。相关实现见 source.py。瞬时getTable失败也不会被缓存因此后续共享同一 MCON 的 monitor 会重试而非继承陈旧的Nonemcon_resolver.py 与_resolve的cached标志。建议在确认一次运行端到端健康之前保持stateful_ingestion关闭护栏使其在之后可以安全启用。源码与测试佐证连接器入口与运行编排source.py含零断言护栏、部分失败护栏与运行事件阶段。断言/告警/运行事件构建assertion.py。映射常量操作符、聚合、结果槽位、连接类型→平台constants.py。MCON 解析与 URN 构建mcon_resolver.py。API 客户端认证、分页、重试、限流client.py。配置模型与校验config.py。集成测试metadata-ingestion/tests/integration/montecarlo/test_montecarlo.py因 Monte Carlo 无公开 Docker 镜像测试注入伪造 pycarlo 客户端回放录制的 GraphQL 响应真实 source、client、resolver 与 builder 端到端运行金样文件为 montecarlo_mces_golden.json单元测试见 metadata-ingestion/tests/unit/montecarlo/test_montecarlo.py。综上所述该连接器将 Monte Carlo 的监控、告警与运行数据完整映射到 DataHub 断言体系其跨平台 URN 映射、comparisons[0]结构化映射与双重软删除护栏设计使得同步后的断言既能与仓库源数据集精确对齐又能在瞬时故障下保证数据安全。【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考