菜单
文档breadcrumb arrow Beylabreadcrumb arrow 快速入门breadcrumb arrow Go 快速入门
Grafana Cloud

快速入门：使用 Beyla 检测 Go 服务

1. 运行一个可检测的 Go 服务

运行一个可检测的 Go 服务，或下载并运行一个简单的示例 Go HTTP 服务。

curl -OL https://raw.githubusercontent.com/grafana/beyla/main/examples/quickstart/golang/quickstart.go
go run quickstart.go

2. 下载 Beyla

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

作为替代方案（如果您的主机已安装 Go 工具集），您可以使用 go install 命令直接下载 Beyla 可执行文件

sh 
go install github.com/grafana/beyla/cmd/beyla@latest

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

Beyla 可以将指标和分布式追踪导出到任何 OpenTelemetry 端点，也可以将指标作为 Prometheus 端点暴露。但是，我们推荐使用 Grafana Cloud 中的 OpenTelemetry 端点。您可以在 Grafana 网站 获取免费的 Grafana Cloud 账户。

在 Grafana Cloud Portal 中，找到 OpenTelemetry 方框并点击 配置。

OpenTelemetry Grafana Cloud portal

在 Password / API token 下，点击 立即生成 并按照说明创建一个默认 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 需要管理员 (sudo) 权限，或者至少需要被授予 CAP_SYS_ADMIN 能力。

sh 
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-08 14:06:14.182614 (432.191µs[80.421µs]) 200 GET /foo [127.0.0.1]->[localhost:8080]
size:0B svc=[{quickstart  go lima-ubuntu-lts-8222}] traceparent=[00-0f82735dab5798dfbf7f7a26d5df827b-0000000000000000-01]

上述分布式追踪显示

  • 2024-01-08 14:06:14.182614: 分布式追踪的时间
  • (432.191µs[80.421µs]): 请求的总响应时间，其中包含请求的实际内部执行时间（不包括请求排队时间）
  • 200 GET /foo: 响应代码、HTTP 方法和 URL 路径
  • [127.0.0.1]->[localhost:8080] 源和目的 host:port
  • size:0B: HTTP 请求体的大小（0 字节，因为这是一个 GET 请求）。对于非 Go 程序，此大小还将包括请求头的大小
  • svc=[{quickstart go lima-ubuntu-lts-8222}]: quickstart 服务，用 Go 编写，服务实例名称自动创建为 lima-ubuntu-lts-8222
  • 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

后续步骤