# @crossdelta/telemetry 中文文档

规范地址：https://npmcn.com/package/%40crossdelta/telemetry/

版本：0\.13\.2
npm 元数据更新时间：2026-05-24T12:18:38.098Z
中文译文更新时间：2026-11-11T01:36:20.841Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40crossdelta/telemetry
原文对照：https://npmcn.com/package/%40crossdelta/telemetry/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：159 kB，34 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：13 个
- peer 依赖：hono \>=4\.12\.12
- 首次发布：2025-12-04T12:07:35.330Z
- 最新版本发布：2026-05-24T12:18:37.995Z
- 近 30 天下载量：4033（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：23（近 12 个月 23 个）

## 中文简介

CrossDelta 服务的 OpenTelemetics 仪器

## 安装

```sh
npm install @crossdelta/telemetry
```

也可以使用：`pnpm add @crossdelta/telemetry`、`yarn add @crossdelta/telemetry`、`bun add @crossdelta/telemetry`

## README

# @ crossdelta/ 遥测

[![npm version](https://img.shields.io/npm/v/@crossdelta/telemetry.svg)](https://www.npmjs.com/package/@crossdelta/telemetry) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/) [![OpenTelemetry](https://img.shields.io/badge/OpenTelemetry-1.x-blueviolet.svg)](https://opentelemetry.io/)

Bun和Node.js上的TypeScript服务的OpenTeleometry仪器化.

## 开始

### 1\. 安装

```bash
bun add @crossdelta/telemetry
```

### 2\. 导入(一行!)

```typescript
import '@crossdelta/telemetry'

import { Hono } from 'hono'
```

导入必须先于所有其它内容来正确补丁模块 .

### 3\. 设定环境变量

```bash
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中的方法.

```typescript
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补丁自动捕捉出一切并附加了微量上下文.

```typescript
console.info('[ORDER:CREATED]', orderId)
console.error('[PAYMENT:FAILED]', reason)
```

对于Grafana中可查询的密钥值属性:

```typescript
import { logInfo, logError } from '@crossdelta/telemetry/logger'

await logInfo('Order created', { orderId, total, tenantId })
await logError('Payment failed', { orderId, reason, provider })
```

### Qwik 应用程序

```typescript
import { initRequestContext } from '@crossdelta/telemetry/logger'

export const onRequest: RequestHandler = async (ev) => {
  const requestId = initRequestContext(ev)
  ev.headers.set('X-Request-Id', requestId)
}
```

### 自定义初始化

对于非默认设置,使用 `initTelemetry()` 而不是副作用导入 :

```typescript
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.

## 许可证

麻省理工学院

## 常见问题

### @crossdelta/telemetry 是什么？

CrossDelta 服务的 OpenTelemetics 仪器

### 如何安装 @crossdelta/telemetry？

在项目目录运行 npm install @crossdelta/telemetry，或使用 pnpm add / yarn add / bun add。

### @crossdelta/telemetry 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @crossdelta/telemetry 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @crossdelta/telemetry 可以商用吗？

@crossdelta/telemetry 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @crossdelta/telemetry 的下载量有多少？

根据 npm 官方下载统计，@crossdelta/telemetry 在 2026/10/11 – 2026/11/09 这 30 天内被下载 4,033 次，日均约 134 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @crossdelta/telemetry 还在维护吗？

最新版本 0\.13\.2 发布于 2026/05/24（5 个月前）；至今共发布 23 个版本，其中过去 12 个月发布了 23 个；首次发布于 2025/12/04。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。