diff --git a/docs/sources/next/javascript-api/jslib/http-instrumentation-tempo/_index.md b/docs/sources/next/javascript-api/jslib/http-instrumentation-tempo/_index.md index 8ceb739564..11294178db 100644 --- a/docs/sources/next/javascript-api/jslib/http-instrumentation-tempo/_index.md +++ b/docs/sources/next/javascript-api/jslib/http-instrumentation-tempo/_index.md @@ -9,6 +9,11 @@ weight: 04 With this jslib, you can _instrument_ HTTP requests so that they emit traces as the test runs. Use it to include a tracing context in HTTP requests, which can then be used by a tracing backend such as [Grafana Tempo](https://grafana.com/docs/grafana-cloud/testing/k6/analyze-results/integration-with-grafana-cloud-traces/). +## Migration from `k6/experimental/tracing` + +This jslib is a drop in replacement, so all you need to migrate to it is to replace `'k6/experimental/tracing'` import with `'https://jslib.k6.io/http-instrumentation-tempo/1.0.0/index.js'` + + ## About trace contexts A _trace context_ is a set of standardized HTTP headers added to a request that lets a tracing system correlate it with other requests as they navigate through a system. The trace context specifications, such as the supported [W3C Trace Context](https://www.w3.org/TR/trace-context/) and [Jaeger Trace Context](https://www.jaegertracing.io/docs/1.21/client-libraries/#propagation-format), define specific header names and an encoding format for the header values. diff --git a/docs/sources/next/javascript-api/k6-experimental/tracing/_index.md b/docs/sources/next/javascript-api/k6-experimental/tracing/_index.md index ea9cd4365c..bc2c83ae8c 100644 --- a/docs/sources/next/javascript-api/k6-experimental/tracing/_index.md +++ b/docs/sources/next/javascript-api/k6-experimental/tracing/_index.md @@ -7,7 +7,7 @@ weight: 04 # tracing -{{< docs/shared source="k6" lookup="experimental-module.md" version="" >}} +{{< docs/shared source="k6" lookup="experimental-tracing-module.md" version="" >}} With this experimental module, you can _instrument_ HTTP requests so that they emit traces as the test runs. diff --git a/docs/sources/next/javascript-api/k6-experimental/tracing/client.md b/docs/sources/next/javascript-api/k6-experimental/tracing/client.md index 28a8710a9d..682e1ea885 100644 --- a/docs/sources/next/javascript-api/k6-experimental/tracing/client.md +++ b/docs/sources/next/javascript-api/k6-experimental/tracing/client.md @@ -6,6 +6,8 @@ weight: 02 # Client +{{< docs/shared source="k6" lookup="experimental-tracing-module.md" version="" >}} + `Client` is an HTTP client constructor that attaches tracing information to its requests. Use it to include a tracing context in HTTP requests so that tracing backends (such as [Grafana Tempo](https://grafana.com/oss/tempo/)) can incorporate their results. The `Client` class acts as a drop-in replacement for the standard `http` module and attaches a [trace context](https://www.w3.org/TR/trace-context/) to the requests headers, and add a `trace_id` to HTTP-related k6 output's data points metadata. It currently supports the [W3C Trace Context](https://www.w3.org/TR/trace-context/) and [Jaeger](https://www.jaegertracing.io/docs/1.21/client-libraries/#propagation-format) trace context propagation formats. For details about propagation, refer to [About trace contexts](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing#about-trace-contexts). diff --git a/docs/sources/next/javascript-api/k6-experimental/tracing/instrumenthttp.md b/docs/sources/next/javascript-api/k6-experimental/tracing/instrumenthttp.md index 29677691f1..ccb981aa95 100644 --- a/docs/sources/next/javascript-api/k6-experimental/tracing/instrumenthttp.md +++ b/docs/sources/next/javascript-api/k6-experimental/tracing/instrumenthttp.md @@ -6,6 +6,8 @@ weight: 01 # instrumentHTTP +{{< docs/shared source="k6" lookup="experimental-tracing-module.md" version="" >}} + The `instrumentHTTP` function instruments the k6 http module with tracing capabilities. It transparently replaces each of the k6 http module functions with versions that automatically attach a trace context to every request. Instrumented functions include [del](https://grafana.com/docs/k6//javascript-api/k6-http/del),[get](https://grafana.com/docs/k6//javascript-api/k6-http/get),[head](https://grafana.com/docs/k6//javascript-api/k6-http/head),[options](https://grafana.com/docs/k6//javascript-api/k6-http/options),[patch](https://grafana.com/docs/k6//javascript-api/k6-http/patch),[post](https://grafana.com/docs/k6//javascript-api/k6-http/post),[put](https://grafana.com/docs/k6//javascript-api/k6-http/head), and [request](https://grafana.com/docs/k6//javascript-api/k6-http/request). The `instrumentHTTP` automatically adds tracing information to HTTP requests performed using the `k6/http` module functions (mentioned above). diff --git a/docs/sources/next/javascript-api/k6-experimental/tracing/options.md b/docs/sources/next/javascript-api/k6-experimental/tracing/options.md index 496dda37f4..d65257ba26 100644 --- a/docs/sources/next/javascript-api/k6-experimental/tracing/options.md +++ b/docs/sources/next/javascript-api/k6-experimental/tracing/options.md @@ -6,6 +6,8 @@ weight: 03 # Options +{{< docs/shared source="k6" lookup="experimental-tracing-module.md" version="" >}} + Use the `Options` object to configure the tracing instrumentation behavior. It is used during the instantiation of a [`Client`](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/client) instance and also as a parameter to the [`instrumentHTTP`](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/instrumenthttp) function. It controls the general behavior of the tracing instrumentation and is unspecific to any particular tracing client instance. ## Options diff --git a/docs/sources/next/shared/experimental-tracing-module.md b/docs/sources/next/shared/experimental-tracing-module.md new file mode 100644 index 0000000000..0dc94267bc --- /dev/null +++ b/docs/sources/next/shared/experimental-tracing-module.md @@ -0,0 +1,10 @@ +--- +title: Experimental tracing module admonition +--- + +{{% admonition type="caution" %}} + +The experimental module `k6/experimental/tracing` is deprecated, it functionality is fully available as a jslib. Please refer to its [documentation](https://grafana.com/docs/k6//javascript-api/jslib/http-instrumentation-tempo/. The `k6/experimental/tracing` will be removed in the future. + +{{% /admonition %}} + diff --git a/docs/sources/v0.52.x/javascript-api/jslib/http-instrumentation-tempo/_index.md b/docs/sources/v0.52.x/javascript-api/jslib/http-instrumentation-tempo/_index.md index 8ceb739564..529bc45f34 100644 --- a/docs/sources/v0.52.x/javascript-api/jslib/http-instrumentation-tempo/_index.md +++ b/docs/sources/v0.52.x/javascript-api/jslib/http-instrumentation-tempo/_index.md @@ -9,6 +9,10 @@ weight: 04 With this jslib, you can _instrument_ HTTP requests so that they emit traces as the test runs. Use it to include a tracing context in HTTP requests, which can then be used by a tracing backend such as [Grafana Tempo](https://grafana.com/docs/grafana-cloud/testing/k6/analyze-results/integration-with-grafana-cloud-traces/). +## Migration from `k6/experimental/tracing` + +This jslib is a drop in replacement, so all you need to migrate to it is to replace `'k6/experimental/tracing'` import with `'https://jslib.k6.io/http-instrumentation-tempo/1.0.0/index.js'` + ## About trace contexts A _trace context_ is a set of standardized HTTP headers added to a request that lets a tracing system correlate it with other requests as they navigate through a system. The trace context specifications, such as the supported [W3C Trace Context](https://www.w3.org/TR/trace-context/) and [Jaeger Trace Context](https://www.jaegertracing.io/docs/1.21/client-libraries/#propagation-format), define specific header names and an encoding format for the header values. diff --git a/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/_index.md b/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/_index.md index ea9cd4365c..bc2c83ae8c 100644 --- a/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/_index.md +++ b/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/_index.md @@ -7,7 +7,7 @@ weight: 04 # tracing -{{< docs/shared source="k6" lookup="experimental-module.md" version="" >}} +{{< docs/shared source="k6" lookup="experimental-tracing-module.md" version="" >}} With this experimental module, you can _instrument_ HTTP requests so that they emit traces as the test runs. diff --git a/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/client.md b/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/client.md index 28a8710a9d..682e1ea885 100644 --- a/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/client.md +++ b/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/client.md @@ -6,6 +6,8 @@ weight: 02 # Client +{{< docs/shared source="k6" lookup="experimental-tracing-module.md" version="" >}} + `Client` is an HTTP client constructor that attaches tracing information to its requests. Use it to include a tracing context in HTTP requests so that tracing backends (such as [Grafana Tempo](https://grafana.com/oss/tempo/)) can incorporate their results. The `Client` class acts as a drop-in replacement for the standard `http` module and attaches a [trace context](https://www.w3.org/TR/trace-context/) to the requests headers, and add a `trace_id` to HTTP-related k6 output's data points metadata. It currently supports the [W3C Trace Context](https://www.w3.org/TR/trace-context/) and [Jaeger](https://www.jaegertracing.io/docs/1.21/client-libraries/#propagation-format) trace context propagation formats. For details about propagation, refer to [About trace contexts](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing#about-trace-contexts). diff --git a/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/instrumenthttp.md b/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/instrumenthttp.md index 29677691f1..ccb981aa95 100644 --- a/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/instrumenthttp.md +++ b/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/instrumenthttp.md @@ -6,6 +6,8 @@ weight: 01 # instrumentHTTP +{{< docs/shared source="k6" lookup="experimental-tracing-module.md" version="" >}} + The `instrumentHTTP` function instruments the k6 http module with tracing capabilities. It transparently replaces each of the k6 http module functions with versions that automatically attach a trace context to every request. Instrumented functions include [del](https://grafana.com/docs/k6//javascript-api/k6-http/del),[get](https://grafana.com/docs/k6//javascript-api/k6-http/get),[head](https://grafana.com/docs/k6//javascript-api/k6-http/head),[options](https://grafana.com/docs/k6//javascript-api/k6-http/options),[patch](https://grafana.com/docs/k6//javascript-api/k6-http/patch),[post](https://grafana.com/docs/k6//javascript-api/k6-http/post),[put](https://grafana.com/docs/k6//javascript-api/k6-http/head), and [request](https://grafana.com/docs/k6//javascript-api/k6-http/request). The `instrumentHTTP` automatically adds tracing information to HTTP requests performed using the `k6/http` module functions (mentioned above). diff --git a/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/options.md b/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/options.md index 496dda37f4..d65257ba26 100644 --- a/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/options.md +++ b/docs/sources/v0.52.x/javascript-api/k6-experimental/tracing/options.md @@ -6,6 +6,8 @@ weight: 03 # Options +{{< docs/shared source="k6" lookup="experimental-tracing-module.md" version="" >}} + Use the `Options` object to configure the tracing instrumentation behavior. It is used during the instantiation of a [`Client`](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/client) instance and also as a parameter to the [`instrumentHTTP`](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/instrumenthttp) function. It controls the general behavior of the tracing instrumentation and is unspecific to any particular tracing client instance. ## Options diff --git a/docs/sources/v0.52.x/shared/experimental-tracing-module.md b/docs/sources/v0.52.x/shared/experimental-tracing-module.md new file mode 100644 index 0000000000..0dc94267bc --- /dev/null +++ b/docs/sources/v0.52.x/shared/experimental-tracing-module.md @@ -0,0 +1,10 @@ +--- +title: Experimental tracing module admonition +--- + +{{% admonition type="caution" %}} + +The experimental module `k6/experimental/tracing` is deprecated, it functionality is fully available as a jslib. Please refer to its [documentation](https://grafana.com/docs/k6//javascript-api/jslib/http-instrumentation-tempo/. The `k6/experimental/tracing` will be removed in the future. + +{{% /admonition %}} +