xk6-client-tracing

[!WARNING] 开发中 本项目处于开发阶段，提交之间变化较大。请自行承担使用风险。

⚠️ 开发中

本项目处于开发阶段，提交之间变化较大。请自行承担使用风险。

此扩展为k6提供了负载测试分布式追踪后端所需的功能。

使用方法

生成追踪数据并将其发送到代理或后端需要两个组件：客户端和追踪生成器。生成器具有名为traces()的方法，可用于生成追踪数据。客户端提供push()方法，该方法接收生成的追踪数据作为第一个参数，并将其发送到配置的收集器。

创建客户端需要客户端配置：

const config = {
endpoint: "localhost:4317",
exporter: tracing.EXPORTER_OTLP,
};
let client = new tracing.Client(config);

配置是一个具有以下架构的对象：

{
// 发送追踪数据的端点，格式为 <主机名>:<端口>
endpoint: string,
// 用于发送追踪数据的导出器协议：tracing.EXPORTER_OTLP 或 tracing.EXPORTER_JAEGER
exporter: string,
// 用于身份验证的凭据（可选）
authentication: { user: string, password: string },
// 客户端发送的额外标头（可选）
headers: { string : string }
// TLS 配置
tls: {
// 是否允许不安全连接（可选，默认：false）
insecure: boolean,
// 启用TLS但跳过验证（可选，默认：false）
insecure_skip_verify: boolean,
// 客户端请求的服务器名称（可选）
server_name: string,
// CA证书文件的路径（可选）
ca_file: string,
// 证书文件的路径（可选）
cert_file: string,
// 密钥文件的路径（可选）
key_file: string,
},
}

以下部分将介绍两种不同类型的生成器。

参数化追踪生成器

此生成器创建由完全随机化的跨度组成的追踪数据。跨度包含可配置数量的随机属性，这些属性具有随机分配的值。该生成器的主要目的是用少量代码创建大量跨度。

示例可在 ./examples/param 中找到。

模板化追踪生成器

此生成器创建看起来真实的追踪数据，其中包含具有跨度名称、跨度类型和属性的跨度。追踪数据由描述如何生成每个跨度的模板配置生成。

以下代码创建一个生成包含单个跨度的追踪数据的生成器：

const template = {
spans: [
{service: "article-service", name: "get-articles", attributes: {"http.request.method": "GET"}}
]
};
let gen = new tracing.TemplatedGenerator(template);
client.push(gen.traces());

生成的跨度将具有名称 get-articles。生成器还将分配跨度类型以及一些常用属性。还将有一个对应的资源跨度，带有相应的 service.name 属性。

模板具有以下架构：

{
// 默认值可用于配置应用于所有跨度的参数（可选）
defaults: {
// 添加到每个生成的跨度的固定属性（可选）
attributes: { string : any },
// attributeSemantics 可用于生成遵循特定 OpenTelemetry 语义约定的属性。例如 tracing.SEMANTICS_HTTP（可选）
attributeSemantics: string,
// 配置随机属性创建的参数。如果缺失，则不会向跨度添加随机属性（可选）
randomAttributes: {
// 要生成的随机属性数量
count: int,
// 为每个属性生成的不同值数量（可选，默认：50）
cardinality: int
}
// 追踪中所有资源的默认资源属性（可选）
resource: {
// 添加到每个资源的固定属性（可选）
attributes: { string : any },
// 配置随机资源属性创建的参数（可选）
randomAttributes: {
// 要生成的随机属性数量
count: int,
// 为每个属性生成的不同值数量（可选，默认：50）
cardinality: int
}
}
},
// 各个跨度的模板
spans: [
{
// 用于设置相应资源跨度的 service.name 属性
service: string,
// 跨度名称。如果为空，名称将随机生成（可选）
name: string,
// `spans` 中父跨度的索引。索引必须小于自身索引。如果为空，父级是 `spans` 中此跨度之前的直接位置的跨度（可选）
parentIdx: int,
// 生成的跨度持续时间的区间。如果缺失，将生成比父跨度持续时间短的随机持续时间（可选）
duration: { min: int, max: int },
// 添加到此跨度的固定属性（可选）
attributes: { string : any },
// attributeSemantics 可用于生成遵循特定 OpenTelemetry 语义约定的属性。例如 tracing.SEMANTICS_HTTP（可选）
attributeSemantics: string,
// 配置随机属性创建的参数。如果缺失，则不会向跨度添加随机属性（可选）
randomAttributes: {
// 要生成的随机属性数量
count: int,
// 为每个属性生成的不同值数量（可选，默认：50）
cardinality: int
},
// 与此跨度关联的资源的额外属性。具有相同服务名称的不同跨度的资源属性定义将合并为单个资源（可选）
resource: {
// 添加到资源的固定属性（可选）
attributes: { string : any },
// 配置随机资源属性创建的参数（可选）
randomAttributes: {
// 要生成的随机属性数量
count: int,
// 为每个属性生成的不同值数量（可选，默认：50）
cardinality: int
}
}
},
...
]
}

模板化生成器的示例可在 ./examples/template 中找到。

本地构建

本地构建扩展需要额外的先决条件：

• Go 工具链
• Git

此外，构建还需要 xk6 来编译带有捆绑追踪扩展的 k6。运行以下命令安装 xk6：

go install go.k6.io/xk6/cmd/xk6@latest

要构建二进制文件，请运行：

make build

构建步骤会生成 k6-tracing 二进制文件。要测试该二进制文件，首先需要将客户端配置中的端点修改为：

const client = new tracing.Client({
endpoint: "localhost:4317",
exporter: "otlp",
insecure: true,
});

准备好新的二进制文件和配置后，可以运行本地 OTEL collector：

docker run --rm -p 13133:13133 -p 14250:14250 -p 14268:14268 \
-p 55678-55679:55678-55679 -p 4317:4317 -p 9411:9411 \
-v "${PWD}/examples/shared/collector-config.yaml":/collector-config.yaml \
--name otelcol otel/opentelemetry-collector \
--config collector-config.yaml

完成后，可以运行如下测试：

./k6-tracing run examples/basic/param.js

然后就能在 OTEL collector 日志中看到生成的跨度！

与 Grafana Cloud 一起使用扩展

通过使用 OTLP 导出器并设置所需的身份验证凭据，可以实现这一点：

const client = new tracing.Client({
endpoint: "you-tempo-endpoint:443"
exporter: "otlp",
insecure: false,
authentication: {
user: "tenant-id",
password: "api-token"
}
});

---

项目仓库 README（补充）

xk6-client-tracing

⚠️ 开发中

本项目正在开发中，提交之间变化较大。请自行承担使用风险。

此扩展为 k6 提供了负载测试分布式追踪后端所需的功能。

用法

生成跟踪并将其发送到代理或后端需要两个组件：客户端和跟踪生成器。生成器具有一个名为 traces() 的方法，可用于生成跟踪。客户端提供一个 push() 方法，该方法接收生成的跟踪作为第一个参数，并将其发送到配置的 collector。

创建客户端需要客户端配置：

const config = {
endpoint: "localhost:4317",
exporter: tracing.EXPORTER_OTLP,
};
let client = new tracing.Client(config);

配置是一个具有以下架构的对象：

{
// 跟踪发送到的端点，格式为 <host>:<port>
endpoint: string,
// 用于发送跟踪的导出器协议：tracing.EXPORTER_OTLP 或 tracing.EXPORTER_JAEGER
exporter: string,
// 用于身份验证的凭据（可选）
authentication: { user: string, password: string },
// 客户端发送的额外标头（可选）
headers: { string : string }
// TLS 配置
tls: {
// 是否允许不安全连接（可选，默认：false）
insecure: boolean,
// 启用 TLS 但跳过验证（可选，默认：false）
insecure_skip_verify: boolean,
// 客户端请求的服务器名称（可选）
server_name: string,
// CA 证书文件的路径（可选）
ca_file: string,
// 证书文件的路径（可选）
cert_file: string,
// 密钥文件的路径（可选）
key_file: string,
},
}

有两种不同类型的生成器，将在以下部分中描述。

参数化跟踪生成器

此生成器创建由完全随机化的跨度组成的跟踪。这些跨度包含可配置数量的随机属性，属性值也是随机分配的。此生成器的主要目的是用少量代码创建大量跨度。

示例可在 ./examples/param 中找到。

模板化跟踪生成器

此生成器创建看起来更真实的跟踪，其中包含具有跨度名称、跨度类型和属性的跨度。跟踪是根据描述如何生成每个跨度的模板配置生成的。

以下代码创建一个生成包含单个跨度的跟踪的生成器：

const template = {
spans: [
{service: "article-service", name: "get-articles", attributes: {"http.request.method": "GET"}}
]
};
let gen = new tracing.TemplatedGenerator(template);
client.push(gen.traces());

生成的跨度将具有名称 get-articles。生成器还会分配一个跨度类型以及一些常用属性。还会有一个对应的资源跨度，带有相应的 service.name 属性。

该模板具有以下架构：

带模板生成器的示例可在./examples/template中找到。

快速开始

要开始使用k6 tracing扩展，请确保已安装以下先决条件：

• Docker
• docker-compose
• make

构建Docker镜像

Docker镜像使用多阶段Docker构建进行编译，无需其他依赖。要启动构建过程，请运行：

make docker

命令成功完成后，将生成grafana/xk6-client-tracing:latest镜像。

运行docker-compose示例

[!NOTE] 在运行docker-compose示例之前，请确保已完成上述Docker镜像构建步骤！

要运行示例，请cd进入examples/param目录并运行：

docker-compose up -d

在此示例中，k6-tracing使用脚本param.js生成跨度并将其发送到otel-collector。可通过查看收集器日志观察生成的跨度：

docker-compose logs -f otel-collector

该示例使用OTLP gRPC导出器。如果要使用Jaeger gRPC，可以修改param.js并使用以下设置：

const client = new tracing.Client({
endpoint: "otel-collector:14250",
exporter: "jaeger",
insecure: true,
});

[!NOTE] 尚不支持HTTP导出器

本地构建

本地构建扩展需要额外的先决条件：

• Go toolchain
• Git

此外，构建还需要https://github.com/grafana/xk6%E6%9D%A5%E7%BC%96%E8%AF%91%E5%8C%85%E5%90%ABtracing%E6%89%A9%E5%B1%95%E7%9A%84k6%E3%80%82%E8%BF%90%E8%A1%8C%E4%BB%A5%E4%B8%8B%E5%91%BD%E4%BB%A4%E5%AE%89%E8%A3%85%60xk6%60%EF%BC%9A

go install go.k6.io/xk6/cmd/xk6@latest

要构建二进制文件，请运行：

make build

构建步骤将生成k6-tracing二进制文件。要测试该二进制文件，首先需要将客户端配置中的端点修改为：

const client = new tracing.Client({
endpoint: "localhost:4317",
exporter: "otlp",
insecure: true,
});

准备好新的二进制文件和配置后，可以运行本地OTEL收集器：

docker run --rm -p 13133:13133 -p 14250:14250 -p 14268:14268 \
-p 55678-55679:55678-55679 -p 4317:4317 -p 9411:9411 \
-v "${PWD}/examples/shared/collector-config.yaml":/collector-config.yaml \
--name otelcol otel/opentelemetry-collector \
--config collector-config.yaml

完成后，可以运行如下测试：

./k6-tracing run examples/basic/param.js

然后在OTEL收集器日志中查看生成的跨度！

与Grafana Cloud一起使用扩展

为此，可使用OTLP导出器并设置所需的身份验证凭据：

const client = new tracing.Client({
endpoint: "you-tempo-endpoint:443"
exporter: "otlp",
insecure: false,
authentication: {
user: "tenant-id",
password: "api-token"
}
});