deno.com
本页内容

如何将遥测数据导出到 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 环境变量

.env
OPENAI_API_KEY=your_openai_api_key

设置 Docker 收集器 跳转到标题

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

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

Dockerfile
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 堆栈。点击“详情”。

Click details on your Grafana Cloud stack

接下来,找到“OpenTelemetry”并点击“配置”。

Find and configure OpenTelemetry

此页面将为您提供配置 OpenTelemetry 收集器所需的所有详细信息。记下您的 OTLP 端点实例 ID密码 / API 令牌(您需要生成一个)。

Configuring OTel in Grafana Cloud

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

otel-collector.yml
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 协议)接收器,监听 gRPCHTTP 两种协议,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,对正在运行的应用程序进行几次请求。

每个请求将:

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

查看遥测数据 跳转到标题

对您的应用程序进行一些请求后,您将在 Grafana Cloud 仪表盘中看到三种类型的数据

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

Viewing logs in Grafana

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

Viewing traces in Grafana

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

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

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

您找到所需内容了吗?

隐私政策