|
| 1 | +--- |
| 2 | +title: 'OpenTelemetry' |
| 3 | +description: 'Use the OpenTelemetry output extension to send test results in OTEL metrics format.' |
| 4 | +weight: 00 |
| 5 | +--- |
| 6 | + |
| 7 | +# OpenTelemetry |
| 8 | + |
| 9 | +Grafana k6 can push test run metrics in the [OpenTelemetry (OTEL) metrics format](https://opentelemetry.io/docs/specs/otel/metrics/) to an OTEL metrics collector or a metrics backend that supports the OTEL metrics format by using the [xk6-output-opentelemetry extension](https://github.com/grafana/xk6-output-opentelemetry/). |
| 10 | + |
| 11 | +{{< admonition type="note" >}} |
| 12 | + |
| 13 | +This is an extension, and we're looking for feedback and contributions and aiming to graduate it as an experimental output within Grafana k6 in a future release. Feel free to [open an issue](https://github.com/grafana/xk6-output-opentelemetry/issues) if you have any feedback or suggestions. |
| 14 | + |
| 15 | +{{< /admonition >}} |
| 16 | + |
| 17 | +## Metrics mapping |
| 18 | + |
| 19 | +k6 converts all [k6 metric types](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/metrics) to an equivalent [OTEL metric type](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#timeseries-model), and all k6 tags to OTEL attributes. When possible, the units are also passed with the metrics. |
| 20 | + |
| 21 | +| k6 Metric | OpenTelemetry Metric | |
| 22 | +| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 23 | +| Counter | `Float64CounterOption` | |
| 24 | +| Gauge | `Float64ObservableGauge` | |
| 25 | +| Rate | Split into two `Int64Counter` counters named `metric_name.occurred` and `metric_name.total`. `metric_name.occurred` counts only the number of non-zero occurrences, and `metric_name.total` registers the total number of positive and negative occurrences. This might change in the future, refer to [xk6-output-opentelemetry#12](https://github.com/grafana/xk6-output-opentelemetry/issues/12) for more details. | |
| 26 | +| Trend | `Float64Histogram` | |
| 27 | + |
| 28 | +## Build the k6 version |
| 29 | + |
| 30 | +To build a k6 binary with the extension, first, make sure you have [Go](https://golang.org/doc/install) and [Git](https://git-scm.com/) installed on your machine. |
| 31 | + |
| 32 | +Then, open your terminal and run the following commands: |
| 33 | + |
| 34 | +```bash |
| 35 | +# Install xk6 |
| 36 | +go install go.k6.io/xk6/cmd/xk6@latest |
| 37 | + |
| 38 | +# Build the k6 binary |
| 39 | +xk6 build --with github.com/grafana/xk6-output-opentelemetry |
| 40 | + |
| 41 | +... [INFO] Build environment ready |
| 42 | +... [INFO] Building k6 |
| 43 | +... [INFO] Build complete: ./k6 |
| 44 | +``` |
| 45 | + |
| 46 | +xk6 will create the new k6 binary in the local folder. |
| 47 | + |
| 48 | +{{% admonition type="note" %}} |
| 49 | + |
| 50 | +To learn more about how to build custom k6 versions, refer to [xk6](https://github.com/grafana/xk6). |
| 51 | + |
| 52 | +{{% /admonition %}} |
| 53 | + |
| 54 | +## Run the k6 test |
| 55 | + |
| 56 | +Using the k6 binary you built in the previous step, you can use the `--out xk6-opentelemetry` option when running your tests to use this extension: |
| 57 | + |
| 58 | +{{< code >}} |
| 59 | + |
| 60 | +```bash |
| 61 | +$ ./k6 run --out xk6-opentelemetry script.js |
| 62 | +``` |
| 63 | + |
| 64 | +{{< /code >}} |
| 65 | + |
| 66 | +## Configuration |
| 67 | + |
| 68 | +The following options can be configured: |
| 69 | + |
| 70 | +| Name | Value | |
| 71 | +| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | |
| 72 | +| `K6_OTEL_METRIC_PREFIX` | Metric prefix. Default is empty. | |
| 73 | +| `K6_OTEL_FLUSH_INTERVAL` | How frequently to flush metrics from k6 metrics engine. Default is `1s`. | |
| 74 | +| `K6_OTEL_EXPORT_INTERVAL` | Configures the intervening time between metrics exports. Default is `10s`. | |
| 75 | +| `K6_OTEL_HEADERS` | Configures headers in the W3C Correlation-Context format without additional semi-colon delimited metadata (i.e. "k1=v1,k2=v2"). Passes the headers to the exporter. | |
| 76 | +| `K6_OTEL_TLS_INSECURE_SKIP_VERIFY` | Disables server certificate verification. | |
| 77 | +| `K6_OTEL_TLS_CERTIFICATE` | Configures the path to the root CA certificate file for TLS credentials. If it is not provided but TLS is enabled then the host's root CAs set is used. | |
| 78 | +| `K6_OTEL_TLS_CLIENT_CERTIFICATE` | Configures the path to the client certificate file. | |
| 79 | +| `K6_OTEL_TLS_CLIENT_KEY` | Configures the path to the client key file. | |
| 80 | +| `K6_OTEL_GRPC_EXPORTER_INSECURE` | Disables client transport security for the gRPC exporter. | |
| 81 | +| `K6_OTEL_GRPC_EXPORTER_ENDPOINT` | Configures the gRPC exporter endpoint. Default is `localhost:4317`. | |
| 82 | +| `K6_OTEL_HTTP_EXPORTER_INSECURE` | Disables client transport security for the HTTP exporter. | |
| 83 | +| `K6_OTEL_HTTP_EXPORTER_ENDPOINT` | Configures the HTTP exporter endpoint. Default is `localhost:4318`. | |
| 84 | +| `K6_OTEL_HTTP_EXPORTER_URL_PATH` | Configures the HTTP exporter path. Default is `/v1/metrics`. | |
| 85 | + |
| 86 | +You can also use the OpenTelemetry SDK configuration environment variables to configure the OpenTelemetry output, like the [gRPC exporter configuration ](https://pkg.go.dev/go.opentelemetry.io/otel/exporters/otlp/otlpmetric/[email protected]). The `K6_OTEL_*` environment variables take precedence over the OpenTelemetry SDK configuration environment variables. |
0 commit comments