README
¶
xk6-client-tracing
This extension provides k6 with the required functionality required to load test distributed tracing backends, specifically OpenTelemetry and Jaeger.
Read more about k6 extensions.
Read more about the k6 Go/js bridge.
Getting started
To start using k6 with the extension, ensure you have the prerequisites:
- Go toolchain
- Git
See also .tool-versions for asdf support.
Then:
- Build the custom k6 binary:
make
Once you've your new binary ready, you can run a local OTEL collector and Jaeger instance with:
docker compose up
Once that's done, you can run a test like:
./bin/k6 run examples/basic.js
And see your spans on the OTEL collector logs!
Open the Jaeger UI at http://localhost:16686/ and you should see your traces there too.
The example uses the OTLP gRPC exporter. If you want to use OTLP HTTP exporter, you can use these settings:
const client = new tracing.Client({
endpoint: "0.0.0.0:4318/v1/traces",
exporter: "otlphttp",
insecure: true,
});
API
Import this module in your k6 script:
import tracing from 'k6/x/tracing';
Make a tracing client:
const client = new tracing.Client({
endpoint: "http://0.0.0.0:4318/v1/traces",
// exporter is optional - defaults to otlp
exporter: "otlphttp",
// headers can be a map of anything
headers: {
'Authorization': 'Bearer potato',
},
// insecure is optional - defaults to false
// if true, it will use a non-TLS connection
insecure: true,
// insecure_skip_verify is optional - defaults to false
// if true, it will skip TLS validation
insecure_skip_verify: true,
// loglevel is optional - defaults to info
// maps to zapcore.Level
loglevel: "debug"
});
Send one or more traces:
client.push([{
// TraceID to use for this trace in hex format
id: traceUUID,
// random_service_name is optional - defaults to false
// if true, it will add random characters into service names
random_service_name: true,
// start_time is optional
// if set this is used for each span start time
// otherwise the current time is used
start_time: new Date(),
spans: {
// the number of spans to generate for the trace ID
count: 1,
// generated attributes collection in bytes
size: 50,
// random_name is optional - defaults to false
// adds a random string to the end of selected span name
random_name: true,
// fixed attributes to send with each span
fixed_attrs: {
"test": "foo"
}
}
}])
client.pushDebug([...]) will also log some info to the console.
You can use tracing.generateRandomTraceID() to create a valid random trace ID.
client.exportMetrics() will export the metrics collected by OTEL client to k6. This can impact on sending speed so is optional.
At the end of your k6 script, do:
export function teardown() {
client.shutdown();
}
License
While k6 is licensed under GNU AGPLv3 scripts using k6 and xk6 extensions can be licensed however we like as long as they are not distributed as part of a product.
References:
- https://k6.io/blog/extending-k6-with-xk6/ - suggests extension authors use Apache 2.0.
- https://community.k6.io/t/k6-licensing-agplv3/395 - support discussion for licensing.
- https://github.com/grafana/xk6-amqp - official xk6 extension using the Apache 2.0 license.
- https://github.com/grafana/xk6-kubernetes - and another, as are all others.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client is a tracing client exported to the k6 script.
func (*Client) ExportMetrics ¶
func (c *Client) ExportMetrics()
ExportMetrics converts otel collector metrics to k6 metrics
func (*Client) Push ¶
func (c *Client) Push(te []TraceEntry) *goja.Object
Push pushes a trace entry to the collector. Note - depending on the collector config this may just push to a queue and not actually send the data.
type ClientTracing ¶
type ClientTracing struct {
// contains filtered or unexported fields
}
ClientTracing is the k6 module for tracing.
func (*ClientTracing) Exports ¶
func (r *ClientTracing) Exports() modules.Exports
func (*ClientTracing) GenerateRandomTraceID ¶
func (c *ClientTracing) GenerateRandomTraceID() string
GenerateRandomTraceID generates a random trace ID encoded as a hex string.
func (*ClientTracing) NewClient ¶
func (c *ClientTracing) NewClient(g goja.ConstructorCall) *goja.Object
NewClient creates a new tracing client from the given config.
type Config ¶
type Config struct {
// OTLP exporter type.
Exporter exporterName
// OTLP exporter endpoint.
Endpoint string
// Insecure allows insecure connection to the collector.
Insecure bool
// InsecureSkipVerify allows TLS without a valid certificate.
InsecureSkipVerify bool
// Headers to be added to the request.
Headers map[string]configopaque.String
// LogLevel sets the log level of the exporter.
Loglevel string
}
Config holds the configuration for the tracing client.
type SpansEntry ¶
type SpansEntry struct {
Count int `json:"count"`
Size int `json:"size"`
RandomName bool `json:"random_name"`
FixedAttrs map[string]interface{} `json:"fixed_attrs"`
}
SpansEntry holds the config to generate spans.
type TraceEntry ¶
type TraceEntry struct {
ID string `json:"id"`
// StartTime is an optional start time for the trace.
StartTime time.Time `json:"start_time"`
RandomServiceName bool `json:"random_service_name"`
Spans SpansEntry `json:"spans"`
}
TraceEntry holds the config to generate a trace.
Source Files