菜单
文档breadcrumb arrow Beylabreadcrumb arrow 快速入门breadcrumb arrow Node.js 快速入门
Grafana Cloud

快速入门：使用 Beyla 观测 Node.js 服务

1. 运行可观测的 Node.js 服务

运行一个可插桩的 Node.js 服务，或下载并运行一个简单的示例 Node.js HTTP 服务。

curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/nodejs/package.json
curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/nodejs/quickstart.js
npm install && npm start

2. 下载 Beyla

从 Beyla 发布页面 下载最新的 Beyla 可执行文件。解压缩并将 Beyla 可执行文件复制到您 $PATH 中的任意位置。

3. (可选) 获取 Grafana Cloud 凭据

Beyla 可以将指标和追踪数据导出到任何 OpenTelemetry 端点，也可以将指标作为 Prometheus 端点暴露。然而，我们建议使用 Grafana Cloud 中的 OpenTelemetry 端点。您可以在 Grafana 网站上获取免费的 Grafana Cloud 账户。

在 Grafana Cloud Portal 中，找到 OpenTelemetry 框并点击 Configure。

OpenTelemetry Grafana Cloud portal

在 Password / API token 下，点击 Generate now 并按照说明创建默认的 API token。

Environment Variables 将会填充一套标准的 OpenTelemetry 环境变量，这些变量将为 Beyla 提供连接端点和凭据信息。

OTLP connection headers

复制 Environment Variables 并保留以供下一步使用。

4. 使用最小配置运行 Beyla

要运行 Beyla，首先设置以下环境变量

  • 从上一步复制的 OTEL_EXPORTER_OTLP_PROTOCOL、OTEL_EXPORTER_OTLP_ENDPOINT 和 OTEL_EXPORTER_OTLP_HEADERS 变量。
  • BEYLA_OPEN_PORT: 插桩服务正在使用的端口（例如，80 或 443）。如果使用本指南第一部分中的示例服务，将此变量设置为 8080。

为了方便本地测试，设置 BEYLA_TRACE_PRINTER=text 环境变量。设置此选项后，Beyla 会将追踪数据以文本格式打印到标准输出。

同时设置 BEYLA_SERVICE_NAME=quickstart 以覆盖追踪数据和指标中报告的服务名称。如果未设置，Beyla 将自动报告进程可执行文件的名称：node。

注意：Beyla 需要管理员 (sudo) 权限，或者至少需要授予 CAP_SYS_ADMIN 能力。

sh 
export BEYLA_SERVICE_NAME=quickstart
export BEYLA_OPEN_PORT=8080
export BEYLA_TRACE_PRINTER=text
export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://otlp-gateway-prod-eu-west-0.grafana.net/otlp"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ...your-encoded-credentials..."
sudo -E beyla

5. 测试服务

在 Beyla 和服务都在运行的情况下，向插桩服务发送 HTTP 请求

curl https://:8080/foo

Beyla 应向标准输出打印类似以下的追踪数据

2024-01-09 10:31:33.19103133 (3.254486ms[3.254486ms]) 200 GET /foo [127.0.0.1]->[127.0.0.1:8080]
size:80B svc=[{quickstart nodejs lima-ubuntu-lts-5074}] traceparent=[00-46214bd23716280eef43cf798dbe5522-0000000000000000-01]

上述追踪数据显示

  • 2024-01-09 10:31:33.19103133: 追踪的时间
  • (3.254486ms[3.254486ms]): 请求的总响应时间
  • 200 GET /foo: 响应码、HTTP 方法和 URL 路径
  • [127.0.0.1]->[127.0.0.1:8080] 源和目的主机:端口
  • size:80B: HTTP 请求大小（头部和正文的总和）
  • svc=[{quickstart nodejs lima-ubuntu-lts-5074}]: quickstart 服务，运行在 Node.js 中，自动生成的服务实例名称为 lima-ubuntu-lts-5074
  • traceparent：由父请求接收到的值，如果父请求未指定，则为新的随机值

几分钟后，追踪数据将出现在 Grafana Cloud 中。例如，在追踪资源管理器中

Beyla traces explorer

6. 配置路由

Grafana Cloud 中显示的 span 名称是通用的 GET /**，但它应该显示类似 GET /foo 的内容（测试请求 URL 的路径）。

Beyla 将任何未知 URL 路径分组为 /**，以避免意外的基数爆炸。

配置路由以告知 Beyla 预期的路由。

对于此快速入门，让 Beyla 启发式地分组路由。

首先，创建一个包含以下内容的 config.yml 文件

yml 
routes:
  unmatched: heuristic

然后，使用 -config 参数运行 Beyla（或使用 BEYLA_CONFIG_PATH 环境变量代替）

sudo -E beyla -config config.yml

最后，发送 HTTP 请求

curl https://:8080/foo
curl https://:8080/user/1234
curl https://:8080/user/5678

现在 Grafana 将为每个追踪数据启发式地分配一个路由。/foo 有了自己的路由，而 /user/1234 和 /user/5678 则被分组到 /user/* 路由下。

Beyla grouped traces

下一步