@ 下行追踪/代理

Downtrace 告诉您当一个更改中断了您节点. js后端的性能时: 在您部署之前, 哪个路由现在运行一个每行一次的查询, 或者每个请求再运行一次; 在您部署之后, 哪个路由变慢或者开始失败, 以及什么变化 . 这是它的 仪器:它从内部观察你的应用,每条路线局部的集合和10秒的间隔,在生产中,船会压缩批次到下行云——从你的要求路径中从未出现过,也从未能够投入你的代码中,带有有界限的内存.

下行追踪是免费的:没有计划,没有计费,也没有解放军. 摄入协议是 v0 ,在小版本之间仍然可以更改.

它注意到这些,每个都可以用 DOWNTRACE_INSTRUMENT数字 :

它只观察它被装入的过程:一个过程,一个服务. 在本文件中 仪器 这个图书馆和一个 编码代理 是运行"下行"的人;该套件保留了旧名.

在你部署之前,没有账户

您的测试通过, 和一个改变 路径运行查询一次每行. downtrace check 运行您的测试 HEAD 在你们工作的树上,你们可以对你们说:你们所请求的,不是按路线排列的

npm install --save-dev @downtrace/agent
npx downtrace init     # finds your test command, writes downtrace.json; asks nothing
npx downtrace check    # exit 0: no route got worse · 1: one did · 2: no comparison could be made

Worse (1)
  GET /orders   3 requests in the base, 3 in the change
    appeared   SELECT name FROM users WHERE id = ?  [query 0ee1294e0ade7fb8]  0 -> 50 per request
    appeared   SELECT id, total, user_id FROM orders ORDER BY id  [query fb36696aebd98a68]  0 -> 1 per request
    gone       SELECT o.id, o.total, u.name FROM orders o JOIN users u ON u.id = o.user_id ORDER BY o.id  [query 0ad9139c76ae524a]  1 -> 0 per request
    request duration, shown and not judged: 1 ms -> 14.82 ms

没有东西离开机器:运行没有符号也没有URL. 持续时间是显示的,从不判断,因为测试运行不是生产;判决来自每个请求的运行情况——询问,发出呼叫,Redis命令——以及多少次. 据说,测试没有达到的路线没有经过名称评估,而且从未改变。 编码代理读取相同的结果 --json。 。 。 .

没有通过HTTP达到你的应用测试吗? 开始 DOWNTRACE_INSPECT,使用它,停止它, 并阅读每个路线运行, 最多查询每个请求:

DOWNTRACE_INSPECT=./run.jsonl node --import @downtrace/agent/register app.js
npx downtrace report run.jsonl                # each route: requests, queries per request, what repeats, the slowest
npx downtrace compare base.jsonl run.jsonl    # check's verdict over two such files, recorded however you can

  GET /orders   2 requests  ·  21 queries per request on average, median 21 to 50
    repeated   select * from "users" where "id" = ?  [query 81ca38dfd955b40d]  20 per request

整个事情: downtrace init,它配置一个项目,要求什么也不做网络请求, downtrace check,以及 downtrace report 财务报告和审定财务报表 downtrace compare. 生产,用云,起于下.

安装

npm install @downtrace/agent
npx downtrace init                      # writes the instrument file and the line that loads it
npx downtrace login --project shop-api  # asks Downtrace's cloud for the project; you approve it in the browser

仪表从一个仪器文件开始, 您的应用程序负载在其它东西之前, 它叫 init() 还有你的DSN. downtrace init 写下面的食谱 downtrace login 打印摄入符和云的URL DSN是由(他们的指南) (中文(简体) ). 已写入文件 DOWNTRACE_DSN 从环境;在无法设置环境的地方,将 DSN 写入它的位置,文件从运行它的每个机器发送.

NestJS, 编译为 CommunityJS

// src/instrument.ts
import { init } from "@downtrace/agent";

init({ dsn: process.env.DOWNTRACE_DSN });

// src/main.ts: the first line, before anything else
import "./instrument";
import { NestFactory } from "@nestjs/core";

TypeScript 将该行转换为条目的第一个 require,所以在Nest建立Express和您的数据库池之前,仪器就已经到位了。 它在每个支持的节点都有作用.

快递

// instrument.js, beside your entry
const { init } = require("@downtrace/agent");

init({ dsn: process.env.DOWNTRACE_DSN });

// server.js: the first line
require("./instrument");
const express = require("express");

快捷化

一样 instrument.js在Fastify创建其实例之前:

// app.js: the first line
require("./instrument");
const fastify = require("fastify")();

ES模块

// instrument.mjs
import { init } from "@downtrace/agent";

init({ dsn: process.env.DOWNTRACE_DSN });

node --import ./instrument.mjs server.js

一个ES模块的进口在第一行运行前全部被装入,所以 node 装入文件本身: 在您的开始脚本中, 您的多克文件 CMD,或 NODE_OPTIONS="--import ./instrument.mjs"。 。 。 .

不碰密码

在您可以设置起始命令或环境时, 不需要仪器文件 :

DOWNTRACE_DSN=https://dt_…@your-downtrace-cloud \
  node --import @downtrace/agent/register server.js
# or, without touching the start command:
NODE_OPTIONS="--import @downtrace/agent/register" node server.js

配置

每个设置都是选择 init() 和一个环境变量:给定的选项胜出,一个被忽略的选项从它的变量读取. 什么让你开始:

其余的——调试,间隔,配置,观察者运行的最小模式,查询文本,排除,基准开关——以及什么是迟到或秒 init() 显示在 配置。 。 。 .

一个摄入物属于一个环境 那个 环境 发送的一切 被存储为,无论 DOWNTRACE_ENV 说 如果两者意见不一,数据仍会落地——对错误标签的部署失明会比错误的标签更糟糕——项目页面显示实例是声明别的东西,这通常是需要修正的可变因素. 在每一个环境标志物存在之前铸造的纸币是不受约束的,并继续让批量申报.

没有DSN,或者 DOWNTRACE_TOKEN 财务报告和审定财务报表 DOWNTRACE_URL (或有一个不是) http(s)://),仪器会印出一个警告,而别无他法:它不会装入任何你的依赖,也不会改变任何依赖。 所以,你可以把它添加到一个部署中, 之前你有一个符号: 没有什么变化,直到它有一个.

要知道它的工作, 读stderr。 当云接受第一批时,一行表示降落地点,调试与否:

[downtrace] connected: shop-api / staging

云何不说从何而来 connected: the cloud accepted the first batch彩云拒绝的象征是一次,从未重复过。 与 DOWNTRACE_DEBUG=1 开始名称 它找到的司机, drivers found: pg, mysql: 一旦您的应用程序装入后, 每一个在首次使用时都会被包裹, 并且是自己的 instrumented 线只到那时.

在部署前, 请检查符号而不发送任何数据 :

npx downtrace verify    # downtrace verify: the token writes to shop-api / staging

它读取了仪表,从.. DOWNTRACE_DSN 或者说 DOWNTRACE_TOKEN 财务报告和审定财务报表 DOWNTRACE_URL· ; --dsn <dsn>,或 --token <token> 与 --url <url>检查另一个。 它从不打印符号。 0出道: 信使写到它写着 : : : : : : 云拒绝 : 2: 没有任何东西可以检查(没有信使,它无法到达或10秒内不回答的云,或任何其他答案), 它写着什么.

摄取物是安全的

标志在 DOWNTRACE_TOKEN 设计上是公开的 就像哨兵DSN一样 携带它的DSN也一样 DOWNTRACE_DSN 或进入 init({ dsn }): 将您的部署可以读取的地方、您的仓库、您的多克文件或您的乐器文件包含在内。 它属于一个项目和一个环境,它只会发出,而云的每一个其它的门都会回答它,因为它根本不回答任何证书. 拿着它的人:

• 能够 将数据发送给其项目,作为它的环境——批量地储存,以及捕捉云所要求的证据——因此,请唐斯崔斯报告从未发生的事情;
• 能够 将环境预算花光——每天排出一行,捕捉一小时,证据,错误的签名——和用完的一分一分停止这种环境,生产没有改变,直到重新填充;
• 能够 读取它发送的答案中,它写给的项目和环境,以及云要求环境捕捉的路线和依赖性;
• 无法 读取发现、报告、错误、证据或页面,在任何东西上操作,或写给另一个项目或作为另一个环境.

如果最后你宁愿没有, 问谁开你的下行云 来为这种环境换个新标志: 老的停止工作, 和它一起发送的是什么。 一个 未绑定 标语(以上)写成批量申报的、包括生产在内的任何环境:在承诺之前,用一个与其环境相连的符号取而代之.

只有摄入物, dt_…,是公开的。 访问证书, dtr_… - 编码代理读取和操作内容,以及 @downtrace/mcp 从同名变量读取——是一个秘密:从不犯.

如果你的建筑有依赖性 它看不到

--import 从命令行装入仪器, 所以 代码里没有输入它仅运送所进口物品的班德勒斯——下一个 output: "standalone",以及复制“只使用什么”的其他任何内容—— 把它放出,容器与 Error: Cannot find package '@downtrace/agent'。 。 。 .

下一个.js

使用 instrumentation.ts在它服务于任何事物之前,它曾经运行过。 您的 Docker 文件、 启动命令或 NODE_OPTIONS - 和 downtrace init 当它发现的时候写给你 output: "standalone"数字 :

// instrumentation.ts, at the root of your project (or in src/)
export async function register() {
  if (process.env.NEXT_RUNTIME === "nodejs") {
    await import("@downtrace/agent/register");
  }
}

因为你的代码导入它, 下一个追踪它和船, 每条路线由服务它的文件命名(/api/products/[id]) (中文(简体) ). 条件不是可选的: 下一次调用 register 每一个运行时间,它建造, 没有它有一个项目 middleware.ts 失败 next build 与 Reading from "node:module" is not handled by plugins。您的 tsconfig.json 需求 "moduleResolution" 设置为 bundler, (中文(简体) ), node16 或者说 nodenext经典 node 无法解决 /register 子路径.

任何其它的痕迹

要么从您拥有的入口导入仪器, 如上, 要么让捆绑者保存它 。 接下来是 outputFileTracingIncludes;其他工具具有等同性.

你的服务器留下的是什么

只有结构元数据:方法, 路由模板 (单位:千美元)/products/:id,绝不是实际的URL),状态,计数和每个路由和间隔的固定-bucket内置直方图;每个依赖性,每个请求打了多少个电话,用了多长时间;每个路由通常运行什么,作为指纹;过程的健康;过程身份(随机ID,主机名,pid)和部署(版本,环境). 没有机构, 没有信头, 没有查询字符串, 没有数据库中的值 。 确切的合同是JSON斯克马 @downtrace/protocol。 。 。 .

DOWNTRACE_MINIMAL=1 扣留您所写的一切: 路由模板, 依赖目标, 您的主机名和您部署的版本旅行作为稳定摘要, 以及查询文本, 调用和命令的标签, 错误消息和例外签名根本不会旅行 。 下行追踪不断检测和比较;它损失的是能够 名称 什么都行,它也这么说.

详细情况——每个字段、每个驱动程序、剖面图、捕捉、参考样本以及仪器本身的费用——都载于 你的服务器留下的是什么, (中文(简体) ), 数据库 财务报告和审定财务报表 路线如何命名。 。 。 .

看看会留下什么

你不必接受我们的话,你不需要一个帐户:

DOWNTRACE_INSPECT=./downtrace-batches.jsonl node --import @downtrace/agent/register app.js

这就是整个设置。 没有标志,没有URL,没有寄到任何地方。 您的应用程序运行器件 分批来 将 已运出的文件附在该文件后—— 精确字节,每个JSON一行。 开车真的 并读出的东西:

# every route template it discovered
jq -r '.intervals[].endpoints[].route' downtrace-batches.jsonl | sort -u

# every query fingerprint, as it would travel
jq -r '.profile.endpoints[]?.operations[]? | "\(.hash)  \(.text // "(no text)")"' downtrace-batches.jsonl

# and the question that actually matters: is anything of yours in there?
grep -i 'something-that-should-not-leave' downtrace-batches.jsonl

与一云相通也. 师曰. 设定 DOWNTRACE_INSPECT 与您的标志和 URL 一起写 财务报告和审定财务报表 发送,所以 运行中的部署可以在不关闭的情况下被审计,你读到的是实际出局的.

有两件事值得了解: 文件会长而无所旋转 它是你的,决定怎么办 用它,它可能包含 正常的文本 您的询问,这是重点, 所以给予同样的小心 你会给出一个应用程序日志.

错误

不触碰您的代码,一个查询,一个发送的呼叫或一个失败的Redis命令,就是它的身份错误——类型,消毒消息和堆栈签名,因此,一个例外会杀死进程,不处理它而观看:你的进程会如它那样结束.

钩子看不见的有两种, 因为从外面看,没有出错

import { captureException, expressErrorHandler } from "@downtrace/agent";

// An error you handled: a catch that retries, falls back or answers a 4xx.
try {
  await provider.authorize(order);
} catch (err) {
  captureException(err, { stage: "authorize", retryable: true });
  return fallback(order);
}

// An exception Express turned into a 5xx: after your routes, before your own error handler.
app.use(expressErrorHandler());

captureException 拥有您错误跟踪器的形状, 绝不扔出, 没有装入的仪器, 什么都不做 。 它的上下文平坦,小而沉着: 任何看上去像价值的东西都会像 ?。如何进行消毒,结束的每一种方式 如何保持和失去,如何运行在你的错误跟踪器旁边 错误。 。 。 .

保证

• 通过节点观测到 HTTP 请求 diagnostics_channel不碰你的密码 要查看查询和路由模板,仪器包罗它所命名的驱动器和框架的几种方法(哪个:它们通过未触动的参数,结果和出错传递,如果包裹本身失败了,你的代码仍然运行. DOWNTRACE_INSTRUMENT=none 把他们禁用.
• 发送与 fetch,脱离请求路径;一个有6个间隔的有界限的队列——如果云无法被接通,最古老的被丢弃.
• 每种云故障都有自己的答案:一批云呼叫无效(400,413,422)是 丢弃,计为 rejected 并报告过一次,而不是从批次中取出一个好的排队槽;被拒绝的 符号 (401 403) 保留批次,因为这是暂时的,一旦固定,这些间隔就值得;a 429 等待时间 为了什么 Retry-After 询问,最多一天; 重试了 5xx 或网络错误 .
• 每个钩子都有被看守;在10个内部出错后,仪表本身就会被禁用并说出一次.
• 每个间隔最多500个不同的路线;其余折叠成 (other)。 。 。 .
• 每道间隔最多60个不同的依赖关系;其余部分折叠成一个 (other) 那种能保持通话,时间和出错的行,因此批次从未超过计划64,而繁忙的路由无法淹没每条路由的间隔.
• 在配置文件、查询、呼叫和命令中,每条路由最多63个操作;其余则折叠为 (other) 桶,每一种它们合并一个, 说每个合并了多少个, 所以一个盖子从不隐藏发生的工作, 从来没有计算一个呼叫作为一个查询。 运行的路由被保存在时间上;它旁边的错误首先被保存.
• 查询文本在每次单独的文本中正常化并缓存,所以重复同样的查询需要一次地图查询,而不是重新查看.
• 计量间接费用预算:在p99中增加 < 1 ms;在CPU中增加 < 3个百分点; < 64 MiB。 每次合并后测量,可以移动它, 在一台机器上,没有其它东西,用手 make bench;在合并前从不作为大门.
• 没有什么可以信任的: DOWNTRACE_INSPECT 写准确的批次,不需要账户.

所需资源

节点(Node.js 18.19.0或更新),除节点(Node 19)外,是其生前的奇特放出;所建套件在节点(Node 18.19.0, 20.5.1, 20, 22和24)CI上被行使. 软件包在其软件包管理器中宣布了无节点版本,因此添加它不会失败安装一个工作空间,而其他应用程序运行一个更古老的节点. 在一个更古老的节点上, 和19, 仪器印出一个警告, 并且不做其他 downtrace 说在一行和2出口.

路线由快车4号和5号的模板命名(Koa)@koa/router, (中文(简体) ), koa-router,因此 Strapi 5)),"Next.js","快活4"和"快活5","Hapi 21"和"Hono 4"在所运行的版本中位于"节点"18上;一个没有路由名称的要求是: (unmatched),没有它的道路旅行。 其它任何地方的热力崩溃 看起来像价值 :id。见 路线如何命名。 。 。 .

驱动程序是您的应用程序载重, 解析其条目 : 找到驾驶员的地方报告未找到的驱动程序,以及 DOWNTRACE_DEBUG=1 说在启动时找到的和没有找到的.

文档

参考页面位于此 README 旁边, 以 guide/ 软件包:

• 配置 - 每一个环境,作为选择 init() 一个变星,一个迟到的变星 init() 输
• 你的服务器留下的是什么 – 每一个字段, 剖面图, 捕获, 参考样本, 最小模式
• 数据库 — Postgres, Neon, postgres.js, MySQL, SQL 服务器, SQLite, MongoDB和Prisma, 驱动程序
• 路线如何命名 ——每个框架,柔和和被包裹的东西
• 错误 ——两个电话,消毒,一个过程如何结束,除了你的错误追踪器
• downtrace init, (中文(简体) ), check 财务报告和审定财务报表 login, (中文(简体) ), brief, (中文(简体) ), api

更改日志

见 CHANGELOG.md。 。 。 .

来源

此软件包是在单列和镜像只读到 RadW2020/下行追踪代理. 欢迎提出的问题。 麻省理工学院.