telemetry-diet

# 遥测优化工具 [](https://github.com/last9/telemetry-diet/actions/workflows/ci.yml) [](https://www.npmjs.com/package/telemetry-diet) [](package.json) [](LICENSE) > 找到可以安全修剪的遥测数据——本地、只读、可审查和应用。 遥测优化工具是平台和可观察性工程师的本地可观察性优化工作台。它使用只读MCP工具收集提供商证据，确定性地分析这些证据，并导出可审查的草稿，而不应用生产变更。 日志是主要支持的工作流。Last9的指标引用和跟踪减少工作流是beta预览： | 工作流 | 捆绑示例 | Datadog | Last9 | | --- | --- | --- | --- | | 日志噪音、隐私和基数分析 | 已包含 | Beta | 支持 | | 指标引用覆盖 | Beta预览 | 不支持 | Beta预览 | | 跟踪减少候选 | Beta预览 | 不支持 | Beta预览 | 遥测优化工具不是仪表板、托管遥测服务或自动策略推出系统。MCP是只读集成层；产品结果是您可以在更改遥测收集之前审查的证据。 ```bash npx telemetry-diet ``` 该命令在`127.0.0.1`上启动本地应用并打开工作台。Datadog和Last9身份验证在提供商自己的同意页面上进行；OAuth令牌保留在本地进程中，不会暴露给浏览器应用。需要Node.js 22.13或更高版本。 ## 从源码在本地运行 前提条件：Git、Node.js 22.13或更高版本，以及npm。 ```bash git clone https://github.com/last9/telemetry-diet.git cd telemetry-diet npm install npm start ``` `npm start`在不自动打开浏览器的情况下运行本地工作台。在终端中打印的URL通常为`http://127.0.0.1:4545`。无需托管后端、数据库或凭证即可使用样本MCP路径。 在开发过程中使用监视模式： ```bash npm run dev ``` 要使用另一个端口： ```bash npm start -- --port 4571 ``` 使用`Ctrl+C`停止本地服务器。在提交更改之前，运行完整的本地质量检查： ```bash npm run verify ``` 该检查涵盖了跟踪的文本/JSON卫生、Markdown链接、JavaScript lint和语法、源代码覆盖率阈值、安装的依赖项许可证和npm包内容。`npm test`仍然是更快的仅测试命令。 提供商环境变量可以在`npm start`之前在同一shell中设置；请参阅[连接Datadog MCP以获取日志](#连接Datadog-MCP以获取日志)、[连接Last9 MCP](#连接Last9-MCP)和详细的[提供商设置指南](docs/mcp-providers.md)。 想要集成另一个可观察性平台吗？按照[添加可观察性提供商](docs/adding-provider.md)进行适配器合约、安全要求、端到端线路和测试检查清单。 ## 快速演示：无需凭证 本地应用运行时： 1. 点击**连接示例MCP**。 2. 保留`checkout-api`、`production`和**最近6小时**。 3. 保留**日志**并点击**分析选定窗口**。 4. 检查13个确定性发现，包括成功的健康检查、DEBUG噪音、风险字段、高基数字段和资源命名漂移。 5. 切换策略建议并观察方向性前后预览更新。 6. 检查或下载Markdown报告、OTel/OTTL草稿和Last9草稿JSON。然后尝试使用相同的示例连接测试指标和跟踪工作流。 捆绑的示例由真正的本地stdio MCP服务器提供。它包含每个工作流的通用、已经删除的示例；无需凭证或粘贴的遥测数据。 ## 连接Datadog MCP以获取日志 遥测优化工具使用配置的Datadog MCP服务器的实际只读工具： - `search_datadog_services`用于发现 - `analyze_datadog_logs`用于聚合分析 - `search_datadog_logs`用于详细回落 此beta路径针对广告的MCP工具模式和安全边界进行了合约测试。在完整的OAuth和分析流程与专用最低权限Datadog角色进行烟雾测试之前，它仍然是beta版本。 点击**使用Datadog登录**。遥测优化工具连接到Datadog的托管MCP端点，在提供商窗口中打开Datadog OAuth，验证本地主机回调并自动重新连接。默认流程中不需要Datadog CLI或API密钥设置。 高级：覆盖Datadog站点端点或使用现有的承载令牌： ```bash export TELEMETRY_DIET_DATADOG_MCP_URL='http://127.0.0.1:8080/mcp' export TELEMETRY_DIET_DATADOG_MCP_TOKEN='optional-existing-mcp-token' npx telemetry-diet ``` 或本地stdio命令。JSON数组避免shell引用歧义： ```bash export TELEMETRY_DIET_DATADOG_MCP_COMMAND='["npx","-y","YOUR_DATADOG_MCP_PACKAGE"]' export TELEMETRY_DIET_DATADOG_SERVICE='checkout-api' # 可选发现回落 # 只有此处列出的名称会从父环境复制到MCP子环境中。 export TELEMETRY_DIET_DATADOG_MCP_ENV_ALLOWLIST='DD_API_KEY,DD_APP_KEY' # 当该服务器需要时 npx telemetry-diet ``` 提供商特定的Datadog凭证属于该MCP服务器的环境。_stdio MCP子环境接收基本进程设置以及仅在`TELEMETRY_DIET_DATADOG_MCP_ENV_ALLOWLIST`中明确列出的凭证名称；不继承无关的父进程秘密。遥测优化工具不会在浏览器中要求凭证，也不会调用Datadog写入工具。 Datadog权限仍然控制所有结果。使用具有`mcp_read`、服务目录读取、日志读取数据、日志读取索引数据和时间序列的专用Datadog角色；不要授予`mcp_write`。遥测优化工具的运行时拒绝写入工具是深度防御，不能缩小过度特权的提供者令牌。它将选定的服务和环境嵌入到其SQL样式聚合查询中，用于计数、基数、顶部路径、严重性和消息指纹。它仅在工具宣传可强制实施的结果限制字段时调用`search_datadog_logs`，请求最多10个示例，拒绝超出限制的响应，删除示例，然后在UI/报告生成之前丢弃原始事件数组。没有该合约限制，聚合分析将继续进行，没有详细示例。 ## 连接Last9 MCP Last9日志适配器针对： - `get_service_summary` - `get_service_environments` - `get_service_logs` - `get_log_attributes` - `get_drop_rules` - `did_you_mean`（可用时） Last9托管端点包括`app.last9.io/<org_slug>/…`中的组织slug。配置此非秘密端点后，点击**使用Last9登录**并在Last9上完成OAuth。OAuth令牌保留在本地遥测优化工具进程中，并在其停止时过期。 对于另一个组织，请在启动应用程序之前设置slug： ```bash export TELEMETRY_DIET_LAST9_ORG_SLUG='your-org' npx telemetry-diet ``` 配置托管/HTTP MCP： ```bash export TELEMETRY_DIET_LAST9_MCP_URL='https://YOUR_LAST9_MCP_ENDPOINT/mcp' export TELEMETRY_DIET_LAST9_MCP_TOKEN='your-existing-mcp-token' export TELEMETRY_DIET_LAST9_SERVICE='checkout-api' npx telemetry-diet ``` 或stdio： ```bash export TELEMETRY_DIET_LAST9_MCP_COMMAND='["node","/path/to/last9-mcp-server.js"]' export TELEMETRY_DIET_LAST9_SERVICE='checkout-api' # 示例：当子服务器需要来自此shell的选定凭证时： export TELEMETRY_DIET_LAST9_MCP_ENV_ALLOWLIST='LAST9_API_TOKEN' npx telemetry-diet ``` 推荐在MCP服务器没有全局服务列表工具时使用`TELEMETRY_DIET_LAST9_SERVICE`。读取现有的删除规则作为上下文。生成的Last9策略是仅导出草稿：没有`add_drop_rule`或其他写入路径。 Last9日志分析是此提供商的主要支持工作流。指标和跟踪工作流是beta预览。指标引用覆盖动态解析只读指标库存和至少一个引用源：原生仪表板、嵌入式Grafana仪表板、警报或实体指标。跟踪智能更喜欢聚合跟踪分析能力，可以仅在广告结果限制时使用跟踪搜索回落。两个beta工作流在必需的读取合约不可用或无法识别时关闭。 参见[提供商设置](docs/mcp-providers.md)以获取传输和响应规范的详细信息。 ## 指标引用覆盖 - beta 指标引用覆盖使用PromQL语法树而不是正则表达式。它按多个扫描查询引用、引用一次或在扫描源中未引用来报告每个指标。单个引用是审查信号，而不是证据表明指标不重要。保护策略是单独的标志；它永远不会悄悄地将未引用的指标变成引用的指标。 报告范围是组织范围的，包括确切的查询出处。它不观察临时查询或外部消费者，因此未引用的结果是审查候选，而不是证明指标未使用。参见[指标使用](docs/metric-usage.md)。 ## 跟踪智能 - beta 跟踪智能按以下顺序考虑测量的字节： 1. 资源属性修剪，保留关键服务和SDK属性。 2. 当多个名称折叠为一个删除模式时，保守的UUID和长十六进制跨度名称规范化。 3. 选择性冗余仪表盘禁用，同时保留配对边界跨度。 4. 准确的低值或健康路由`INTERNAL`叶过滤器，排除错误、业务跨度和受保护的边界跨度。 5. 快速成功分组作为仅审查采样候选，具有明确的测量持续时间阈值。 6. 剩余头部采样作为最后的杠杆，具有明确的APM和错误可见性警告。 生成的OTel Collector和OTTL文本明显标记为**仅导出草稿**，永远不会应用。参见[跟踪智能](docs/trace-intelligence.md)。 ## 分析器证明 确定性日志分析器检测： - 成功`/health`、`/healthz`、`/ready`、`/live`和`/metrics`流量 - DEBUG/TRACE噪音和重复的消息指纹 - 可能的电子邮件、API密钥、承载令牌、秘密和会话令牌字段 - 使用存在和唯一性比率的高基数字段 - `service`/`service.name`/`app`和环境命名漂移 - 不适合作为标签、标签、方面或路由键的字段 每个发现结果都包括置信度、选定窗口中的受影响记录、删除的示例、建议的操作、限制和规则片段（如果目标支持）。小样本标记为**样本影响**或**方向减少**，而非确切节省。 ## 生成的输出 输出取决于所选的工作流：日志生成Markdown报告以及OTel/OTTL和Last9策略草稿；指标生成Markdown和JSON使用报告；跟踪生成Markdown以及OTel Collector/OTTL仅导出草稿。 生成的语义和可移植性限制在[策略输出](docs/policy-output.md)中记录。 维护人员可以使用安装的OpenTelemetry Collector Contrib二进制文件验证有代表性的日志和跟踪草稿： ```bash npm run validate:artifacts -- --collector /path/to/otelcol-contrib ``` 检查还验证Last9 JSON是否符合已发布的[`telemetry-diet.last9-draft/v1`模式](schemas/telemetry-diet.last9-draft.v1.schema.json)。 ## 安全边界 > 证据优先。 人工审查。 您应用。 - 提供商OAuth加上只读MCP调用；不提供生产写入实现。 - Web服务器仅绑定到环回地址，并拒绝不匹配的主机、跨源和跨站点请求。 - 原始记录在本地汇总，不发送到AI服务。 - 指标查询定义和跟踪聚合在本地规范化；永远不会将原始跟踪记录返回到浏览器。 - 提供商证据在UI/报告生成前通过基于模式的删除进行本地处理。在审查之前，请将导出的报告视为敏感信息。 - 生成的配置始终可见且仅导出。 - 现有Last9规则是上下文，不是突变目标。 - 草稿可能会影响事件响应、合规性和保留。请在部署前测试和审查它们。 遥测优化工具不提供确切的成本估算、自动推出、Datadog写入、Last9写入、托管多租户后端、生产策略应用或AI分析。 ## 架构 ```text 示例MCP ─┐ Datadog MCP ─┼─> 信号适配器 ─> 规范化的提供者证据 Last9 MCP ──┘ │ v 确定性信号分析器 │ 报告 + 可见的导出草稿 ``` ```text bin/ CLI和示例MCP可执行文件 src/core/ 日志分析器、删除、预览、策略、报告 src/metric-usage/ PromQL解析、保护策略、使用报告 src/trace-intelligence/ 字节优先减少分析和导出草稿 src/mcp/ stdio客户端/服务器和Streamable HTTP客户端 src/providers/ 示例、Datadog和Last9适配器 src/sample/ 捆绑示例场景 web/ 无依赖的本地工作台 test/ 确定性和MCP集成测试 ``` ## 社区 - 在打开问题或错误报告之前，请阅读[SUPPORT.md](SUPPORT.md)。 - 参见[CONTRIBUTING.md](CONTRIBUTING.md)以开发和测试更改。 - 使用[SECURITY.md](SECURITY.md)中的私有流程报告漏洞，切勿公开问题。 - 参与由[Code of Conduct](CODE_OF_CONDUCT.md)管辖。 ## 许可证 Apache-2.0。参见[LICENSE](LICENSE)和[NOTICE](NOTICE)。