@ crossdelta/ 遥测
Bun和Node.js上的TypeScript服务的OpenTeleometry仪器化.
开始
1. 安装
bun add @crossdelta/telemetry
2. 导入(一行!)
import '@crossdelta/telemetry'
import { Hono } from 'hono'
导入必须先于所有其它内容来正确补丁模块 .
3. 设定环境变量
OTEL_SERVICE_NAME=my-service
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp-gateway.grafana.net/otlp/v1/traces
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=https://otlp-gateway.grafana.net/otlp/v1/logs
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT=https://otlp-gateway.grafana.net/otlp/v1/metrics
OTEL_EXPORTER_OTLP_HEADERS=Authorization=Basic base64(instanceId:apiKey)
如果未配置端点, 遥测会禁用零起落点 .
使用量
霍诺服务(本)
线 instrumentMiddleware() 以获取每个请求的跨度、 HTTP 参数和日志上下文。 每个 console.* 在请求中自动调用包括requestId, trackId,路径,以及Grafana中的方法.
import '@crossdelta/telemetry'
import { instrumentMiddleware } from '@crossdelta/telemetry/middleware'
import { Hono } from 'hono'
const app = new Hono()
app.use('*', instrumentMiddleware())
按此请求创建:
- OTEL 服务器跨度(
http.method, (中文(简体) ),http.target, (中文(简体) ),http.status_code(中文(简体) ) - 一个
http.server.request.duration直方图条目 - ALS 语境
requestId, (中文(简体) ),traceId, (中文(简体) ),spanId, (中文(简体) ),path, (中文(简体) ),method日志关联
W3C号 traceparent 标题自动传播,所以所有下游服务都一样 traceId. NATS CloudEvents 上下文通过 @crossdelta/cloudevents。 。 。 .
在Node.js(NestJS/Express)上, HttpInstrumentation 自动处理跨度和度量. instrumentMiddleware() 只设置 ALS 上下文 .
日志
在大多数情况下,是普通的 console.* 工作时 OTEL补丁自动捕捉出一切并附加了微量上下文.
console.info('[ORDER:CREATED]', orderId)
console.error('[PAYMENT:FAILED]', reason)
对于Grafana中可查询的密钥值属性:
import { logInfo, logError } from '@crossdelta/telemetry/logger'
await logInfo('Order created', { orderId, total, tenantId })
await logError('Payment failed', { orderId, reason, provider })
Qwik 应用程序
import { initRequestContext } from '@crossdelta/telemetry/logger'
export const onRequest: RequestHandler = async (ev) => {
const requestId = initRequestContext(ev)
ev.headers.set('X-Request-Id', requestId)
}
自定义初始化
对于非默认设置,使用 initTelemetry() 而不是副作用导入 :
import { initTelemetry } from '@crossdelta/telemetry'
initTelemetry({
metricsIntervalMs: 30_000,
onShutdown: async () => {
await database.close()
},
})
运行时间支持
所有信号(logs, 度量衡, tracks)在两个运行时间都工作. 不同之处在于HTTP跨度和度量标准是如何创建的:
| 特性 | 节点.js | 阿宝 |
|---|---|---|
| HTTP 跨度 | 自动 (HttpInstrumentation(中文(简体) ) | instrumentMiddleware() |
HTTP 度量衡(http.server.request.duration(中文(简体) ) | 自动 (HttpInstrumentation(中文(简体) ) | instrumentMiddleware() |
| 快速/最新JS追踪 | 对 | 没有 |
支持的后端
Grafana Cloud, Better Stack, Jaeger——任何OTLP端点都可行.
API 参考
基本内容
| 导出 | 从 | 说明 |
|---|---|---|
import '@crossdelta/telemetry' | . | 自动初始化 SDK( 边效导入) |
instrumentMiddleware() | ./middleware | Hono中件:服务器跨度, HTTP 度量衡, ALS 上下文, X-Request-Id 标题 |
logInfo(msg, data?) | ./logger | 有ALS上下文的结构化信息日志 |
logWarn(msg, data?) | ./logger | 带有 ALS 上下文的结构化警告日志 |
logError(msg, data?) | ./logger | 带有 ALS 上下文的结构化错误日志 |
logDebug(msg, data?) | ./logger | 带有 ALS 上下文的结构调试日志 |
initRequestContext(event) | ./logger | 按请求设置ALS上下文. 返回请求Id . |
logger | ./logger | 通用日志对象(服务器:Pino+ALS,客户端:控制台) |
高级
| 导出 | 从 | 说明 |
|---|---|---|
initTelemetry(config?) | . | 手动带有自定义选项的 SDK 初始化 |
shutdownTelemetry() | . | 模糊数据并关闭 SDK |
getSDK() | . | 获取当前 NodeSDK 实例(或 null(中文(简体) ) |
extractTraceparent(request) | ./traceparent | 解析 W3C traceparent 来自请求的页眉 |
parseTraceparent(header) | ./traceparent | 分析 W3C traceparent 字符串 |
buildTraceparent(context) | ./traceparent | 构建 W3C traceparent 微量上下文的标题 |
getCurrentTraceparent() | ./traceparent | 获取当前 traceparent 从ALS 或 OTEL 活动跨度 |
runWithTraceparent(header, fn) | ./traceparent | 运行一个函数在从一个 traceparent 标题 |
runWithLogContext(context, fn) | ./logger | 在自定义的 ALS 上下文中运行一个函数 |
buildRequestLogContext(req, url) | ./logger | 从请求中建立日志连接地图 |
getLogContext() | ./logger | 将当前 ALS 上下文读取为普通对象 |
withLogging(name, fn, opts?) | ./logger | 以自动出错 + 慢调记录环绕 async 函数 |
serializeError(error) | ./logger | 序列化错误到 { err, errName, stack, cause } |
在生产中 OTEL_* vars通过你的秘密经理 或CI/CD.
许可证
麻省理工学院