Build a k6 binary using Go | Grafana k6 documentation (original) (raw)

Open source

To use an extension that you found on theExtension page or thexk6 GitHub topic, you need to build a binary using Go.

Before you start

Installing xk6

Given the prerequisite Go setup, installingxk6 itself requires only the following command:

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

To confirm your installation, run which xk6 on Linux and Mac, or where xk6 on Windows. Make sure the command returns a valid path.

If not, check that you’ve correctly defined the$GOPATH environment variable and that $GOPATH/binis in your $PATH. See theGo documentationfor details.

Building your first extension

Once installed, building a k6 binary with one or more extensions can be done with the xk6 buildcommand as follows:

xk6 build latest \
  --with github.com/grafana/xk6-sql@v0.0.1 \
  --with github.com/grafana/xk6-output-prometheus-remote

Once completed, the current directory contains your newly built k6 binary with thexk6-sql andxk6-output-prometheus-remoteextensions.

... [INFO] Build environment ready
... [INFO] Building k6
... [INFO] Build complete: ./k6

xk6 has now produced a new k6 binary which may be different than the command on your system path!
Be sure to run './k6 run <SCRIPT_NAME>' from the '...' directory.

Breaking down the xk6 command

From thexk6 documentation, the command-line usage is as follows:

xk6 build [<k6_version>]
    [--output <file>]
    [--with <module[@version][=replacement]>...]
    [--replace <module=replacement>...]

Flags:
  --output   specifies the new binary name [default: 'k6']
  --replace  enables override of dependencies for k6 and extensions [default: none]
  --with     the extension module to be included in the binary [default: none]

The use of --replace should be considered an advanced feature to be avoided unless required.

Referring back to our executed command, note that:

Running ./k6 version should show your build is based upon the appropriate version.

Building from a local repository

Suppose now you’ve cloned the xk6-sql repository and want the local version included in your custom binary? From the cloned directory, we would then use:

--with github.com/grafana/xk6-sql=.

Based upon the command usage described in the previous section, this tells xk6 to use the current directory as the replacement for the module.

Running your extended binary

Now that we have our newly built k6 binary, we can run scripts using the functionalities of the bundled extensions.

Be sure to specify the binary just built in the current directory as ./k6, or else Linux/Mac could execute another k6 binary on your system path. Windows shells will first search for the binary in the current directory by default.