From dde5a2a4718a640f79c81b0baf85d13411b1e1d6 Mon Sep 17 00:00:00 2001 From: Mihail Stoykov Date: Wed, 6 Nov 2024 11:53:04 +0200 Subject: [PATCH 1/2] Remove the deprecated `k6/experimental/tracing` Documentation changes around https://github.com/grafana/k6/pull/3855 --- .../k6-experimental/tracing/_index.md | 63 -------------- .../k6-experimental/tracing/client.md | 87 ------------------- .../k6-experimental/tracing/instrumenthttp.md | 57 ------------ .../k6-experimental/tracing/options.md | 17 ---- .../shared/experimental-tracing-module.md | 9 -- .../shared/javascript-api/k6-experimental.md | 1 - .../automated-performance-testing.md | 2 +- 7 files changed, 1 insertion(+), 235 deletions(-) delete mode 100644 docs/sources/k6/next/javascript-api/k6-experimental/tracing/_index.md delete mode 100644 docs/sources/k6/next/javascript-api/k6-experimental/tracing/client.md delete mode 100644 docs/sources/k6/next/javascript-api/k6-experimental/tracing/instrumenthttp.md delete mode 100644 docs/sources/k6/next/javascript-api/k6-experimental/tracing/options.md delete mode 100644 docs/sources/k6/next/shared/experimental-tracing-module.md diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/tracing/_index.md b/docs/sources/k6/next/javascript-api/k6-experimental/tracing/_index.md deleted file mode 100644 index 1580f9ad23..0000000000 --- a/docs/sources/k6/next/javascript-api/k6-experimental/tracing/_index.md +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: 'tracing' -description: 'k6 Tracing experimental API' -weight: 04 ---- - -# tracing - -{{< 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. - -## About trace contexts - -A _trace context_ is a set of standardized HTTP headers added to a request that lets a tracing system correlate the request 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. - -A trace context generally consists of, at least, a `trace_id`, a `span_id`, and a `sampled` flag. The `trace_id` is a unique identifier for the trace, the `span_id` is a unique identifier for the request, and the `sampled` flag is a boolean that indicates whether the request should be traced. For instance, the [W3C Trace Context](https://www.w3.org/TR/trace-context/) defines the `Traceparent` header, whose value contains a `trace_id`, a `span_id` and a `sampled` flag, encoded as a dash (`-`) separated list of hexadecimal values. When a trace context header is attached to an HTTP request, we refer to it as being _propagated_ to the downstream service. - -## API - -| Class/Function | Description | -| :--------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------ | -| [instrumentHTTP](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/instrumenthttp) | instruments the k6 http module with tracing capabilities. | -| [Client](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/client) | configurable Client that exposes instrumented HTTP operations and allows selectively instrumenting requests with tracing. | - -## Example - -This example demonstrates how to use the tracing API to instrument every HTTP request made in a script with tracing information. - -{{< code >}} - -```javascript -import { check } from 'k6'; -import tracing from 'k6/experimental/tracing'; -import http from 'k6/http'; - -// instrumentHTTP will ensure that all requests made by the http module -// from this point forward will have a trace context attached. -// -// The first argument is a configuration object that -// can be used to configure the tracer. -tracing.instrumentHTTP({ - // possible values: "w3c", "jaeger" - propagator: 'w3c', -}); - -export default () => { - // the instrumentHTTP call in the init context replaced - // the http module with a version that will automatically - // attach a trace context to every request. - // - // Because the instrumentHTTP call was configured with the - // w3c trace propagator, this request will as a result have - // a `traceparent` header attached. - const res = http.get('http://httpbin.org/get', { - headers: { - 'X-Example-Header': 'instrumented/get', - }, - }); -}; -``` - -{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/tracing/client.md b/docs/sources/k6/next/javascript-api/k6-experimental/tracing/client.md deleted file mode 100644 index 682e1ea885..0000000000 --- a/docs/sources/k6/next/javascript-api/k6-experimental/tracing/client.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -title: 'Client' -description: 'Client is a HTTP client attaching tracing information to its requests.' -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). - -The `Client` constructor accepts an [`Options`](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/options) object as its only parameter. - -## Example - -This example demonstrates how to instantiate a tracing client and use it to instrument HTTP calls with trace context headers. It also illustrates how you can use it alongside the standard `http` module to perform non-instrumented HTTP calls. - -{{< code >}} - -```javascript -import { check } from 'k6'; -import tracing from 'k6/experimental/tracing'; -import http from 'k6/http'; - -// Explicitly instantiating a tracing client allows to distringuish -// instrumented from non-instrumented HTTP calls, by keeping APIs separate. -// It also allows for finer-grained configuration control, by letting -// users changing the tracing configuration on the fly during their -// script's execution. -const instrumentedHTTP = new tracing.Client({ - propagator: 'w3c', -}); - -const testData = { name: 'Bert' }; - -export default () => { - // Using the tracing client instance, HTTP calls will have - // their trace context headers set. - let res = instrumentedHTTP.request('GET', 'http://httpbin.org/get', null, { - headers: { - 'X-Example-Header': 'instrumented/request', - }, - }); - - // The tracing client offers more flexibility over - // the `instrumentHTTP` function, as it leaves the - // imported standard http module untouched. Thus, - // one can still perform non-instrumented HTTP calls - // using it. - res = http.post('http://httpbin.org/post', JSON.stringify(testData), { - headers: { 'X-Example-Header': 'noninstrumented/post' }, - }); - - res = instrumentedHTTP.del('http://httpbin.org/delete', null, { - headers: { 'X-Example-Header': 'instrumented/delete' }, - }); -}; -``` - -{{< /code >}} - -## HTTP module functions equivalents - -The `Client` class exposes the same API as the standard `http` module. Except for the `batch` method, which is absent from `Client`. The following table lists the `Client` methods which have an equivalent in the standard `http` module: - -| Method | HTTP equivalent | Description | -| :--------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Client.del(url, [body], [params])` | [http.del](https://grafana.com/docs/k6//javascript-api/k6-http/del) | Performs an instrumented HTTP DELETE request. The method has the same prototype as the `http.del` function and should transparently act as a drop-in replacement for it. | -| `Client.get(url, [params])` | [http.get](https://grafana.com/docs/k6//javascript-api/k6-http/get) | Performs an instrumented HTTP GET request. The method has the same prototype as the `http.get` function and should transparently act as a drop-in replacement for it. | -| `Client.head(url, [params])` | [http.head](https://grafana.com/docs/k6//javascript-api/k6-http/head) | Performs an instrumented HTTP HEAD request. The method has the same prototype as the `http.head` function and should transparently act as a drop-in replacement for it. | -| `Client.options(url, [body], [params])` | [http.options](https://grafana.com/docs/k6//javascript-api/k6-http/options) | Performs an instrumented HTTP OPTIONS request. The method has the same prototype as the `http.options` function and should transparently act as a drop-in replacement for it. | -| `Client.patch(url, [body], [params])` | [http.patch](https://grafana.com/docs/k6//javascript-api/k6-http/patch) | Performs an instrumented HTTP PATCH request. The method has the same prototype as the `http.patch` function and should transparently act as a drop-in replacement for it. | -| `Client.post(url, [body], [params])` | [http.post](https://grafana.com/docs/k6//javascript-api/k6-http/post) | Performs an instrumented HTTP POST request. The method has the same prototype as the `http.post` function and should transparently act as a drop-in replacement for it. | -| `Client.put(url, [body], [params])` | [http.put](https://grafana.com/docs/k6//javascript-api/k6-http/head) | Performs an instrumented HTTP HEAD request. The method has the same prototype as the `http.put` function and should transparently act as a drop-in replacement for it. | -| `Client.request(method, url, [body], [params])` | [http.request](https://grafana.com/docs/k6//javascript-api/k6-http/request) | Performs an instrumented HTTP request. The method has the same prototype as the `http.request` function and should transparently act as a drop-in replacement for it. | -| `Client.asyncRequest(method, url, [body], [params])` | [http.asyncRequest](https://grafana.com/docs/k6//javascript-api/k6-http/asyncrequest) | Performs an instrumented HTTP asynchronous request. The method has the same prototype as the `http.asyncRequest` function and should transparently act as a drop-in replacement for it. | - -## Configuration - -`Client` instances support being reconfigured using the following API: - -| Method | Description | -| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `Client.configure(options)` | Reconfigures the tracing client instance with the provided [`Options`](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/options) | diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/tracing/instrumenthttp.md b/docs/sources/k6/next/javascript-api/k6-experimental/tracing/instrumenthttp.md deleted file mode 100644 index ccb981aa95..0000000000 --- a/docs/sources/k6/next/javascript-api/k6-experimental/tracing/instrumenthttp.md +++ /dev/null @@ -1,57 +0,0 @@ ---- -title: 'instrumentHTTP' -description: 'instrumentHTTP instruments the k6 http module with tracing capabilities.' -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). -This means that, to instrument the HTTP requests, you don't need to rewrite any code. -Instead, call it once in the init context. -From that point forward, all requests made by the HTTP module from that point forward will have a trace context header added to them, and the metadata for the data-point output will have the used `trace_id`. For details about propagation, refer to [About trace contexts](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing#about-trace-contexts). - -## Parameters - -| Name | Type | Description | -| :-------- | :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `options` | [`Options`](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/options) | Configures the tracing behavior with the provided [`Options`](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing/options) object. | - -## Example - -This example demonstrates how calling the `instrumentHTTP` function in the init context of a script once ensures that all requests made by the HTTP module from that point forward will have a trace context header attached. - -{{< code >}} - -```javascript -import { check } from 'k6'; -import tracing from 'k6/experimental/tracing'; -import http from 'k6/http'; - -// instrumentHTTP will ensure that all requests made by the http module -// will be traced. The first argument is a configuration object that -// can be used to configure the tracer. -// -// Currently supported HTTP methods are: get, post, put, patch, head, -// del, options, and request. -tracing.instrumentHTTP({ - // propagator defines the trace context propagation format. - // Currently supported: w3c and jaeger. - // Default: w3c - propagator: 'w3c', -}); - -export default () => { - const res = http.get('http://httpbin.org/get', { - headers: { - 'X-Example-Header': 'instrumented/get', - }, - }); -}; -``` - -{{< /code >}} diff --git a/docs/sources/k6/next/javascript-api/k6-experimental/tracing/options.md b/docs/sources/k6/next/javascript-api/k6-experimental/tracing/options.md deleted file mode 100644 index d65257ba26..0000000000 --- a/docs/sources/k6/next/javascript-api/k6-experimental/tracing/options.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -title: 'Options' -description: 'Options allows to configure the tracing instrumentation behavior.' -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 - -| Option name | Type | Default | Description | -| :----------- | :------- | :------ | :----------------------------------------------------------------------------- | -| `propagator` | `string` | `w3c` | The trace context propagation format. Currently supported: `w3c` and `jaeger`. | diff --git a/docs/sources/k6/next/shared/experimental-tracing-module.md b/docs/sources/k6/next/shared/experimental-tracing-module.md deleted file mode 100644 index 5cdc995558..0000000000 --- a/docs/sources/k6/next/shared/experimental-tracing-module.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -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/k6/next/shared/javascript-api/k6-experimental.md b/docs/sources/k6/next/shared/javascript-api/k6-experimental.md index ff20550588..cdd6ee25d8 100644 --- a/docs/sources/k6/next/shared/javascript-api/k6-experimental.md +++ b/docs/sources/k6/next/shared/javascript-api/k6-experimental.md @@ -8,6 +8,5 @@ title: javascript-api/k6-experimental | [fs](https://grafana.com/docs/k6//javascript-api/k6-experimental/fs) | Provides a memory-efficient way to handle file interactions within your test scripts. | | [redis](https://grafana.com/docs/k6//javascript-api/k6-experimental/redis) | Functionality to interact with [Redis](https://redis.io/). | | [streams](https://grafana.com/docs/k6//javascript-api/k6-experimental/streams) | Provides an implementation of the Streams API specification, offering support for defining and consuming readable streams. | -| [tracing](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing) | Support for instrumenting HTTP requests with tracing information. | | [webcrypto](https://grafana.com/docs/k6//javascript-api/k6-experimental/webcrypto) | Implements the [WebCrypto API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Crypto_API). | | [websockets](https://grafana.com/docs/k6//javascript-api/k6-experimental/websockets) | Implements the browser's [WebSocket API](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket). | diff --git a/docs/sources/k6/next/testing-guides/automated-performance-testing.md b/docs/sources/k6/next/testing-guides/automated-performance-testing.md index b409d21dd4..8647bd06d8 100644 --- a/docs/sources/k6/next/testing-guides/automated-performance-testing.md +++ b/docs/sources/k6/next/testing-guides/automated-performance-testing.md @@ -255,7 +255,7 @@ Last but not least, set up proper instrumentation of the SUT and understand the Performance testing results can highlight poor performance, such as slow responses. However, it does not show what happens internally on the SUT, such as a slow SQL query or CPU and memory saturation. -To bridge the gap, work out a way to correlate testing results with how you instrument your infrastructure and application code. For instance, connecting or building custom dashboards with test results or using [trace data from your tests](https://grafana.com/docs/k6//javascript-api/k6-experimental/tracing). +To bridge the gap, work out a way to correlate testing results with how you instrument your infrastructure and application code. For instance, connecting or building custom dashboards with test results or using [trace data from your tests](https://grafana.com/docs/k6//javascript-api/jslib/http-instrumentation-tempo/). Continuous testing helps detect issues and performance degradations, whether from test results or system data. Proper observability will help to find the root cause. From acc25d772466012ca56ec5633687307c5d754b7a Mon Sep 17 00:00:00 2001 From: Heitor Tashiro Sergent Date: Fri, 8 Nov 2024 13:49:06 -0600 Subject: [PATCH 2/2] Add aliases to http-instrumentation-tempo pages --- .../jslib/http-instrumentation-tempo/_index.md | 2 ++ .../jslib/http-instrumentation-tempo/client.md | 6 ++++-- .../jslib/http-instrumentation-tempo/instrumenthttp.md | 6 ++++-- .../jslib/http-instrumentation-tempo/options.md | 10 ++++++---- 4 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/_index.md b/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/_index.md index fb8a6eb805..456061b8d7 100644 --- a/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/_index.md +++ b/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/_index.md @@ -1,4 +1,6 @@ --- +aliases: + - ../k6-experimental/tracing/ # docs/k6//javascript-api/k6-experimental/tracing/ title: 'HTTP instrumentation for Tempo' menuTitle: http-instrumentation-tempo description: 'k6 Tempo instrumentation API' diff --git a/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/client.md b/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/client.md index 3d644cca24..abd89005ab 100644 --- a/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/client.md +++ b/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/client.md @@ -1,4 +1,6 @@ --- +aliases: + - ../../k6-experimental/tracing/client/ # docs/k6//javascript-api/k6-experimental/tracing/client/ title: 'Client' description: 'Client is a HTTP client attaching tracing information to its requests.' weight: 02 @@ -82,6 +84,6 @@ The following table lists the `Client` methods which have an equivalent in the s `Client` instances support being reconfigured using the following API: -| Method | Description | -| :-------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Method | Description | +| :-------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Client.configure(options)` | Reconfigures the tracing client instance with the provided [`Options`](https://grafana.com/docs/k6//javascript-api/jslib/http-instrumentation-tempo/options) | diff --git a/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/instrumenthttp.md b/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/instrumenthttp.md index 475e090107..3622e47b44 100644 --- a/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/instrumenthttp.md +++ b/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/instrumenthttp.md @@ -1,4 +1,6 @@ --- +aliases: + - ../../k6-experimental/tracing/instrumenthttp/ # docs/k6//javascript-api/k6-experimental/tracing/instrumenthttp/ title: 'instrumentHTTP' description: 'instrumentHTTP instruments the k6 http module with tracing capabilities.' weight: 01 @@ -15,8 +17,8 @@ From that point forward, all requests made by the HTTP module from that point fo ## Parameters -| Name | Type | Description | -| :-------- | :--------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Name | Type | Description | +| :-------- | :------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `options` | [`Options`](https://grafana.com/docs/k6//javascript-api/jslib/http-instrumentation-tempo/options) | Configures the tracing behavior with the provided [`Options`](https://grafana.com/docs/k6//javascript-api/jslib/http-instrumentation-tempo/options) object. | ## Example diff --git a/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/options.md b/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/options.md index f3ec11513a..2f08f625dc 100644 --- a/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/options.md +++ b/docs/sources/k6/next/javascript-api/jslib/http-instrumentation-tempo/options.md @@ -1,4 +1,6 @@ --- +aliases: + - ../../k6-experimental/tracing/options/ # docs/k6//javascript-api/k6-experimental/tracing/options/ title: 'Options' description: 'Options allows to configure the tracing instrumentation behavior.' weight: 03 @@ -10,7 +12,7 @@ Use the `Options` object to configure the tracing instrumentation behavior. It i ## Options -| Option name | Type | Default | Description | -| :----------- | :------- | :------ | :----------------------------------------------------------------------------- | -| `propagator` | `string` | `w3c` | The trace context propagation format. Currently supported: `w3c` and `jaeger`. | -| `sampling` | `number` | `1` | A number between 0 and 1 defining the sampling rate. 1 means sample always, 0 means never sample. | +| Option name | Type | Default | Description | +| :----------- | :------- | :------ | :------------------------------------------------------------------------------------------------ | +| `propagator` | `string` | `w3c` | The trace context propagation format. Currently supported: `w3c` and `jaeger`. | +| `sampling` | `number` | `1` | A number between 0 and 1 defining the sampling rate. 1 means sample always, 0 means never sample. |