如何将遥测数据导出到 Honeycomb
OpenTelemetry(通常缩写为 OTel)是一个开源可观测性框架,提供了一种标准化方式来收集和导出遥测数据,例如跟踪、指标和日志。Deno 内置支持 OpenTelemetry,让您可以轻松地检测应用程序而无需添加外部依赖项。此集成可与 Honeycomb 等可观测性平台即开即用。
Honeycomb 是一个可观测性平台,旨在调试和理解复杂的现代分布式系统。
在本教程中,我们将构建一个简单的应用程序,并将其遥测数据导出到 Honeycomb。我们将涵盖:
您可以在 GitHub 上找到本教程的完整源代码。
设置您的聊天应用 跳转到标题
在本教程中,我们将使用一个简单的聊天应用程序来演示如何导出遥测数据。您可以在 GitHub 上找到该应用程序的代码。
您可以复制该存储库,或者创建一个 `main.ts` 文件和一个 `.env` 文件。
为了运行该应用程序,您需要一个 OpenAI API 密钥。您可以通过在 OpenAI 注册账户并创建一个新的秘密密钥来获取。您可以在 OpenAI 账户的 API 密钥部分找到您的 API 密钥。获得 API 密钥后,在您的 `.env` 文件中设置一个 `OPENAI_API_KEY` 环境变量:
OPENAI_API_KEY=your_openai_api_key
设置 Docker 收集器 跳转到标题
接下来,我们将设置一个 Docker 容器来运行 OpenTelemetry 收集器。该收集器负责接收您应用程序的遥测数据并将其导出到 Honeycomb。
如果您还没有 Honeycomb 账户,请创建一个免费账户并设置一个摄取 API 密钥。
在与 `main.ts` 文件相同的目录下,创建一个 `Dockerfile` 和一个 `otel-collector.yml` 文件。`Dockerfile` 将用于构建 Docker 镜像:
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:
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` 发出一些请求。
每个请求将:
- 在应用程序中流动时生成跟踪
- 从应用程序的控制台输出发送日志
- 创建有关请求性能的指标
- 通过收集器将所有这些数据转发到 Honeycomb
查看遥测数据 跳转到标题
向您的应用程序发出一些请求后,您将在 `Honeycomb.io` 控制面板中看到三种类型的数据:
- 跟踪 - 跨系统端到端请求流
- 日志 - 控制台输出和结构化日志数据
- 指标 - 性能和资源利用率数据
您可以深入查看单个 Span 以调试性能问题
🦕 现在您已经成功导出了遥测数据,您可以:
- 添加自定义 Span 和属性以更好地理解您的应用程序
- 根据延迟或错误条件设置警报
- 使用以下平台将您的应用程序和收集器部署到生产环境:
有关 OpenTelemetry 配置的更多详细信息,请查阅 Honeycomb 文档。