@vlt-sdk/node

VLT (Virtual Log Trace) Node.js SDK — 自动收集 Node.js 服务的请求、响应和错误，并按照 VLT 协议上传遥测日志。

功能

• Express 中间件 — 自动收集入站 HTTP 请求/响应日志
• http/https 模块拦截 — 自动收集出站 HTTP 请求日志
• 手动日志上报 — info() / warn() / error() / log() 便捷 API
• 批量缓冲 — 本地缓冲，达到阈值或定时自动批量上传
• gzip 压缩 — 减少网络带宽开销
• 指数退避重试 — 网络异常时自动重试
• 环境变量回退 — 支持 VLT_ENDPOINT / VLT_TOKEN 环境变量配置

安装

pnpm add @vlt-sdk/node

快速开始

基本用法

import { VltClient } from '@vlt-sdk/node';

const vlt = new VltClient({
  project: 'my-app',
  environment: 'production',
  token: 'your-token',
  sourceName: 'user-service',
});

vlt.info('Service started', { port: 3000 });
vlt.error('Connection failed', { host: 'db.local' });

// 优雅关闭
process.on('SIGTERM', () => vlt.shutdown());

Express 中间件

import express from 'express';
import { VltClient } from '@vlt-sdk/node';

const vlt = new VltClient({
  project: 'my-app',
  environment: 'production',
  token: 'your-token',
  sourceName: 'api-gateway',
});

const app = express();
app.use(vlt.expressMiddleware());

app.get('/users', (req, res) => {
  res.json([{ id: 1, name: 'Alice' }]);
});

app.listen(3000);

HTTP 出站拦截

import { VltClient } from '@vlt-sdk/node';

const vlt = new VltClient({
  project: 'my-app',
  environment: 'production',
  token: 'your-token',
  sourceName: 'worker',
});

// 启用后，所有 http/https 请求自动记录
const disable = vlt.enableHttpInterceptor();

// 停止拦截
disable();

配置

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | project | string | 必填 | 项目标识 | | environment | string | 必填 | 环境 (dev/staging/prod) | | endpoint | string | VLT_ENDPOINT 或 http://localhost:8080 | VLT 服务端地址 | | token | string | VLT_TOKEN | 认证 Token | | sourceName | string | VLT_SOURCE_NAME 或 unknown | 服务名称 | | sourceType | SourceType | SERVICE | 来源类型 | | instanceId | string | hostname:pid | 实例 ID | | batchSize | number | 100 | 批次大小 | | flushInterval | number | 5000 | 刷新间隔 (ms) | | maxQueueSize | number | 10000 | 最大队列大小 | | timeout | number | 10000 | HTTP 超时 (ms) | | gzip | boolean | true | 是否 gzip 压缩 | | retries | number | 3 | 重试次数 |

API

VltClient

• log(record) — 记录一条自定义日志
• info(body, attributes?) — INFO 级别日志
• warn(body, attributes?) — WARN 级别日志
• error(body, attributes?) — ERROR 级别日志
• expressMiddleware() — 返回 Express 中间件
• enableHttpInterceptor() — 启用 http 模块拦截，返回 disable 函数
• flush() — 立即刷新缓冲
• shutdown() — 优雅关闭

协议兼容

完全兼容 VLT 协议 v1：

• 上传端点: POST /v1/logs
• Content-Type: application/json
• 支持 gzip 压缩
• Bearer Token 认证
• 幂等性 request_id

License

MIT