如何将遥测数据导出到 Grafana
OpenTelemetry(通常缩写为 OTel)是一个开源可观测性框架,它提供了一种标准化的方式来收集和导出遥测数据,例如追踪、指标和日志。Deno 内置支持 OpenTelemetry,从而无需添加外部依赖即可轻松地为您的应用程序添加观测功能。这种集成可以与 Grafana 等可观测性平台无缝协作。
Grafana 是一个开源可观测性平台,允许 DevOps 团队实时可视化、查询和告警来自不同数据源的指标、日志和追踪。它广泛用于构建仪表盘,以监控基础设施、应用程序和系统健康状况。
Grafana 还提供了一个托管版本,名为 Grafana Cloud。本教程将帮助您配置项目,以便将 OTel 数据导出到 Grafana Cloud。
在本教程中,我们将构建一个简单的应用程序,并将其遥测数据导出到 Grafana Cloud。我们将介绍
您可以在 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 收集器。收集器负责从您的应用程序接收遥测数据并将其导出到 Grafana Cloud。
在您的 main.ts
文件所在的同一目录下,创建一个 Dockerfile
和一个 otel-collector.yml
文件。Dockerfile
将用于构建 Docker 镜像
FROM otel/opentelemetry-collector-contrib:latest
COPY otel-collector.yml /otel-config.yml
CMD ["--config", "/otel-config.yml"]
FROM otel/opentelemetry-collector-contrib:latest
- 此行指定了容器的基础镜像。它使用官方的 OpenTelemetry Collector Contributor 镜像,该镜像包含所有接收器、导出器、处理器、连接器和其他可选组件,并拉取最新版本。
COPY otel-collector.yml /otel-config.yml
- 此指令将名为 otel-collector.yml
的配置文件从本地构建上下文复制到容器中。该文件在容器内部被重命名为 /otel-config.yml
。
CMD ["--config", "/otel-config.yml"]
- 这设置了容器启动时将运行的默认命令。它指示 OpenTelemetry 收集器使用我们在上一步中复制的配置文件。
接下来,让我们设置一个 Grafana Cloud 账户并获取一些信息。
如果您尚未注册,请创建一个免费的 Grafana Cloud 账户。创建后,您将收到一个 Grafana Cloud 堆栈。点击“详情”。
接下来,找到“OpenTelemetry”并点击“配置”。
此页面将为您提供配置 OpenTelemetry 收集器所需的所有详细信息。记下您的 OTLP 端点、实例 ID 和 密码 / API 令牌(您需要生成一个)。
接下来,将以下内容添加到您的 otel-collector.yml
文件中,以定义如何收集遥测数据并将其导出到 Grafana Cloud
receivers:
otlp:
protocols:
grpc:
endpoint: 0.0.0.0:4317
http:
endpoint: 0.0.0.0:4318
exporters:
otlphttp/grafana_cloud:
endpoint: $_YOUR_GRAFANA_OTLP_ENDPOINT
auth:
authenticator: basicauth/grafana_cloud
extensions:
basicauth/grafana_cloud:
client_auth:
username: $_YOUR_INSTANCE_ID
password: $_YOUR_API_TOKEN
processors:
batch:
service:
extensions: [basicauth/grafana_cloud]
pipelines:
traces:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp/grafana_cloud]
metrics:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp/grafana_cloud]
logs:
receivers: [otlp]
processors: [batch]
exporters: [otlphttp/grafana_cloud]
receivers
部分配置了收集器如何接收数据。它设置了一个 OTLP(OpenTelemetry 协议)接收器,监听 gRPC
和 HTTP
两种协议,0.0.0.0
地址表示它将接受来自任何来源的数据。
exporters
部分定义了收集到的数据应该发送到哪里。请务必包含您的 Grafana Cloud 实例提供的 OTLP 端点。
extensions
部分定义了 OTel 将数据导出到 Grafana Cloud 的认证信息。请务必包含您的 Grafana Cloud 实例 ID,以及您生成的 密码 / 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
) - 在 Grafana Cloud 中将您的服务命名为“chat-app”
- 启用 Deno 的 OpenTelemetry 集成
- 以必要的权限运行您的应用程序
为了生成一些遥测数据,请在浏览器中访问 http://localhost:8000
,对正在运行的应用程序进行几次请求。
每个请求将:
- 在应用程序中流动时生成跟踪
- 从应用程序的控制台输出发送日志
- 创建有关请求性能的指标
- 通过收集器将所有这些数据转发到 Grafana Cloud
查看遥测数据 跳转到标题
对您的应用程序进行一些请求后,您将在 Grafana Cloud 仪表盘中看到三种类型的数据
- 追踪 - 您的系统中的端到端请求流
- 日志 - 控制台输出和结构化日志数据
- 指标 - 性能和资源利用率数据
您可以深入查看单个跨度以调试性能问题
🦕 现在您已经成功导出了遥测数据,您可以:
- 添加自定义跨度和属性以更好地理解您的应用程序
- 根据延迟或错误条件设置警报
- 使用以下平台将您的应用程序和收集器部署到生产环境,例如
有关 OpenTelemetry 配置的更多详细信息,请查阅 Grafana Cloud 文档。