Megatron-LM 训练可观测性指标（Metrics）实战指南：megatron.training.* 命名空间、Prometheus 导出与自定义指标扩展

Megatron-LM 训练可观测性指标Metrics实战指南megatron.training.* 命名空间、Prometheus 导出与自定义指标扩展【免费下载链接】Megatron-LMOngoing research training transformer models at scale项目地址: https://gitcode.com/GitHub_Trending/me/Megatron-LM本篇技术指南以 Megatron-LM 的训练指标Metrics体系为主线完整讲解megatron.training.*指标命名空间下的 8 个训练指标、其基于 OpenTelemetryOTel的发射机制与导出路径并给出 Prometheus 名称映射、跨 run 过滤查询与指标 vs Span 属性的常见陷阱辨析。阅读完本文后你可以直接在 Grafana/Jaeger 等 OTLP 兼容后端中搭建训练监控面板并能依照仓库内的现有实现模式为 Megatron 添加自定义指标。Megatron-LM 通过nemo-lens库接入 OpenTelemetry在训练框架边界发出 traces同时为 loss、吞吐量、梯度范数等关键训练信号发出metrics。指标部分独立成文统一收拢在megatron.training.*项目专属命名空间下相关实现集中在 megatron/core/telemetry/training_metrics.py观测性总览见 docs/user-guide/observability/index.md。指标命名空间与发射范围Megatron 的训练指标全部归属megatron.training.*命名空间。与 span 命名megatron.*保持一致的项目专属风格不同训练指标之所以使用独立命名空间是因为训练过程没有 OTel 官方标准语义约定semantic convention因此由项目自行定义一套稳定的指标名称与单位。两个关键约束需要先明确仅在导出 rank 上发射所有指标只由is_exporting True的 rank 创建并记录非导出 rank 不会创建任何 metric instrument指标仪器。这在分布式训练中避免了每个 rank 各自上报一份相同数据造成的冗余与后端压力。发射节奏与--log-interval对齐指标记录与 TensorBoard、WB logger 的日志节奏完全一致即每--log-interval次迭代记录一次保证三个观测通道看到的是同一时间点的训练状态。训练指标清单megatron.training.*以下是 Megatron 当前发出的全部训练指标逐项对应 training_metrics.py 中的 instrument 定义Metric类型单位描述megatron.training.step_duration_msHistogramms单个训练 step 的耗时毫秒megatron.training.lossGauge—训练 loss每个 log interval 的最新值megatron.training.throughput_tflopsGaugeTFLOP/s训练吞吐单位 TFLOP/s/GPUmegatron.training.tokens_per_secGaugetokens/s训练吞吐单位 tokens/smegatron.training.grad_normGauge—全局梯度范数megatron.training.skipped_itersCounter—被跳过的优化器 step 数loss 为 NaN/inf 时megatron.training.learning_rateGauge—当前学习率megatron.training.memory_allocated_gbGaugeGB峰值 GPU 显存分配量需要特别注意的是类型语义loss、throughput、grad norm、learning rate 全部使用Gauge瞬时值而非 Histogram。这保证了导出到 Prometheus 后得到的是语义正确的gauge类型——这类指标每个 log interval 都会变化用瞬态值表达最合适而 step 耗时这类分布型指标才用 Histogram便于统计 P50/P95 等分位数。发射机制与源码实现指标的发射点位于 megatron/training/training.py训练循环在满足iteration % args.log_interval 0或首个 iteration时进入日志分支并在末尾调用record_training_metrics()# megatron/training/training.py约 3808-3829 行 if _otel_telemetry_log is not None and _otel_telemetry_log.is_exporting: from megatron.core.telemetry.training_metrics import record_training_metrics _avg_loss _otel_loss_snapshot _tokens_per_sec ( batch_size * args.seq_length / elapsed_time_per_iteration if elapsed_time_per_iteration 0 else None ) _mem_gb torch.cuda.max_memory_allocated() / (1024 ** 3) if torch.cuda.is_available() else None record_training_metrics( meter_otel_telemetry_log.meter, step_duration_mselapsed_time_per_iteration * 1000.0, loss_avg_loss, throughput_tflopsthroughput if args.log_throughput else None, grad_normgrad_norm, learning_ratelearning_rate, skipped_iters_otel_skipped_iters_snapshot, tokens_per_sec_tokens_per_sec, memory_allocated_gb_mem_gb, )从这段代码可以读出几个实现细节快照时序loss 与 skipped-iters 取自上方快照snapshot即累加器重置之前的值其余指标在调用时仍是实时值——保证记录的是完整 log interval 的聚合结果。tokens_per_sec的推算由batch_size * args.seq_length / elapsed_time_per_iteration直接计算且当elapsed_time_per_iteration 0时安全地传None。throughput_tflops的条件性仅当args.log_throughput开启时才上报避免无意义的额外开销。memory_allocated_gb的平台守卫仅在torch.cuda.is_available()时上报非 CUDA 环境下传None。指标模块的内部结构training_metrics.py 是整个指标体系的自包含副本——它是从 nemo.lens 的指标记录逻辑复制而来使 Megatron-LM 可以不依赖 nemo-lens 硬依赖就发出训练指标。其内部由三部分组成名称常量文件头部定义了 8 个MEGATRON_TRAINING_*字符串常量与 nemo.lens 的 semconv 对齐保证名称在代码中单一来源。_get_training_instruments(meter)按需创建并缓存 instrument。使用weakref.WeakKeyDictionary以meter为 key 缓存避免 re-init 时发生泄漏首次调用时通过meter.create_histogram / create_gauge / create_counter创建 8 个 instrument。record_training_metrics(meter, **kwargs)公共记录入口所有参数可选None值被静默跳过。例如skipped_iters仅在 0时才调用add()grad_norm会被显式float()转换。同时整个模块对 OTel 缺失保持优雅降级若opentelemetry未安装metrics Nonerecord_training_metrics()直接成为 no-op若 instrument 创建失败只记录一条 warning 日志后返回不影响训练主流程在 megatron/core/telemetry/fallbacks.py 中当 nemo-lens 未安装时还提供了trace_fn、managed_span、span_cm等 no-op stub保证整个 telemetry 层在缺少依赖时一切照常。这种设计使得指标发射对训练性能与稳定性零侵入可以放心在生产环境常开。Prometheus 指标名称与单元后缀OTel SDK 导出到 Prometheus 时可能会根据 instrument 的 unit 追加后缀因此实际抓取到的名称与 OTel instrument 名不完全一致。官方示例映射如下OTel instrument 名称Prometheus 指标示例megatron.training.lossmegatron_training_loss(Gauge)megatron.training.step_duration_msmegatron_training_step_duration_ms_millisecondsmegatron.training.throughput_tflopsmegatron_training_throughput_tflops(Gauge)megatron.training.tokens_per_secmegatron_training_tokens_per_sec(Gauge)megatron.training.skipped_itersmegatron_training_skipped_iters_total注意两个转换规律命名空间中的点号.替换为下划线_带 unit 的 Histogram 会追加单位后缀如_millisecondsCounter 会追加_totalPrometheus 计数器命名惯例。正因后缀随 SDK 版本可能有差异官方仪表板dashboard在写 PromQL 时普遍使用正则匹配例如{__name__~megatron_training_loss.*}这样无论 SDK 是否追加后缀都能命中。如果你在面板上看到 No data推荐用Explore → Prometheus → Metrics browser浏览当前 SDK 版本实际暴露的完整指标名再据此调整查询。跨 run 过滤与多 run 对比每个训练 run 都会被自动分配唯一的nemo.run.id资源属性并且该属性会附着在每一个数据点上。这意味着你可以在 Grafana 中用它做两件事隔离单个 run{nemo_run_idid, __name__~megatron_training_.*}对比两个 run{nemo_run_id~run-a|run-b, __name__megatron_training_loss}run id 的生成遵循固定的优先级顺序详见 docs/user-guide/observability/configuration.mdNEMO_LENS_RUN_ID环境变量显式指定优先级最高→SLURM_JOB_IDSLURM 集群自动检测→ 自动生成的 12 字符 UUID兜底。同一分布式任务的所有 rank 共享同一个run_id同时每个 rank 拥有唯一的service.instance.id格式为{run_id}-rank{rank}因此你既能按 run 聚合整轮训练也能下钻到具体 rank 排查单卡异常。Metric vs Span 属性一个反复出现的陷阱在可观测性设计中最容易出错的地方是把应该是指标的量放到 span 属性上。官方文档明确给出的原则是Loss 每个 iteration 都在变化属于时间序列数据应当记录到megatron.training.loss指标上。Prometheus 会保存每个值Grafana 可将其绘制成连续曲线用于观察训练收敛趋势Iteration 编号是某个特定 span 的分类上下文应当放在megatron.iterationspan 属性上由 Jaeger 这类 trace 系统用于过滤和检索。反过来做则两头受损把 loss 放到 span 属性上Jaeger 中无法形成有用的时间序列——这只是一堆零散的调试数据把 iteration 放到 metric 的 label 上每个 iteration 都会产生一条独立的 metric 序列——无界基数爆炸unbounded cardinality explosion会迅速拖垮 Prometheus 的存储与查询性能。一句话总结会随时间连续变化的量用 Metric用于描述某一次事件是什么的分类信息用 Span/Resource 属性。关于三者的完整辨析可参考 nemo-lens 文档中 Metric vs span attribute vs resource attribute 一节。添加自定义指标三步模板如果你需要为 Megatron 增加项目专属指标官方推荐在megatron/core/telemetry/目录下新增文件并严格仿照 training_metrics.py 的既有模式。模板步骤如下声明WeakKeyDictionary用于 per-Meter 的 instrument 缓存避免重复创建与内存泄漏实现_get_domain_instruments(meter)创建并缓存该域的全部 instrument首次调用时通过meter.create_gauge / create_histogram / create_counter创建实现record_domain_metrics(meter, **kwargs)所有参数可选只记录非None的值与现有record_training_metrics的 None-skipping 行为保持一致。命名空间方面遵循以下约定应用/项目专属指标使用megatron.subsystem.metric命名与训练指标同风格共享的dl.*与gen_ai.*命名空间保留给跨消费者使用或符合行业标准的指标不要随意占用。仓库中已有的nemo.lens.instruments.inference可作为模板参考。按此模式新增的文件会被 megatron/core/telemetry/init.py 统一组织安装 nemo-lens 时使用真实实现未安装时由fallbacks提供 no-op 兜底从而保证新指标与既有体系无缝融合。快速启用与验证要把整套指标真正跑起来最小配置只需三个环境变量完整配置见 docs/user-guide/observability/configuration.mdexport MEGATRON_OTEL_ENABLED1 export OTEL_EXPORTER_OTLP_ENDPOINThttp://localhost:4317 export MEGATRON_OTEL_SPAN_GROUPSdefault # 粗粒度 span生产安全 torchrun --nproc_per_node8 pretrain_gpt.py ...MEGATRON_OTEL_ENABLED是总开关默认0必须置1才激活它是NEMO_LENS_ENABLED的别名二者指向同一底层配置。指标上报通过MEGATRON_OTEL_METRICS_ENABLED默认1独立控制可单独关闭而保留 traces。默认只有最后一个 rank导出single_rank策略MEGATRON_OTEL_EXPORT_RANK-1表示最后一个 rank。如需多 rank 上报可切换all_ranks、sampled、first_rank_per_node等策略。本地调试时可将MEGATRON_OTEL_EXPORTERconsolespan 与指标直接打印到 stdout无需任何后端。开启后配合 Prometheus Grafana 即可对 loss、吞吐TFLOP/s/GPU 与 tokens/s、梯度范数、学习率、显存峰值进行实时监控并通过nemo.run.id在多次实验间做横向对比——这套指标体系与 docs/user-guide/observability/span-groups.md 中的 trace 体系共同构成了 Megatron 训练任务完整的可观测性闭环。【免费下载链接】Megatron-LMOngoing research training transformer models at scale项目地址: https://gitcode.com/GitHub_Trending/me/Megatron-LM创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考