使用说明

动态跟踪观察性助手

AI驱动的可观察性助手，结合了 GitHub Copilot LLMs （或 人类模型), 动态跟踪MCP （模型上下文协议）， dtctl命令行界面，以及 Dynatrace域技能 将其整合为一个单一的web应用程序，用于Dynatrace环境的智能、证据驱动的调查和管理。

它做什么

助理充当 Dynatrace的代理AI副驾驶。它可以：

查询实时可观察性数据 --通过Dynatrace MCP服务器实时获取日志、指标、跟踪、问题和实体拓扑。
执行DQL查询 --使用来自领域技能的内置语法指导生成和运行Dynatrace查询语言查询。
管理Dynatrace配置 --通过dtctl创建、修改和检查工作流、仪表板、笔记本、SLO和设置。
分析上传的上下文 --摄取配置文件、日志或数据导出，并与实时遥测一起对其进行推理。
分类事件 --遵循结构化工作流程（问题→ 影响→ 痕迹→ 根本原因→ 补救），并在每个步骤调用工具。
提供领域专业知识 --加载涵盖17个Dynatrace域（DQL、服务、前端、跟踪、主机、Kubernetes、AWS、Azure、GCP、日志、问题、预测分析、警报、仪表板、笔记本电脑、JS运行时和实体迁移）的按需技能包，每个域都有详细的参考文件。

LLM在一个 代理工具调用循环 （每条消息最多10轮），自主决定调用哪些工具——用于实时数据的MCP、用于配置的dtctl和用于领域知识的技能——然后将结果合成为实时流式传输的连贯响应。

建筑

┌─────────────────────────────────────────────────────────────────────┐
│                        Frontend (React + Vite + Tailwind)           │
│  ┌────────────┐  ┌────────────────┐  ┌───────────────────────────┐ │
│  │ Left Panel  │  │  Chat Panel    │  │  Right Panel              │ │
│  │ • Prompts   │  │  • Messages    │  │  • dtctl status & login   │ │
│  │ • Context   │  │  • SSE stream  │  │  • Telemetry config       │ │
│  │   files     │  │  • Tool calls  │  │  • MCP connection         │ │
│  │ • Model     │  │  • Markdown    │  │  • Model selection        │ │
│  │   selector  │  │  • MCP log     │  │                           │ │
│  └────────────┘  └────────────────┘  └───────────────────────────┘ │
│                      Zustand (auth + chat stores)                   │
└──────────────────────────┬──────────────────────────────────────────┘
                           │ HTTP + SSE
┌──────────────────────────┴──────────────────────────────────────────┐
│                       Backend (Fastify + TypeScript)                │
│                                                                     │
│  Routes                        Services                             │
│  ├─ /api/auth/*    GitHub OAuth ├─ Session store (in-memory)        │
│  ├─ /api/chat/stream  SSE chat  ├─ MCP client (JSON-RPC 2.0)        │
│  ├─ /api/context/* file upload  ├─ MCP context builder (96k budget) │
│  ├─ /api/dynatrace/* MCP proxy  ├─ dtctl service (binary mgmt)      │
│  ├─ /api/dtctl/*   CLI mgmt    ├─ Skills service (13 skills)        │
│  ├─ /api/models    model list   └─ System instructions engine       │
│  └─ /api/telemetry OTel config                                      │ 
│                                                                     │
│  ┌────────────────── Agentic Tool Loop (max 10 rounds) ──────────┐  │
│  │  LLM ←→ load_dynatrace_skill ←→ dtctl_run ←→ MCP tools        │   │
│  │       ←→ load_dynatrace_skill_reference ←→ dtctl_context_info │  │
│  └───────────────────────────────────────────────────────────────┘  │
│                                                                     │
│  OpenTelemetry (GenAI semconv → OTLP → Dynatrace)                   │
└─────────────────────────────────────────────────────────────────────┘
         │                          │                      │
         ▼                          ▼                      ▼
  GitHub Copilot API       Dynatrace MCP Server       dtctl binary
  or Anthropic API
  (LLM inference)          (live observability)       (config mgmt)

双平面设计

平面	通道	用途	示例
运行时	Dynatrace MCP	实时可观察性查询和分析	获取日志、列表问题、查询指标、跟踪跨度
管理	dtctl CLI	配置更改和资源清册	创建仪表板、编辑工作流、应用设置、列出笔记本

LLM的系统指令对 路线决策图 因此，它会自动为每个任务选择正确的平面。

特征

核心聊天

流媒体响应 -来自GitHub Copilot API或Anthropic消息API的实时SSE，带有delta、tool-call和MCP-流量事件
模型选择 -GPT-4o、GPT-4o-Mini、Claude Sonnet 4、o3-Mini（Copilot API动态列表）或人类模型（Claude Opus 4、Sonnet 4和Haiku等）
代理工具调用 --多轮循环（最多10次迭代），LLM自主调用工具并对结果进行推理
Markdown渲染 --完全支持GFM，语法突出显示代码块

Dynatrace MCP集成

连接到任何Dynatrace MCP服务器 --UI中的URL+承载令牌配置
自动工具发现 --MCP工具被列出并注册为LLM函数调用
实时MCP活动日志 --可扩展的每条消息日志，显示发送/接收的工具流量

dtctl CLI集成

自动安装 --一键下载dtctl v0.18.0二进制文件（检测到平台/arch）
OAuth登录 --基于浏览器的SSO流，用于在Dynatrace环境中进行身份验证
安全命令执行 --写入操作需要明确确认；防止注射（无分号、管道、回扣）
情境感知 --飞行前检查(dtctl_context_info)在任何状态更改命令之前

Dynatrace域名技能

17领域技能 LLM通过工具调用按需加载：

技能	领域
`dt-dql-essentials`	DQL语法、函数、陷阱、优化
`dt-obs-services`	服务RED指标，特定于运行时的遥测（.NET、Java、Node.js、Python、PHP、Go）
`dt-obs-frontends`	RUM、Web Vitals、用户会话、移动端、前端错误
`dt-obs-tracing`	分布式跟踪、跨度、故障检测、性能
`dt-obs-hosts`	主机/进程指标——CPU、内存、磁盘、容器
`dt-obs-kubernetes`	集群、Pod、节点、工作负载、存储、网络
`dt-obs-aws`	EC2、RDS、Lambda、ECS/EKS、VPC、成本优化
`dt-obs-azure`	虚拟机、SQL数据库、存储、AKS、应用服务、功能、Direct3D
`dt-obs-gcp`	计算引擎、GKE、云运行、发布/订阅、VPC、IAM
`dt-obs-logs`	日志查询、过滤、模式分析、相关性
`dt-obs-problems`	问题、RCA、影响分析、问题相关性
`dt-obs-predictive-analytics`	预测、容量规划、异常/趋势检测
`dt-alerting`	异常检测器、Davis事件、工作流通知
`dt-app-dashboards`	仪表板创建、图块、变量、可视化
`dt-app-notebooks`	笔记本创建、分区、分析工作流程
`dt-js-runtime`	Dynatrace服务器端JS运行时，@Dynatrace sdk/*目录
`dt-migration`	经典实体→ Smartscape迁移模式

250+参考文件 对于深度子主题（例如，单个DQL函数类别、运行时特定指标、SDK API文档、实体迁移模式），可通过 load_dynatrace_skill_reference

上下文管理

文件上传 --JSON、YAML、TXT、CSV、MD、LOG、XML、Python、JS/TS、Dockerfile、.env（最多20个文件，总共12 MB，每个文件5 MB）
智能上下文预算 --96k令牌系统上下文，每个文件截断（60k令牌），预算警告为80%
自定义系统提示 --覆盖或增强默认系统指令

身份验证和安全

双身份验证提供者 -GitHub OAuth设备流或Anthropic API密钥登录
8小时课程 --带有httpOnly签名Cookie的内存会话存储
后端代理 -Dynatrace API令牌保持服务器端（从不向浏览器公开）
速率限制 --每个客户端每分钟100个请求
安全标头 --头盔（CSP、HSTS等）+每个环境的CORS
文件验证 --扩展白名单、大小限制、二进制拒绝

可观测性（开放遥测）

GenAI语义约定 --每个LLM调用和工具执行都会发出带有输入/输出令牌、模型、完成原因、工具参数和结果的OTel跨度
OTLP导出到Dynatrace --跟踪和指标发送到任何与OTLP兼容的后端
运行时重新配置 --在不重新启动服务器的情况下，从UI更改OTLP终结点和令牌
连接测试 --在提交配置更改之前验证OTLP连接

预定义提示

按类别组织的一键提示：

类别	提示
动态追踪	列出活动问题、主机运行状况概述、服务性能、最近的错误日志、SLO状态、最近的部署
上下文	分析上传的上下文，解释配置
dtctl	检查上下文、列出工作流、列出仪表板、健康检查（医生）、DQL查询、列出笔记本

先决条件

Node.js 20+
GitHub OAuth应用程序 — 在此处创建一个 （适用于GitHub提供商）
GitHub Copilot许可证 对GitHub帐户进行身份验证 （适用于GitHub提供商）
人类API密钥 （备选方案——适用于Anthropic提供者）
Dynatrace环境 （可选）--用于MCP和dtctl集成

快速开始

1.克隆和配置

git clone <repo-url>
cd DEMO_MCP_DT
cp .env.example .env

编辑 .env 使用您的凭据：

# Required — GitHub OAuth App
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

# Optional — OpenTelemetry export to Dynatrace
OTEL_EXPORTER_OTLP_ENDPOINT=https://<env-id>.live.dynatrace.com/api/v2/otlp
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Api-Token <your-token>

2.安装依赖项

npm run install:all

3.开始开发

npm run dev

服务	URL
前端（Vite）	http://localhost:5173
后端（禁食）	http://localhost:3001

4.身份验证

选项A-GitHub（Copilot模型）：

在浏览器中打开前端。
点击 使用 GitHub 登录 --显示设备代码。
打开GitHub验证URL，输入代码并授权。
应用程序轮询令牌并开始会话。

选项B——人体模型（克劳德模型）：

切换到人类登录屏幕上的选项卡。
输入您的Anthropic API键。
点击 使用Anthropic登录 --密钥已验证，会话开始。

5.连接到Dynatrace（可选）

通过MCP服务器：

在右侧面板中，输入您的Dynatrace MCP服务器URL和承载令牌。
点击连接 --可用工具会自动列出。

通过dtctl：

在右侧面板中，单击 安装dtctl （自动下载二进制文件）。
点击登录并输入您的Dynatrace环境URL。
完成基于浏览器的SSO流程。

GitHub OAuth设置

首选 GitHub开发人员设置→ OAuth应用程序
创建新的OAuth应用程序：
- 应用程序名称：动态跟踪观察性助手
- 首页网址: http://localhost:5173
- 授权回调URL: http://localhost:5173
复制 客户端ID 和 客户端密钥 进入你的 .env 文件。

环境变量

变量	默认值	描述
`GITHUB_CLIENT_ID`	—	必修的。 GitHub OAuth应用程序客户端ID
`GITHUB_CLIENT_SECRET`	—	必修的。 GitHub OAuth应用程序客户端密码
`PORT`	`3001`	服务器侦听端口
`NODE_ENV`	`development`	`development` 或 `production`
`LOG_LEVEL`	`info`	Pino日志级别(`debug`, `info`, `warn`, `error`)
`COOKIE_SECRET`	自动生成	Cookie签名密钥（未设置时随机）
`ALLOWED_ORIGIN`	--	CORS生产来源（例如。， `https://myapp.example.com`)
`OTEL_SERVICE_NAME`	`dynatrace-observability-assistant`	OpenTetry服务名称
`OTEL_SERVICE_VERSION`	`1.0.0`	OpenTetry服务版本
`OTEL_EXPORTER_OTLP_ENDPOINT`	--	OTLP端点（例如。， `https://<env>.live.dynatrace.com/api/v2/otlp`)
`OTEL_EXPORTER_OTLP_HEADERS`	--	OTLP认证头（例如。， `Authorization=Api-Token dt0c01...`)

Docker 部署

该项目包括一个多阶段的Dockerfile，用于优化生产构建。

构建并运行

docker compose up --build

该应用程序可在 http://localhost:3000.

Docker构建的功能是什么

阶段	目的
建造者	安装所有依赖项，构建Vite客户端，编译TypeScript服务器
生产	仅将生产依赖项+内置工件复制到精简版中 `node:20-alpine` 图像（约150 MB）

docker-compose.yml

services:
  mcp-chat:
    build: .
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      - GITHUB_CLIENT_ID=${GITHUB_CLIENT_ID}
      - GITHUB_CLIENT_SECRET=${GITHUB_CLIENT_SECRET}
      - COOKIE_SECRET=${COOKIE_SECRET}
    restart: unless-stopped

生产注意事项

会话存储 --对于多实例部署，用Redis替换内存中的会话存储。
跨域资源共享 --设置 ALLOWED_ORIGIN 到您的生产领域。
秘密 --使用秘密管理器；不要承诺 .env 文件夹。
遥测 --设置 OTEL_EXPORTER_OTLP_ENDPOINT 和 OTEL_EXPORTER_OTLP_HEADERS 用于跟踪/度量导出。

项目结构

├── client/                          # React frontend (Vite + Tailwind)
│   └── src/
│       ├── components/
│       │   ├── ChatLayout.tsx       # 3-panel layout shell
│       │   ├── ChatPanel.tsx        # Chat messages, SSE consumer, markdown
│       │   ├── LeftPanel.tsx        # Prompts, file uploads, model selector
│       │   ├── RightPanel.tsx       # dtctl, telemetry, MCP config
│       │   └── LoginScreen.tsx      # GitHub + Anthropic login UI
│       ├── stores/
│       │   ├── auth.ts             # Authentication state (Zustand)
│       │   └── chat.ts            # Chat, context, MCP, dtctl state (Zustand)
│       └── main.tsx
├── server/                          # Fastify backend (TypeScript)
│   └── src/
│       ├── config/
│       │   └── env.ts              # Environment variable parsing
│       ├── instructions/
│       │   ├── system-instructions.md   # LLM system prompt (routing, safety, workflows)
│       │   └── skills/             # 17 domain skills + 250+ reference files
│       │       ├── dt-dql-essentials.md
│       │       ├── dt-dql-essentials/   # 31 DQL reference files
│       │       ├── dt-obs-services.md
│       │       ├── dt-obs-services/     # 7 runtime-specific refs
│       │       ├── dt-js-runtime/       # 122 SDK reference files
│       │       ├── ...                  # (one .md + directory per skill)
│       │       └── dt-migration/        # 17 migration reference files
│       ├── routes/
│       │   ├── auth.ts             # GitHub OAuth + Anthropic API key auth
│       │   ├── chat.ts             # SSE streaming + agentic tool loop (GitHub & Anthropic)
│       │   ├── context.ts          # File upload/download/budget
│       │   ├── dtctl.ts            # dtctl install/login/exec
│       │   ├── dynatrace.ts        # MCP server connect/tools
│       │   ├── models.ts           # LLM model listing
│       │   └── telemetry.ts        # OTel config management
│       ├── services/
│       │   ├── dtctl.ts            # dtctl binary management + command execution
│       │   ├── dtctl-skill.ts      # System instructions loader
│       │   ├── mcp-client.ts       # MCP JSON-RPC 2.0 client
│       │   ├── mcp-context.ts      # Context aggregation + budget management
│       │   ├── session.ts          # In-memory session store (8h TTL, multi-provider)
│       │   └── skills.ts           # Skill catalog (17 skills), loader, reference loader
│       ├── telemetry.ts            # OpenTelemetry SDK setup + runtime reconfig
│       ├── semconv.ts              # GenAI semantic convention constants
│       └── index.ts                # Entry point
├── shared/                          # Shared TypeScript types
│   └── src/index.ts                # ChatMessage, ContextPayload, MCPConfig, etc.
├── Dockerfile                       # Multi-stage production build
├── docker-compose.yml
└── package.json                     # Root workspace scripts

运作原理

代理聊天流

User sends message
       │
       ▼
  Build system context
  (instructions + skills catalog + files + DT data)
       │
       ▼
  Truncate to 96k-token budget
       │
       ▼
  ┌─── Tool loop (up to 10 rounds) ──────────────────┐
  │                                                    │
  │  Send messages + tools → GitHub Copilot API / Anthropic API        │
  │       │                                            │
  │       ▼                                            │
  │  Stream response (SSE deltas to browser)           │
  │       │                                            │
  │  finish_reason = tool_calls?                       │
  │       │ YES                    │ NO                │
  │       ▼                        ▼                   │
  │  Dispatch each tool call    Done — send 'done' SSE │
  │  ┌─ load_dynatrace_skill                          │
  │  ├─ load_dynatrace_skill_reference                │
  │  ├─ dtctl_run / dtctl_context_info                │
  │  └─ MCP tool (via JSON-RPC)                       │
  │       │                                            │
  │  Add tool results to messages                      │
  │  Continue loop ───────────────────────────────────┘
  │                                                    │
  └────────────────────────────────────────────────────┘

背景预算

系统上下文（作为第一条消息发送到LLM）由以下内容组装而成：

系统说明 （约6k个令牌）--路由规则、安全协议、DQL指南、工作流程、技能目录
用户系统提示 （可选）--来自上下文面板的自定义说明
上传文件 --每个文件截断为6万个代币，总预算为9.6万个代币
动态跟踪数据 -来自MCP或上下文API的JSON有效负载

当使用量超过预算的80%时，通过SSE发出警告。

工具调度命令

当LLM发出工具调用时，它们会按照以下优先级进行调度：

load_dynatrace_skill --加载域技能（返回降价内容）
load_dynatrace_skill_reference --加载技能的参考文件
dtctl_run / dtctl_context_info --执行dtctl命令或获取上下文信息
MCP工具 （回退）--通过JSON-RPC转发到连接的Dynatrace MCP服务器

API终点

身份验证(`/api/auth`)

方法	端点	描述
职位	`/device-code`	启动GitHub设备流（返回 `user_code` + `verification_uri`)
职位	`/poll-token`	用户授权后轮询访问令牌
职位	`/anthropic-login`	使用Anthropic API密钥登录（根据Anthroptic API验证）
得到	`/status`	检查当前会话、用户信息和提供者
职位	`/logout`	销毁会话

聊天(`/api/chat`)

方法	端点	描述
职位	`/stream`	与SSE流媒体进行代理聊天（主要端点）

背景(`/api/context`)

方法	端点	描述
职位	`/upload`	上传上下文文件（多部分，最大5 MB）
得到	`/files`	列出上传的文件
删除	`/files/:name`	删除特定文件
删除	`/files`	清除所有文件
得到	`/payload`	获取完整的上下文负载
得到	`/budget`	获取上下文使用情况（字节、百分比、文件计数）

动态跟踪MCP(`/api/dynatrace`)

方法	端点	描述
职位	`/connect`	连接到Dynatrace MCP服务器
职位	`/tools`	列出可用的MCP工具
职位	`/disconnect`	断开与MCP服务器的连接

dtctl(`/api/dtctl`)

方法	端点	描述
得到	`/status`	检查dtctl安装、版本、身份验证状态
职位	`/install`	自动下载并安装dtctl二进制文件
职位	`/exec`	执行dtctl命令
职位	`/login`	OAuth登录到Dynatrace环境
职位	`/logout`	注销并删除上下文

型号(`/api/models`)

方法	端点	描述
得到	`/`	列出可用的GitHub Copilot模型

遥测(`/api/telemetry`)

方法	端点	描述
得到	`/config`	获取当前OTel配置
职位	`/config`	在运行时更新OTel配置
职位	`/test`	测试OTLP端点连接

健康

方法	端点	描述
得到	`/api/health`	退货 `{ status: 'ok', timestamp }`

关键设计决策

决定	理由
快速比Express快2-3倍，内置模式验证，TypeScript优先
上海证券交易所通过WebSocket	单向流媒体更简单，原生浏览器支持
双重身份验证（设备流+API密钥）	用于Copilot的GitHub设备流，用于Claude的Anthropic API密钥-不需要重定向URI
状态 state	最小样板，没有上下文提供者，小捆绑包
后端代理对于DT	neneneba API令牌，保持服务器端，防止浏览器暴露
内存会话	足以进行单实例演示；切换到Redis进行生产
按需技能	仅在LLM需要时加载——保持系统上下文精简
双平面布线	将实时观察（MCP）与配置更改（dtctl）分开
森科尼酒店	LLM交互的完全可观察性——令牌使用、工具结果、延迟

安全

GitHub代币 和 无烟煤API键 存储在httpOnly签名Cookie中（从不存储在localStorage中）
Dynatrace API令牌 代理服务器端（从不发送到浏览器）
SSRF保护 在Dynatrace代理上（仅相对路径）
命令注入预防 --dtctl命令根据允许的动词白名单进行解析和验证；分号、管道和倒钩被堵塞
写操作安全 --dtctl写动词需要显式 confirmWrite 旗；上下文已验证(dtctl_context_info)执行前
文件上传验证 --扩展白名单，每个文件限制5 MB，二进制内容拒绝
速率限制 --每个客户端每分钟100个请求
安全标头 --头盔（CSP、X-Content-Type-Options、HSTS等）
跨域资源共享 --仅限于 localhost:5173 正在开发中，可通过以下方式配置 ALLOWED_ORIGIN 生产中

运行测试

cd server && npm test