dt-obs-extensions

Dynatrace 扩展技能

概述

Dynatrace 扩展可通过与外部系统和自定义数据源集成，扩展 Dynatrace 的功能。

适用场景：

• 检查已安装扩展的状态及其监控配置
• 使用 DQL 查询和事件日志排查扩展配置问题

扩展生命周期

扩展首先需要安装，安装后会引入资源（仪表板、告警模板、OpenPipeline 规则等）。安装后，每个扩展都可以有多个激活项——监控配置。配置可以在 ActiveGate 或 OneAgent 上运行，并可单独启用或禁用。每个配置都有自己的状态，可使用此技能进行查询。

扩展监控配置和状态

扩展状态

要检查扩展的状态，可以运行以下 DQL 查询：

timeseries count(dt.sfm.extension.config.status), by: {dt.extension.name, dt.extension.config.id, dt.extension.status}

• dt.extension.name — 扩展名称
• dt.extension.config.id — 监控配置 ID
• dt.extension.status — 当前状态值

2. 获取扩展事件日志

如果状态不是 OK，请获取详细日志：

fetch dt.system.events
| filter dt.extension.name == "<extension_name>" AND dt.extension.config.id == "<config_id>"

请在 content 字段中查找错误代码。错误代码格式为 DEC:[A-Z0-9_]+。

→ 要了解错误代码的含义及修复方法，请在 references/extensions-error-codes.md 中搜索确切代码（参见错误代码参考）。

---

扩展状态参考

状态	含义	修复方法
OK	运行正常	无需处理
STARTUP / STARTUP_PENDING / STARTUP_SCHEDULED	扩展正在启动	等待启动完成
RESTART / TIMED_OUT_RESTART	扩展正在重启	持续监控；如果反复发生，请检查日志
IDLE	正在工作，但未生成状态	通常是暂时性的
WARNING	警告状态	检查扩展日志
GENERIC_ERROR	错误状态	检查扩展日志
STARTUP_ERROR	启动期间出错	检查扩展日志和配置
HIGH_CPU / HIGH_CPU_RESTART	CPU 使用率过高	在 ActiveGate 设置中切换 Performance Profile
HIGH_MEMORY / HIGH_MEMORY_RESTART	内存使用率过高	在 ActiveGate 设置中切换 Performance Profile
EEC_HARD_LIMIT_REJECTION / EEC_HARD_LIMIT_RESTART	达到资源硬限制	在 ActiveGate 设置中切换 Performance Profile
EEC_RESTSERVER_ERROR	REST API 端口冲突	检查主机上的端口冲突
EXTENSIONS_CACHE_ERROR	无法下载扩展	检查 ActiveGate/OneAgent 上的磁盘空间
EXTENSION_VERIFICATION_ERROR	extension.yaml 格式错误	验证 extension.yaml 语法
CUSTOM_CODE_EXTENSION_NOT_ALLOWED	自定义代码被阻止	更新 ActiveGate 或 OneAgent
INCOMPATIBLE_API_ERROR	API 版本不匹配	更新 ActiveGate/OneAgent，或查看扩展文档
MAX_TASKS_LIMIT_REJECTION	任务过多	向组中添加 ActiveGate，或拆分组
MISSING_BINARY / MISSING_DATASOURCE	安装格式错误	重新安装 ActiveGate 或 OneAgent
GROUP_NAME_CHANGE	临时重新平衡	等待重新平衡完成

---

故障排查

常见问题

1. 扩展程序显示非 OK 状态

   • 运行上方的状态查询，找出具体的状态代码
   • 查看状态参考表以了解解决方法
   • 如果不清楚，请获取扩展程序的事件日志

2. 事件日志中出现错误代码

   • 错误代码遵循 DEC:[A-Z0-9_]+ 模式
   • 在 references/extensions-error-codes.md 中搜索该代码（见下方的错误代码参考）
   • 如果没有错误代码，请阅读事件的 content 了解详情

3. 扩展程序不断重启

   • 检查是否存在 HIGH_CPU_RESTART、HIGH_MEMORY_RESTART 或 TIMED_OUT_RESTART
   • 在 ActiveGate 设置中切换到更高的性能配置文件
   • 检查扩展程序配置是否覆盖范围过大

4. 扩展程序未生成数据

   • 确认状态为 OK（而不是 IDLE 或错误状态）
   • 检查监控配置是否已启用
   • 确认与受监控系统的网络连接正常

---

错误代码参考

references/extensions-error-codes.md 是一个大型生成文件。每个条目的结构如下：

## Error Code DEC:<code>

### Error Description: <description>

### Suggestions:

1. ...

请勿加载整个文件。 在 references/extensions-error-codes.md 中搜索具体的错误代码标题（例如 ## Error Code DEC:1D6），并阅读接下来的约 50 行。到下一个 ## Error Code 标题处停止。

---

参考资料

• extensions-error-codes.md — DEC 错误代码完整列表，包含说明和故障排除步骤