HTTP instrumentation for Tempo on Grafana Labs

instrumentHTTP

Mon, 21 Sep 2026 15:16:28 +0000

instrumentHTTP

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, get, head, options, patch, post, put, and 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 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.

Parameters

Name	Type	Description
`options`	`Options`	Configures the tracing behavior with the provided `Options` object.

Example

This example demonstrates how to call the instrumentHTTP function in the script’s init context. From that point forward, all the requests made by the HTTP module have a trace context header attached.

import { check } from 'k6';
import tempo from 'https://jslib.k6.io/http-instrumentation-tempo/1.0.1/index.js';
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.
tempo.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',
    },
  });
};

Client

Mon, 21 Sep 2026 15:16:28 +0000

Client

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) can incorporate their results.

The Client class acts as a drop-in replacement for the standard http module and attaches a 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 and Jaeger trace context propagation formats. For details about propagation, refer to About trace contexts.

The Client constructor accepts an 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.

import { check } from 'k6';
import tempo from 'https://jslib.k6.io/http-instrumentation-tempo/1.0.1/index.js';
import http from 'k6/http';

// Explicitly instantiating a tempo client allows to distinguish
// 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 tempo.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' },
  });
};

HTTP module functions equivalents

The Client class exposes the same API as the standard http module, except for the batch method.

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	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	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	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	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	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	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	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	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	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`

Options

Mon, 21 Sep 2026 15:16:28 +0000

Options

Use the Options object to configure the tracing instrumentation behavior. It is used during the instantiation of a Client instance and also as a parameter to the 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`.
`sampling`	`number`	`1`	A number between 0 and 1 defining the sampling rate. 1 means sample always, 0 means never sample.