# @cloudflare/workers-honeycomb-logger 中文文档

规范地址：https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/

版本：2\.3\.3
npm 元数据更新时间：2026-09-03T14:21:56.588Z
中文译文更新时间：2026-11-10T04:08:23.734Z
软件包许可：BSD-3-Clause

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

原始 npm 页面：https://www.npmjs.com/package/%40cloudflare/workers-honeycomb-logger
原文对照：https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/?lang=original
项目主页：https://github.com/cloudflare/workers-honeycomb-logger#readme
源码仓库：https://github.com/cloudflare/workers-honeycomb-logger

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

- 包体积（解压后）：96.4 kB，26 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- 运行依赖：4 个
- 首次发布：2021-03-20T03:45:37.403Z
- 最新版本发布：2022-08-14T11:42:56.568Z
- 近 30 天下载量：2665（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：34（近 12 个月 0 个）

## 中文简介

用于登录所有请求引用到 Honeycomb.io 的功能

## 安装

```sh
npm install @cloudflare/workers-honeycomb-logger
```

也可以使用：`pnpm add @cloudflare/workers-honeycomb-logger`、`yarn add @cloudflare/workers-honeycomb-logger`、`bun add @cloudflare/workers-honeycomb-logger`

## README

Honeycomb 日志程序是一个简单的库,可以非常容易地导出您的运行时间信息 [云花岗工人](https://workers.cloudflare.com/) 输入 [蜂窝](https://honeycomb.io/)。 。 。 . Honeycomb是一个可观察性平台,它允许您在您数据中的任何(个数)维度之间查询和图表。 因此,例如,您可以将200个响应代码的图形请求持续时间,用于GET请求,到特定的URL,用于特定的客户.

或者你可以钻入一个错误请求的全部痕迹,包括所有子请求.

目录

-   [先决条件](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-prerequisites)
-   [开始](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-getting-started)
    -   [添加事件收听器配置](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-addeventlistener-configuration)
    -   [模块语法配置](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-module-syntax-configuration)
    -   [持久对象配置](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-durable-object-configuration)
-   [配置](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-config)
-   [添加日志和其他数据](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-adding-logs-and-other-data)
-   [追踪](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-traces)
-   [动态抽样](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-dynamic-sampling)

### 先决条件

这个剧本还没有为预定的工人工作. 它支持工人在以下两个方面: `addEventListener` 和模块语法,包括持久对象。 关于持久对象支持的更多信息,见下文.

### 开始

安装通过通常方式进行 `npm install @cloudflare/workers-honeycomb-logger` 或者说 `yarn add @cloudflare/workers-honeycomb-logger`。 。 。 .

接下来需要的两件事是Honeycomb API密钥和数据集名. 您可以选择您喜欢的任何数据集名称, Honeycomb 如果看到新名称, 将会自动创建新数据集 .

下一步取决于你是否在使用 `addEventListener` 格式或新模块格式(持久对象需要)

您还需要启用 `Automatically unpack nested JSON` 数据集设置 [https://ui.honeycomb.io (英语)](https://ui.honeycomb.io/) 可以查询所有自动包含的数据.

#### 添加事件收听器配置

要配置软件包,您需要用蜂窝记录器来包装您的收听器 。 所以,如果你目前的代码 看起来像这样:

```javascript
addEventListener('fetch', (event) => {
  event.respondWith(handleRequest(event.request))
})

function handleRequest(request) {
  //your worker code.
}
```

你可以把它改为:

```javascript
import { hc } from '@cloudflare/workers-honeycomb-logger'

const hc_config = {
  apiKey: '<api_key>',
  dataset: '<my-first-dataset>',
}
const listener = hc(hc_config, (event) => {
  event.respondWith(handleRequest(event.request))
})

addEventListener('fetch', listener)

function handleRequest(request) {
  //your worker code.
}
```

你现在可以走了。 通过配置部分读取以查看您还能配置什么 . 如果你遇到任何问题,这里有一个 [添加EventListener配置工人的全部示例](https://github.com/cloudflare/workers-honeycomb-logger/blob/main/run/worker/src/index.js)

#### 模块语法配置

如果使用模块语法,设置略有不同. 但你还是得把工人包起来.

如果你的密码是这样的

```javascript
export default {
  async fetch(request, env, ctx) {
    return new Response('Hello world!', { status: 200 })
  },
}
```

你会改变为类似的东西:

```javascript
const worker = {
  async fetch(request, env, ctx) {
    return new Response('Hello world!', { status: 200 })
  },
}

const config = {
  apiKey: '__HONEYCOMB_API_KEY__', // can also be provided by setting env var HONEYCOMB_API_KEY
  dataset: 'my-first-dataset', // can also be provided by setting env var HONEYCOMB_DATASET
}

export default wrapModule(config, worker)
```

你现在可以走了。 通过配置部分读取以查看您还能配置什么 . 如果你遇到任何问题,这里有一个 [模块语法配置工人的全部示例](https://github.com/cloudflare/workers-honeycomb-logger/blob/main/run/module-worker/src/index.mjs)

如果您不想手动硬化 API 密钥, 您也可以设置环境变量 `HONEYCOMB_API_KEY` 财务报告和审定财务报表 `HONEYCOMB_DATASET` 他们将制服插入其中的东西 `wrapModule`。 。 。 .

#### 持久对象配置

如果你在使用持久物体,我们支持在你的工人和持久物体中自动分布式追踪. 你需要用密码包裹你的工人密码 [模块系统配置](https://npmcn.com/package/%40cloudflare/workers-honeycomb-logger/#readme-module-syntax-configuration) 上方,然后将永久对象也包起来.

你可以这样做:

```javascript
import { Counter as counter_do } from './counter.mjs'

const worker = {
  async fetch(request, env) {
    // handleRequest
  },
}

const config = {
  apiKey: '__HONEYCOMB_API_KEY__', // can also be provided by setting env var HONEYCOMB_API_KEY
  dataset: 'my-first-dataset', // can also be provided by setting env var HONEYCOMB_DATASET
}

const Counter = wrapDurableObject(config, counter_do)
export default wrapModule(config, worker)
export { Counter }
```

如果你遇到任何问题,这里有一个 [长对象配置工人的完整示例](https://github.com/cloudflare/workers-honeycomb-logger/blob/main/run/do-worker/src/index.mjs)

### 配置

配置对象可以占用几个额外的参数来给发送给Honeycomb的事件添加更多细节或者配置其他方面.

```typescript
interface Config {
  apiKey?: string //The honeycomb API Key, can be specified as env var HONEYCOMB_API_KEY
  dataset?: string //The name of the dataset, can be specified as env var HONEYCOMB_DATASET
  acceptTraceContext?: boolean //Do you want to accept automatic TraceContext information from clients? Defaults to 'false'
  data?: any //Any data you want to add to every request. Things like service name, version info etc.
  redactRequestHeaders?: string[] //Array of headers to redact. Will replace value with `REDACTED`. default is ['authorization', 'cookie', 'referer'].
  redactResponseHeaders?: string[] //Array of headers to redact. Will replace value with `REDACTED`. default is ['set-cookie'].
  sampleRates?: SampleRates | SampleRateFn //Either an object or function that configured sampling ([See below](#dynamic-sampling))
  sendTraceContext?: boolean | RegExp //set this to true to send a TraceContext with all fetch requests. With a Regex, we will check the URL against the regex first. Defaults to 'false'
  serviceName?: string //The serviceName you want to see in Honeycomb. Defaults to 'worker'
  debugLog?: boolean // console.log response info for Honeycomb requests. Defaults to false
}
```

注:在以前的版本中,有分析请求和答复的方法,但在阅读请求或答复的正文时,这便成为一个问题,因此已删除。 如果您想要添加任何信息, 您可以使用 `tracer.addData` 方法说明如下.

### 添加日志和其他数据

如果您想要将其它数据或日志添加到当前请求中, 您可以使用 `tracer.addData(data: object)` 财务报告和审定财务报表 `tracer.log(message: string)` 方法。 。 . 您可以在请求对象上或者在听者中获取对追踪器的引用,或者获取第二个参数.

```typescript
async function handleRequest(request: TracerRequest) {
  request.tracer.log('handling request')
  const customer = parseCustomer(request)
  request.tracer.addData({customer: customer.name})
  return ...
}
```

### 追踪

Honeycomb有一个追踪的概念,它是多个相关事件的分级代表. Cloudflare Worker Honeycomb 日志支持子请求的微量事件(正在运行的 HTTP 获取您员工的请求) :

![Screenshot 2021-03-18 at 10 53 06 AM](https://user-images.githubusercontent.com/890386/111732941-ca13d200-88ca-11eb-94cb-a4f30a462788.png)

要将子请求与收到的正确请求联系起来, 您必须使用上述跟踪器上定义的获取 。 追踪器上的方法将所有参数都代表常规获取方法,所以 `tracer.fetch` 函数是所有 `fetch` 函数调用.

示例

```typescript
async function handleRequest(request: Request) {
  return request.tracer.fetch('https://docs.honeycomb.io/api/events/')
}
```

如果您想要启用从客户端到后端的自动分布的痕迹, 您可以启用 `acceptTrace` 属性,用于参与客户端启动的跟踪 `sendTraceContext` 自动发送到 [跟踪背景](https://www.w3.org/TR/trace-context/#examples-of-http-traceparent-headers) 转到你的后端. 这只管用 `fetch` 定义方法 `tracer` 对象,并与Honeycomb beeline 框架相容. 记住,你必须使用同样的 `dataset` 让所有系统都能在Honeycomb组装你的踪迹.

### 动态抽样

每个请求中存储所有这些信息的挑战之一是,当你将信息扩大到每月超过上千万个请求时,信息变得越来越昂贵。 但与此同时,你几乎肯定对绝大多数事件不甚感兴趣。 这就是为什么Honeycomb支持采样。 在那里只发送了部分事件. 做简单的取样(例如每10个请求中只发送1个)的问题是,你损失了很多很少发生的事件. 所以Honeycomb和这个库支持动态采样. 通过响应代码可以配置最简单的样本. 这样您就可以配置在10个响应码中只保留1个,并保留全部5xx.

从技术上讲,这个号码代表了多少个请求。 一个更容易记住的方法是,一个请求有1/x的机会被采样.

```typescript
export interface SampleRates {
  '1xx': number
  '2xx': number
  '3xx': number
  '4xx': number
  '5xx': number
  exception: number
}
```

举例来说:

```typescript
const hc_config = {
  api_key: 'abcd',
  dataset: 'my-first-dataset',
  sampleRates: {
    '1xx': 20,
    '2xx': 10,
    '3xx': 5,
    '4xx': 2,
    '5xx': 1,
    exception: 1,
  },
}
```

此配置库仅发送每10个请求中的1个,在200s中有一个响应代码,但保留所有错误;包括500s和例外.

如果想要对样本进行更精细的谷物控制,您可以提供一个能带走全部的函数 `data` 对象. 这是将发送到Honeycomb的确切对象,这样你就可以看到那里有什么值. 这包括您添加的所有信息 `request.tracer.addData()`

请注意: `Headers` 请求对象和响应对象均改为a `Record<string, string>`所以,如果你想检查 `content-type` 在回复中头,你可以 `data.response.headers['content-type']`。 。 。 .

实例

```typescript
function sampleRates(data: any): number {
  if (data.request.url.contains('/healthcheck')) {
    return 0
  } else if (data.customer.plan === 'enterprise') {
    return 5
  } else if (data.response.ok === true) {
    return 20
  } else {
    return 1
  }
}
```

关于取样和分布式追踪的一个告诫是,如果在两个/所有系统中分别进行取样,则 可能会得到部分的痕迹.

## 常见问题

### @cloudflare/workers-honeycomb-logger 是什么？

用于登录所有请求引用到 Honeycomb\.io 的功能

### 如何安装 @cloudflare/workers-honeycomb-logger？

在项目目录运行 npm install @cloudflare/workers-honeycomb-logger，或使用 pnpm add / yarn add / bun add。

### @cloudflare/workers-honeycomb-logger 支持 TypeScript 吗？

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

### @cloudflare/workers-honeycomb-logger 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @cloudflare/workers-honeycomb-logger 可以商用吗？

@cloudflare/workers-honeycomb-logger 使用 BSD-3-Clause 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。另外不得用原作者名义为衍生产品背书。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudflare/workers-honeycomb-logger 的下载量有多少？

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

### @cloudflare/workers-honeycomb-logger 还在维护吗？

最新版本 2\.3\.3 发布于 2022/08/14（4 年前）；至今共发布 34 个版本，其中过去 12 个月发布了 0 个；首次发布于 2021/03/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。