ghcr.io/grafana/xk6-client-tracing:v0.0.10

xk6-client-tracing

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

⚠️ 开发中

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

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

用法

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

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 },
// OTLP服务器支持的额外压缩类型
compression: 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,
},
}

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

参数化追踪生成器

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

示例可在./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属性。

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中找到。

快速开始

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

• Docker
• docker-compose
• make

构建Docker镜像

Docker镜像使用多阶段Docker构建进行编译，不需要其他依赖项。要开始构建过程，请运行：

make docker

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

grafana/xk6-client-tracing:latest

运行docker-compose示例

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

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

本地构建

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

• 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 日志中查看生成的跨度！

{
// 可使用默认值配置应用于所有跨度的参数（可选）
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 中可找到带模板生成器的示例。

快速开始

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

• Docker
• docker-compose
• make

构建 Docker 镜像

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

make docker

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

运行 docker-compose 示例

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

要运行示例，请进入 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 工具链
• Git

此外，构建还需要 https://github.com/grafana/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 收集器：

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"
}
});