@ api 流量/ 用户

核心公用设施库,为所有ApiTraffic Node.js框架SDK提供共享功能. 该软件包包含用于请求管理、外出拦截、数据处理和配置管理的共同设施.

安装

npm install @apitraffic/utilities

特征

• 请求管理 - 集中要求跟踪和背景管理
• 外出拦截 - 自动 http编号 :https 财务报告和审定财务报表 fetch 请求拦截和监测
• 配置管理 - 以环境变量支持进行统一配置处理
• 数据处理 - 请求/答复机构处理和期限计算
• 内容管理 - 请求上下文和标记系统
• 设置管理 - 动态设置检索和缓存

快速启动

const { setup, RequestManager, config } = require('@apitraffic/utilities');

// Initialize ApiTraffic utilities
await setup({
  token: 'your-api-token',
  bucket: 'your-bucket-id',
  ingestHost: 'ingest.apitraffic.io',
  apiHost: 'api.apitraffic.io',
  interceptOutbound: true,
  debug: false
});

// Create a request manager
const requestManager = new RequestManager(config);
requestManager.tag('environment', 'production');

API 参考

设置函数

以您的配置初始化 ApiTraffic 工具 .

const { setup } = require('@apitraffic/utilities');

await setup(options, context);

选项

环境变量

您也可以使用环境变量配置 :

• API_TRAFFIC_TOKEN - 你的API代号
• API_TRAFFIC_BUCKET - 你的桶身份证
• API_TRAFFIC_INGEST_HOST - 最佳端点主机
• API_TRAFFIC_API_HOST - API 端点主机
• API_TRAFFIC_INTERCEPT_OUTBOUND - 启用出入境拦截
• API_TRAFFIC_CAPTURE_FETCH - 捕获出入境 fetch 电话
• API_TRAFFIC_MAX_FETCH_BODY_LENGTH - 每捕获一字节上限 fetch (违约:524288)
• API_TRAFFIC_REDACT_SENSITIVE_KEYS - 默认的遮盖证书形状的正文密钥和查询参数(默认:真实)
• API_TRAFFIC_INGEST_BATCH - 当您的账户和摄入主机提供时, 寄出的分批吞噬请求( 默认: 真实)
• API_TRAFFIC_INGEST_GZIP - 当您的账户要求时, Gzip 这些批次( 默认: 真)
• API_TRAFFIC_DEBUG - 启用调试模式

被压缩的批量压缩了数个被捕获的有效载荷(已经被修改) 所以压缩的好坏取决于这些有效载荷的含量 常见。 攻击者可以把所选内容输入俘获 sDK的出行请求的加密大小 摄入, 设定 ingestGzip: false (单位:千美元)API_TRAFFIC_INGEST_GZIP=false),或请求 账户的 ingest.batch.gzip 要关闭的旗帜, 发送批次 无所压缩.

内建编辑

在任何离开进程之前,证书形状名称下的值是 替换为 [*** API REDACTED ***]不管账户的规则怎么说 在JSON和 application/x-www-form-urlencoded 尸体和被俘者 URL的查询字符串(出入口). 规则旨在命名 拿着 一个秘密,而不是名字 提到一个:

• password, (中文(简体) ), passwd, (中文(简体) ), passcode, (中文(简体) ), secret, (中文(简体) ), apikey, (中文(简体) ), accesskey, (中文(简体) ), privatekey, (中文(简体) ), credential, (中文(简体) ), signature, (中文(简体) ), assertion, (中文(简体) ), jwt 在任何一处 名称( 忽略分隔符 : api_key, (中文(简体) ), x-api-key 财务报告和审定财务报表 apiKey 全部对齐);
• 结束于 token (单位:千美元)access_token, (中文(简体) ), csrfToken),但不能标注 光标( r)pageToken, (中文(简体) ), nextToken)或计数(max_tokens(三);
• 单词 auth, (中文(简体) ), pass, (中文(简体) ), pwd, (中文(简体) ), otp, (中文(简体) ), sig, (中文(简体) ), mfa, (中文(简体) ), totp· ; secret_key- 式键和 auth_code- 式码; session, (中文(简体) ), sessionid, (中文(简体) ), sid, (中文(简体) ), authorization, (中文(简体) ), cookie· ;
• 只有查询字符串中: key, (中文(简体) ), code 词 pin。 。 。 .

布尔斯, null 并保留空值。 机构经过编辑——仅限 蒙面值会改变, 所以没有其它关于被俘尸体的改变. 多段和XML机构没有密钥。 证书信头 (单位:千美元)authorization, (中文(简体) ), cookie, (中文(简体) ), x-api-key,.)总是被修改.

关闭密钥口罩 redactSensitiveKeys: false (或阴道) (见上文)。 SDK也尊重一个账户级别 redaction.sensitiveKeys: false 当仪表板提供开关时 账户规则 范围为 request.query 应用到抓取的 URL 查询字符串,并按键 规则适用于组成机构.

出境 fetch 捕获

出境 http编号 :https 调用(xios, got, node-fatch的 http path,...) 被捕获 通过补丁 http.request全球 fetch 从来没有经过它,它驱动 节点的内置undici直通插座——所以它有自己的钩子,安装了 与其余的出入境拦截。 A 类 fetch 电话报告与 与轴线相同的细节 : URL,方法,信头实际安装在线上 (从undici的) sendHeaders 诊断事件,所以 host, (中文(简体) ), content-length 财务报告和审定财务报表 accept-encoding 请求和答复 机构、状态、响应标题和时间,加内线 http.out 横跨 打电话的请求.

捕捉不会改变呼叫:呼叫者会得到准确的 Response 对象, 和身体读取从 clone()s. 值得了解的两个后果:

• 有效载荷上限为 maxFetchBodyLength, (中文(简体) ), 默认512 KB (单位:千美元) http 路径的上限是 3 MB ),因为读取一个响应的复制件会连接流—— a 高高的盖子与您同时持有第二个大下载副本 拥有的。 超过盖子的尸体是被截取并标记的 升为 无论你的载荷和头室证明什么

  await setup({ /* … */ maxFetchBodyLength: 512 * 1024 * 1024 }); // 512 MB
  

  API_TRAFFIC_MAX_FETCH_BODY_LENGTH=536870912
  

• 请求体是一个溪流, FormData 或者说 Blob,且非文本或 text/event-stream 答复,仅作为元数据列报 (单位:千美元)bodyCaptured: false而不是被消耗或重写.

设定 captureFetch: false (或 API_TRAFFIC_CAPTURE_FETCH=false离开 globalThis.fetch 无所未有.

钩子本身不需要比18号节点更新鲜的了(验证在 联合国 在没有全局的运行时间 fetch 钩子根本就没有 安装, 如果无法安装无线头事件, 信头是呼叫者 相反,报告设定.

值得了解钩子本身的两个属性:

• 随你怎么说 globalThis.fetch 安装时间和标记 本身,所以两次安装(或从此软件包的复制件)不会 堆栈包装和另一个库包 fetch 之后仍然运行在上面 这个 密码 替换 globalThis.fetch 设置后直接(而不是 把它包起来)去掉钩子,这些电话会被扣住.
• 线头通过undici请求身份(通过 undici:request:create ,而不是通过 URL,所以 同时提出的相同请求——包括发出不合秩序或排队的请求 在集合连接上——不能互换头集.

请求管理器

管理单个请求的上下文、标签和痕迹.

const { RequestManager } = require('@apitraffic/utilities');

const manager = new RequestManager(settings);

方法

tag(key, value) 在当前请求上下文中添加标签 .

manager.tag('user_id', '12345');
manager.tag('environment', 'production');

removeTag(key) 从当前请求上下文中删除标签 .

manager.removeTag('user_id');

trace(message) 在请求中添加一个跟踪消息 .

manager.trace('Database query executed');

工具函数

getDuration 计算两个时间点之间的持续时间 .

const { getDuration } = require('@apitraffic/utilities');

const startTime = process.hrtime();
// ... some operation
const duration = getDuration(startTime);

handleResponseBody 处理并处理响应体数据.

const { handleResponseBody } = require('@apitraffic/utilities');

const processedBody = handleResponseBody(responseData, options);

sendToApiTraffic 将请求数据发送到 ApiTraffic 服务 .

const { sendToApiTraffic } = require('@apitraffic/utilities');

await sendToApiTraffic(options, payload);

Span 指纹帮助器

这个包是 单一真相来源 apiTraffic 是如何变成原始的 运行到稳定状态 fingerprint (因此,相同的SQL/Redis/HTTP/海关 操作崩溃为一个身份 GROUP BY fingerprint 分析。 这个 @apitraffic/apm OTel大桥导入了同样的帮助,所以手动计时 同一操作的相接相接相接相接相接相接相接相接相接 指纹。 输入是 原始内容 ——常态化/装模作样发生在内部.

const {
  normalizeSql,       // "SELECT * FROM t WHERE id = 42" -> "SELECT * FROM t WHERE id = ?"
  maskRedisKey,       // "user:12345:profile" -> "user:{}:profile"
  fingerprintSql,     // (statement) -> "fpr_<16hex>"
  fingerprintRedis,   // (type, command, key, patterns?) -> "fpr_<16hex>"
  fingerprintHttpOut, // (method, host, pathPattern) -> "fpr_<16hex>"
  fingerprintGeneric, // (type, name) -> "fpr_<16hex>"
  fingerprintFrom,    // (parts:string) -> "fpr_<16hex>"  (low-level)
} = require('@apitraffic/utilities');

maskRedisKey 编辑 *Redis* 帮助者接受可选选项 redisKeyPatterns: Array<string | RegExp> 以覆盖内置 用于键形的可变分泌热力学,不能自行推断出.

配置

访问全局配置对象 :

const { config } = require('@apitraffic/utilities');

console.log(config.apiToken);
console.log(config.bucketSid);
console.log(config.ingestHost);

内容管理

在整个应用程序中管理请求上下文 :

const { context } = require('@apitraffic/utilities');

// Get current context
const currentContext = context.get();

// Set context data
context.set('requestId', 'req-123');

所需资源

• 节点.js 20.0.0或以上
• 有效的 ApiTraffic 账户和 API 令牌

依赖关系

此软件包包括以下依赖性:

• @apitraffic/data-redaction - 数据编辑公用事业
• @apitraffic/javascript-helpers - JavaScript 帮助函数
• @faker-js/faker - 数据生成公用事业
• ably - 实时通讯
• axios - HTTP 客户端
• ksuid - 独特的ID生成
• pako - 数据压缩
• systeminformation - 系统信息收集

捕捉到的东西

框架包按客户收到时报告每个入境请求. 当答复是: 承诺 当其第一个字节被交接到套接字(onCommit)——不是当它 完成,对于一个大响应来说,只有客户端读取了它. 这个 捕捉在字节被写入之后运行,所以它永远不会延迟回复, 和丢出(无效的标题值或状态代码)的写入 无:以下的错误反应是报告的内容.

请求机构 意思是每个框架都是一样的: 应用程序在响应时有它——包括更改其中间软件、钩子 或处理器在答复之前, 或没有处理器在答复之后。 通常这样 承诺 如果一个图层将字节背过应用程序 电话: compression 或者说 express-session 安装在 SDK 之后, 一个自动同步 快捷化 onSend 钩子,哈皮的gzip —— 单是请求,当 应用程序开始响应( e)onCommit是因为 start),这个捕捉步骤 运行在响应的字节之前, 只在路径上。 价格低廉:a 已宣布其请求超过 maxRedactBodyBytes (单位:千美元)Content-Length由占位符替换而无需序列化,以及 任何其他被解析出的尸体 由本地序列器序列化 并定居到 确切地说,这是有限度的相机所造作的(记号), 缓冲器),当有效载荷准备时,离开响应路径.

反应机构 是客户端发送的: 在快递上,有效载荷 改为 reply.raw - 申请结束后 onSend 钩子(一个能擦去 字段)——或对于流体或内容编码体,有效载荷 当它到达SDK的 onSend。一个内容编码的(gzip)机构永远不会 在任意框架上作为压缩字节报告.

答复完成时记录现状和时间(499 为客户服务 先断开的 尸体的巢穴有256个以上的深层——被剖析,或 JSON 文本框架为字符串, 当账户编辑规则会 解析——或无法被读取或被编辑的被发送为 [body not captured: …] 占位符和在 bodyNotCaptured 送货统计。 无法完成编辑的请求 即使没有它的躯体,它也绝不被派去 droppedUnredactable。 。 。 .

交货和代理

每个抓获的请求都作为JSON送去 POST编制和发送 关闭响应路径( 在 setImmediate,在答复之后 在SDK本身的活性剂上,有限定的货币,a 小重试队列和一个断路器。 使用节点的插图 http编号 :https 直接说 何时 HTTP_PROXY 编号 : HTTPS_PROXY 编号 : ALL_PROXY (或它们) npm_config_* 表格)适用于摄入的 URL 协议,这些帖子通过 而不是像以前一样,它的代理支持(NO_PROXY, CONNECT 地道 hTTPS)仍然适用. 代理变量最多每10个重读一次 秒数。 SDK自己的呼号(摄取,设置,主机遥测,嵌入符) 从未被记录为申请的外传电话.

处理错误

公用事业包括全面处理错误:

try {
  await setup({
    token: 'invalid-token',
    bucket: 'invalid-bucket'
  });
} catch (error) {
  console.error('Setup failed:', error.message);
}

常见错误 :

• 缺少 API 令牌或桶ID
• 无效的节点.js版本( < 18.0.0)
• 网络连接问题
• 无效的配置参数

调试模式

启用调试模式以查看详细记录 :

await setup({
  token: 'your-token',
  bucket: 'your-bucket',
  debug: true
});

或通过环境变量:

export API_TRAFFIC_DEBUG=true

许可证

麻省理工学院许可证 - 详情见LICENSE文件.

支助

支助和文件,访问 ApiTraffic.io (英语) 或联系人 sdk@ apitraffic.io (英语)。 。 。 .