article

README

Dynatrace

我们使用 Dynatrace Managed 作为我们的可观测性解决方案。本文档提供了使用 Dynatrace Managed MCP 从 Dynatrace 检索 EasyTrade 系统数据的说明。

最佳实践

始终使用特定的时间范围，保持范围狭窄（例如 now-1h、now-24h），以避免大的数据查询。
对于实体选择器，考虑使用标签标准进行更精确的过滤（如果理解标签策略和命名）。

easytrade 的实体选择器

考虑在 entitySelector 中使用这些标准来过滤我们 easytrade 应用程序的数据：

服务：

type(SERVICE),entityName.contains("easytrade")
type(SERVICE),tag("app:easytrade")

进程组和容器：

type(PROCESS_GROUP),entityName.contains("easytrade")
type(CONTAINER_GROUP_INSTANCE),entityName.contains("easytrade")

主机：

type(HOST),tag("environment:production"),tag("app:easytrade")

AWS Lambda 函数：

type(AWS_LAMBDA_FUNCTION),entityName.contains("easytrade")
type(AWS_LAMBDA_FUNCTION),tag("AWS_REGION:us-west-2"),tag("app:easytrade")


### 环境变量
#### 配置变量
- **`DT_CONFIG_FILE`**（可选）：配置文件（JSON 或 YAML）的路径。**推荐用于本地开发**。
  - 支持相对路径（例如 `./dt-config.yaml`）
  - 支持绝对路径（例如 `/etc/dynatrace/config.yaml`）
  - 支持 `~` 扩展（例如 `~/dt-config.yaml`）
  - 支持文件内容中的环境变量插值 (`${VAR_NAME}`)
  - 示例：`DT_CONFIG_FILE=./dt-config.yaml`

- **`DT_ENVIRONMENT_CONFIGS`**（可选）：包含环境配置的 JSON 字符串。**适用于 Kubernetes/Docker**。
  - 如果 `DT_CONFIG_FILE` 未设置，则使用此变量
  - 必须是有效的 JSON 数组
  - 示例：`DT_ENVIRONMENT_CONFIGS='[{"apiEndpointUrl":"...","environmentId":"...","alias":"...","apiToken":"..."}]'`

> **注意**：如果同时设置了 `DT_CONFIG_FILE` 和 `DT_ENVIRONMENT_CONFIGS`，`DT_CONFIG_FILE` 优先。

#### 日志变量
- `LOG_LEVEL`（可选）：日志详细程度级别（例如 debug、info、warn、error）。默认：`info`
- `LOG_OUTPUT`（可选）：日志输出目标。默认：`file`
  - `file`：将日志写入文件（默认行为）
  - `stdout` / `console`：将日志写入标准输出（⚠️ **仅适用于 stdio 传输**：stdio 用于 MCP 协议 - 请使用 `stderr-all` 代替）
  - `stderr`：将错误和警告写入标准错误（info/debug 被抑制）
  - `stderr-all`：将所有日志级别写入标准错误（✅ **推荐用于使用 stdio 传输的 VS Code**）
  - `file+console` / `file+stdout`：将日志写入文件和标准输出（⚠️ **仅适用于 stdio 传输**：stdio 用于 MCP 协议 - 请使用 `stderr-all` 代替）
  - `file+stderr`：将日志写入文件，将错误/警告写入标准错误
  - `disabled`：完全禁用日志记录
- `LOG_FILE`（可选）：当 `LOG_OUTPUT` 包含 `file` 时，日志文件的路径。默认：当前工作目录中的 `dynatrace-managed-mcp.log`

> [!IMPORTANT]
> **为你的设置选择正确的 LOG_OUTPUT：**
>
> - **stdio 传输（默认）**：使用 `LOG_OUTPUT=stderr-all` 或 `LOG_OUTPUT=file`（默认）
>   - ❌ `LOG_OUTPUT=console` 不起作用 - stdout 用于 MCP 协议
>   - ✅ `LOG_OUTPUT=stderr-all` 在 VS Code 的输出面板中显示所有日志
>   - ✅ `LOG_OUTPUT=file` 写入日志文件（使用 `tail -f dynatrace-managed-mcp.log` 查看）
> - **HTTP 传输 (`--http` 模式)**：任何 `LOG_OUTPUT` 选项都可以
>   - ✅ `LOG_OUTPUT=console` 在终端中可见
>   - ✅ `LOG_OUTPUT=stderr-all` 在终端中可见
>   - ✅ `LOG_OUTPUT=file` 写入日志文件

**日志记录示例：**
```bash
# 使用 stdio 传输的 VS Code - 在输出面板中查看日志
LOG_OUTPUT=stderr-all LOG_LEVEL=debug

# 使用 stdio 传输的 VS Code - 写入文件（默认）
LOG_LEVEL=debug
# 使用以下命令查看：tail -f dynatrace-managed-mcp.log

# HTTP 传输 - 日志记录到控制台
LOG_OUTPUT=console LOG_LEVEL=debug node dist/index.js --http

# HTTP 传输 - 日志记录到文件和控制台
LOG_OUTPUT=file+console LOG_LEVEL=debug node dist/index.js --http

# 日志记录到自定义文件路径
LOG_OUTPUT=file LOG_FILE=/var/log/dynatrace-mcp.log node dist/index.js

# 完全禁用日志记录（不推荐）
LOG_OUTPUT=disabled node dist/index.js

速率限制变量

DT_MCP_RATE_LIMIT_MAX_CALLS（可选）：速率限制窗口内允许的最大工具调用次数。默认：20
DT_MCP_RATE_LIMIT_WINDOW_MS（可选）：速率限制窗口大小（毫秒）。默认：20000（20 秒）

示例：允许每 30 秒进行 50 次调用：

DT_MCP_RATE_LIMIT_MAX_CALLS=50
DT_MCP_RATE_LIMIT_WINDOW_MS=30000

多环境配置字段

在 DT_ENVIRONMENT_CONFIGS 变量中，数组的每个元素必须包含每个环境的以下所有字段：

dynatraceUrl：Dynatrace Managed 仪表盘的基础 URL，环境 ID 将附加到该 URL 后面（例如 https://dmz123.dynatrace-managed.com）。如果未指定，将默认为 DT_API_ENDPOINT_URL 的值。
apiEndpointUrl（必需）：Dynatrace Managed API 的基础 URL，环境 ID 将附加到该 URL 后面（例如 https://abc123.dynatrace-managed.com:9999）
environmentId（必需）：托管环境的 ID，用于构建 API 和仪表盘的 URL（例如 01234567-89ab-cdef-abcd-ef0123456789 形式）
alias：环境的友好/易读名称，在与大语言模型区分环境时很有用
apiToken（必需）：具有所需作用域的 API 令牌（见身份验证）
httpProxyUrl（可选）：企业环境的 HTTP 代理，用于路由流量（例如 http://proxy.company.com:8080）
httpsProxyUrl（可选）：企业环境的 HTTPS 代理，用于路由流量（例如 https://proxy.company.com:8080）

代理配置 MCP 服务器会遵循你为每个 Dynatrace Managed 环境配置的企业环境系统代理设置：

httpProxyUrl（可选，字符串，例如 http://proxy.company.com:8080） - HTTPS 请求的代理服务器 URL；或
httpsProxyUrl（可选，字符串，例如 http://proxy.company.com:8080） - HTTP 请求的代理服务器 URL

带有代理的示例配置：

export DT_ENVIRONMENT_CONFIGS='[
    {
        "dynatraceUrl": "https://my-dashboard-endpoint.com/",
        "apiEndpointUrl": "https://my-api-endpoint.com/",
        "environmentId": "my-env-id-1",
        "alias": "alias-env",
        "apiToken": "my-api-token",
        "httpProxyUrl": "http://proxy.company.com:8080"
    },
    {
        "dynatraceUrl": "https://my-dashboard2-endpoint.com/",
        "apiEndpointUrl": "https://my-api2-endpoint.com/",
        "environmentId": "my-env-id-2",
        "alias": "alias-env-2",
        "apiToken": "my-api-token-2",
        "httpProxyUrl": "http://proxy.company.com:8080"
    }
]'

请注意，httpProxyUrl/httpsProxyUrl 变量是针对每个环境的，因此你可以配置一个环境使用代理，而其他环境可能不需要。

身份验证

Dynatrace Managed 使用基于 API 令牌的身份验证。在你的托管集群中创建一个具有所需作用域的 API 令牌（见下一小节）。有关在托管部署中创建 API 令牌的更多信息，请参考 Dynatrace Managed 文档。

托管部署的 API 作用域

你的 API 令牌必须包含以下作用域才能实现完整功能： 必需作用域：

读取审计日志 (auditLogs.read)
读取实体 (entities.read)
读取事件 (events.read)
读取日志 (logs.read)
读取指标 (metrics.read)
读取网络区域 (networkZones.read)
读取问题 (problems.read)
读取安全问题 (securityProblems.read)
读取 SLO (slo.read)

注意：托管部署中的 API 令牌作用域与 SaaS 平台令牌不同。请确保为你的托管集群版本选择正确的作用域。

与 SaaS Dynatrace MCP 的主要区别

此 MCP 适用于 Dynatrace Managed 平台。有一个不同的 Dynatrace MCP 服务器用于 Dynatrace SaaS。主要区别包括：

Dynatrace SaaS MCP 使用 DQL，而 Dynatrace Managed 使用 v2 API
Dynatrace SaaS MCP 使用 Davis CoPilot，而 Dynatrace Managed 不使用
Dynatrace SaaS MCP 使用 OAuth，而 Dynatrace Managed 使用 API 令牌

同时使用 Dynatrace SaaS MCP 和 Dynatrace Managed MCP 的混合设置

此托管 Dynatrace MCP 可以与 SaaS Dynatrace MCP 一起运行，以实现自托管和 SaaS Dynatrace 环境之间的混合设置。如果你以混合方式运行应用程序，这可能很有用，它也支持迁移场景，即你已迁移到 Dynatrace SaaS，但仍有历史数据保留在托管平台上且不打算迁移。在这种情况下，你的 MCP 客户端可以配置为同时与两个 MCP 服务器通信，从而使你能够跨 SaaS 和托管数据进行查询。

要设置此配置，你应该：

按照上述说明设置此 Dynatrace Managed MCP 服务器
按照 Dynatrace SaaS MCP 的说明进行设置，确保在 MCP 配置文件中为两个服务器指定不同的名称
在你的 AI 助手中确认已连接到两个服务器
（可选，但推荐）为你的 AI 助手设置规则或指导，以便明确指导其使用两个 MCP

配置好两个 MCP 服务器后，你可以提出问题，MCP 客户端应将问题传递给正确的 MCP 服务器（或在适当情况下传递给两个服务器）。

请注意，如果不为 MCP 客户端包含规则或指导，诸如 要求 Dynatrace 列出过去 24 小时内的应用程序问题 之类的查询可能会使用一个 MCP 服务器或两个服务器，具体取决于上下文窗口中的内容。如果你选择这样做，请确保你的命令非常具体，例如 要求 Dynatrace 列出我托管环境中过去 24 小时内的应用程序问题。

规则/指导

AI 助手通常支持规则文件以提供使用指导（有关配置信息，请参阅规则文件）。如果你在混合设置中同时使用此 MCP 服务器和 SaaS MCP 服务器，并且/或者你有多个托管环境，建议在配置中添加此内容，以防止 AI 助手使用错误的 MCP 或产生混淆。你的指导规则将根据你的设置而有所不同，但以下是一些推荐的模板作为起点。你可以根据需要编辑这些模板，并包含特定于你的环境的额外上下文。

多个托管环境

在此示例中，你设置了多个 Dynatrace Managed 环境。这可能是开发/测试/生产环境设置，或者是一组完全不同的应用程序。建议使用 DT_ENVIRONMENT_CONFIGS 中 alias 字段使用的相同别名来引用你的环境，以避免混淆。

# Dynatrace

- 我有三个独立的 Dynatrace 环境：
   1. "production" 是一个自托管的 Dynatrace Managed 环境。它包含我的生产环境的数据，其问题和故障应优先于任何其他环境，因为这是面向客户的。它通过名为 dynatrace-managed-mcp-server 的 Dynatrace Managed MCP 访问。
   2. "test" 是一个自托管的 Dynatrace Managed 环境。它包含我的测试环境的数据，用于在代码进入生产之前进行准备。它通过名为 dynatrace-managed-mcp-server 的 Dynatrace Managed MCP 访问。
   3. "development" 是一个自托管的 Dynatrace Managed 环境。它包含我的开发环境的数据，这是我优先级最低的环境。它通过名为 dynatrace-managed-mcp-server 的 Dynatrace Managed MCP 访问。
- 注意使用哪个环境。如果不清楚，请询问使用哪个环境。
- 必须向用户明确说明数据来自哪个环境。

带有迁移日期的混合设置

在此示例中，你已从托管环境迁移到 SaaS 环境，但自托管的 Managed 环境中仍有历史数据。你希望你的 AI 助手了解数据的存储位置。这将使其能够知道针对你请求的日期范围应针对哪些环境，例如 显示过去 7 天内的所有 Dynatrace 问题 可能需要来自两个环境的数据（因此使用两个 MCP 服务器），或者可能仅存在于 Dynatrace SaaS 中。

# Dynatrace

- 我有两个独立的 Dynatrace 环境：
   1. Dynatrace Managed 是自托管的。它仅包含 2025 年 11 月 29 日之前的历史数据。它通过名为 dynatrace-managed-mcp-server 的 Dynatrace Managed MCP 访问。
   2. Dynatrace SaaS 用于所有实时数据。它通过名为 dynatrace-saas-mcp-server 的 Dynatrace SaaS MCP 访问。
- 注意使用哪个 MCP。如果不清楚，请询问使用哪个 MCP。
- 必须向用户明确说明数据是来自 Dynatrace Managed 还是 Dynatrace SaaS。

同时运行的混合设置

在此示例中，你使用 Dynatrace Managed 管理部分应用程序，使用 Dynatrace SaaS 管理其他应用程序，并希望你的 MCP 客户端了解每个应用程序的数据位置。

# Dynatrace

- 我有两个独立的 Dynatrace 环境，都包含实时数据：
   1. Dynatrace Managed 是自托管的。它仅包含我的部分系统的可观测性数据，主要是书店系统。它通过名为 dynatrace-managed-mcp-server 的 Dynatrace Managed MCP 访问。
   2. Dynatrace SaaS 用于我的所有其他系统的可观测性。它通过名为 dynatrace-saas-mcp-server 的 Dynatrace SaaS MCP 访问。
- 注意使用哪个 MCP。如果不清楚，请询问使用哪个 MCP。
- 必须向用户明确说明数据是来自 Dynatrace Managed 还是 Dynatrace SaaS。

🔧 技术细节

示例提示

你可以从简单的提示开始，如 "要求 Dynatrace 列出问题"，并参考示例进行更复杂的查询。

故障排除

身份验证问题

在大多数情况下，身份验证问题源于缺少作用域或无效的令牌。请确保你已添加上述所有必需的作用域。遇到错误时，你可以要求 AI 助手提供 MCP 返回的准确错误信息。对于启动问题，请检查 AI 助手日志。你也可以直接运行 MCP 以查看启动时是否报告错误：

npx @dynatrace-oss/dynatrace-managed-mcp-server@latest

遥测

Dynatrace MCP 服务器通过 Dynatrace OpenKit 发送遥测数据，以帮助改进产品。这包括：

服务器启动事件
工具使用情况（调用了哪些工具、成功/失败、执行持续时间）
错误跟踪，用于调试和改进

隐私和退出选项：

遥测 默认启用，但可以通过设置 DT_MCP_DISABLE_TELEMETRY=true 禁用
不会跟踪你的 Dynatrace 环境中的敏感数据
仅收集匿名使用统计信息和错误信息
使用统计信息和错误数据将传输到 Dynatrace 的分析端点

配置选项：

DT_MCP_DISABLE_TELEMETRY（布尔值，默认：false） - 禁用遥测
DT_MCP_TELEMETRY_APPLICATION_ID（字符串，默认：dynatrace-managed-mcp） - 用于跟踪的应用程序 ID
DT_MCP_TELEMETRY_ENDPOINT_URL（字符串，默认：Dynatrace 端点） - OpenKit 端点 URL
DT_MCP_TELEMETRY_DEVICE_ID（字符串，默认：自动生成） - 用于跟踪的设备标识符

要禁用使用跟踪，请在配置中添加以下内容：

DT_MCP_DISABLE_TELEMETRY=true

dynatrace-managed-mcp