deno.com
本页内容

如何将遥测数据导出到 Honeycomb

OpenTelemetry(通常缩写为 OTel)是一个开源可观测性框架,提供了一种标准化方式来收集和导出遥测数据,例如跟踪、指标和日志。Deno 内置支持 OpenTelemetry,让您可以轻松地检测应用程序而无需添加外部依赖项。此集成可与 Honeycomb 等可观测性平台即开即用。

Honeycomb 是一个可观测性平台,旨在调试和理解复杂的现代分布式系统。

在本教程中,我们将构建一个简单的应用程序,并将其遥测数据导出到 Honeycomb。我们将涵盖:

您可以在 GitHub 上找到本教程的完整源代码。

设置您的聊天应用 跳转到标题

在本教程中,我们将使用一个简单的聊天应用程序来演示如何导出遥测数据。您可以在 GitHub 上找到该应用程序的代码。

您可以复制该存储库,或者创建一个 `main.ts` 文件和一个 `.env` 文件。

为了运行该应用程序,您需要一个 OpenAI API 密钥。您可以通过在 OpenAI 注册账户并创建一个新的秘密密钥来获取。您可以在 OpenAI 账户的 API 密钥部分找到您的 API 密钥。获得 API 密钥后,在您的 `.env` 文件中设置一个 `OPENAI_API_KEY` 环境变量:

.env
OPENAI_API_KEY=your_openai_api_key

设置 Docker 收集器 跳转到标题

接下来,我们将设置一个 Docker 容器来运行 OpenTelemetry 收集器。该收集器负责接收您应用程序的遥测数据并将其导出到 Honeycomb。

如果您还没有 Honeycomb 账户,请创建一个免费账户并设置一个摄取 API 密钥

在与 `main.ts` 文件相同的目录下,创建一个 `Dockerfile` 和一个 `otel-collector.yml` 文件。`Dockerfile` 将用于构建 Docker 镜像:

Dockerfile
FROM otel/opentelemetry-collector:latest

COPY otel-collector.yml /otel-config.yml

CMD ["--config", "/otel-config.yml"]

FROM otel/opentelemetry-collector:latest - 这一行指定了容器的基础镜像。它使用官方的 OpenTelemetry Collector 镜像并拉取最新版本。

COPY otel-collector.yml /otel-config.yml - 这条指令将我们名为 `otel-collector.yml` 的配置文件从本地构建上下文复制到容器中。该文件在容器内部被重命名为 `/otel-config.yml`。

CMD ["--config", "/otel-config.yml"] - 这设置了容器启动时将运行的默认命令。它告诉 OpenTelemetry Collector 使用我们在上一步中复制的配置文件。

接下来,将以下内容添加到您的 `otel-collector.yml` 文件中,以定义遥测数据应如何收集并导出到 Honeycomb:

otel-collector.yml
receivers:
  otlp:
    protocols:
      grpc:
        endpoint: 0.0.0.0:4317
      http:
        endpoint: 0.0.0.0:4318

exporters:
  otlp:
    endpoint: "api.honeycomb.io:443"
    headers:
      x-honeycomb-team: $_HONEYCOMB_API_KEY

processors:
  batch:
    timeout: 5s
    send_batch_size: 5000

service:
  pipelines:
    logs:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    traces:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]
    metrics:
      receivers: [otlp]
      processors: [batch]
      exporters: [otlp]

receivers 部分配置了收集器如何接收数据。它设置了一个 OTLP (OpenTelemetry Protocol) 接收器,该接收器监听 `gRPC` 和 `HTTP` 两种协议,`0.0.0.0` 地址表示它将接受来自任何来源的数据。

exporters 部分定义了收集到的数据应该发送到哪里。它配置为将数据发送到 Honeycomb 的 API 端点 `api.honeycomb.io:443`。该配置需要一个 API 密钥进行身份验证,请将 `$_HONEYCOMB_API_KEY` 替换为您实际的 Honeycomb API 密钥。

processors 部分定义了数据在导出前应如何处理。它使用批处理,超时时间为 5 秒,最大批处理大小为 5000 项。

service 部分通过定义三个管道将所有内容连接在一起。每个管道负责不同类型的遥测数据。日志管道收集应用程序日志。跟踪管道用于分布式跟踪数据。指标管道用于性能指标。

使用以下命令构建并运行 Docker 实例以开始收集您的遥测数据:

docker build -t otel-collector . && docker run -p 4317:4317 -p 4318:4318 otel-collector

生成遥测数据 跳转到标题

现在我们已经设置好了应用程序和 Docker 容器,可以开始生成遥测数据了。使用这些环境变量运行您的应用程序,将数据发送到收集器:

OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
OTEL_SERVICE_NAME=chat-app \
OTEL_DENO=true \
deno run --unstable-otel --allow-net --allow-env --env-file --allow-read main.ts

此命令:

  • 将 OpenTelemetry 导出器指向您的本地收集器 (`localhost:4318`)
  • 在 Honeycomb 中将您的服务命名为 "chat-app"
  • 启用 Deno 的 OpenTelemetry 集成
  • 以必要的权限运行您的应用程序

要生成一些遥测数据,请在浏览器中向您正在运行的应用程序 `http://localhost:8000` 发出一些请求。

每个请求将:

  1. 在应用程序中流动时生成跟踪
  2. 从应用程序的控制台输出发送日志
  3. 创建有关请求性能的指标
  4. 通过收集器将所有这些数据转发到 Honeycomb

查看遥测数据 跳转到标题

向您的应用程序发出一些请求后,您将在 `Honeycomb.io` 控制面板中看到三种类型的数据:

  1. 跟踪 - 跨系统端到端请求流
  2. 日志 - 控制台输出和结构化日志数据
  3. 指标 - 性能和资源利用率数据

Viewing traces in Honeycomb

您可以深入查看单个 Span 以调试性能问题

Viewing expanded traces in Honeycomb

🦕 现在您已经成功导出了遥测数据,您可以:

  1. 添加自定义 Span 和属性以更好地理解您的应用程序
  2. 根据延迟或错误条件设置警报
  3. 使用以下平台将您的应用程序和收集器部署到生产环境:

有关 OpenTelemetry 配置的更多详细信息,请查阅 Honeycomb 文档

您找到所需内容了吗?

隐私政策