%% date:: [[2023-04-11]], [[2023-05-11]] parent:: %% # [[xk6-distributed-tracing]] [repo](https://github.com/grafana/xk6-distributed-tracing) xk6-distributed tracing is an [[Extensions for k6 using xk6|extension]] for [[k6 (tool)|k6]] that starts [[Distributed tracing|traces]] from a k6 test by instrumenting every HTTP request by adding a header according to the following propagation formats: - [[Jaeger]] (also used by [[Grafana Tempo|Tempo]]) - [[W3C]] - [[b3]] k6 currently comes with an [[Experimental modules in k6|experimental module]] called [[k6 tracing]], which is a more general implementation of this extension. Unlike k6 tracing, xk6-distributed-tracing also talks to the [[k6 Insights]] platform. ## How to use this xk6-distributed tracing and [[k6 Insights]] in general is in a private beta. While the extension is [[Open-source|opensource]] and anyone can use it, people need to be given permissions to use the k6 insights platform. ### Prerequisites - A [[Grafana Cloud]] account - A [[k6 Cloud]] account (for now, although this is a legacy platform) - Membership to an organization that has been given access to [[k6 Insights]]. - Access to the organization-level API token (available for admins and owners). ### Get your organization details #### API token Get the [organization-level API token](https://k6.io/docs/cloud/integrations/token/#organization-api-token) from k6 Cloud. Note that this is not the same as a personal API token. The organization-level API token is one that is not tied to a specific person's account, which makes it better to use for [[Continuous Improvement|CI/CD]] pipelines. #### Organization ID You'll also need your organization ID. Go to k6 Cloud, click on the dropdown menu on the upper left, and select your organization. Then, click on the dropdown menu again and click Settings. Your organization ID is shown. ### Step 1. Build the custom k6 binary Since xk6-distributed-tracing is a [[Extensions for k6 using xk6|k6 extension]], you need to create a custom k6 binary that includes it. Follow [the instructions on the repo](https://github.com/grafana/xk6-distributed-tracing) or run this: Download the latest version of xk6: ``` go install go.k6.io/xk6/cmd/xk6@latest ``` and then build a binary that includes the extension: ``` xk6 build --with github.com/grafana/xk6-distributed-tracing@latest ``` ### Step 2. Write the script Now, write your k6 script. You need to add two things to the script to make it propagate traces. The first is an import statement: ```javascript import tracing from "k6/x/tracing"; ``` and the second is a definition of the `http` object (note that you shouldn't import this from the `k6/http` library like you normally would for a k6 script): ```javascript const http = new tracing.Http( { propagator: "jaeger" } ); ``` > [!tip]- Full example > [Here's](https://github.com/nicolevanderhoeven/k6-scripts/blob/main/hotrod/hotrod-tracing.js) an example of a full script implementing this: > ```javascript > import http from "k6/http"; > import { sleep, check } from "k6"; > import { randomIntBetween } from "https://jslib.k6.io/k6-utils/1.1.0/index.js"; > import Papa from 'https://jslib.k6.io/papaparse/5.1.1/index.js'; > > const domain = "https://hotrod-sedemo.test.k6.io/"; > const csvData = Papa.parse(open('customers.csv'), { header: false }).data; > > export const options = { > scenarios: { > home: { > executor: 'ramping-vus', > exec: 'homepage', > startVUs: 0, > stages: [ > { duration: "30s", target: 20 }, > { duration: "10m", target: 20 }, > { duration: "30s", target: 0} > ], > }, > dispatch: { > executor: 'ramping-vus', > exec: 'dispatch', > startVUs: 0, > stages: [ > { duration: "30s", target: 10 }, > { duration: "10m", target: 10 }, > { duration: "30s", target: 0} > ] > } > }, > thresholds: { > http_req_duration: ['p(95) < 500'], // Response times average below 1s > http_req_failed: ['rate < 0.01'], // Error rate below 1% > }, > ext : { > loadimpact: { > projectID: 3640420, > name: "Hotrod Dispatch", > distribution: { > 'amazon:us:ashburn': { loadZone: 'amazon:us:ashburn', percent: 50 }, > 'amazon:us:columbus': { loadZone: 'amazon:us:columbus', percent: 50 }, > }, > }, > }, > } > export default function () { > homepage(); > dispatch(); > } > > export function homepage() { > let res = http.get(domain); > check(res, { > "status was 200": (r) => r.status == 200, > "Homepage accessed": (r) => r.body.includes("HotROD - Rides On Demand"), > }) > > sleep(randomIntBetween(3, 5)); > } > > export function dispatch() { > let rand = Math.floor(Math.random() * csvData.length); > let customer = csvData[rand]; > let res = http.get(domain + 'dispatch?customer=' + customer) > check(res, { > "status was 200": (r) => r.status == 200, > "Car dispatched": (r) => r.body.includes("ETA"), > }) > > sleep(randomIntBetween(3, 5)); > } > ``` ### Step 3. Run the script Run the script using the custom binary you created. You need to also output your metrics simultaneously to the cloud and to the [[k6 Insights]] platform. You can do all of this with one command: ``` XK6_CROCOSPANS_ORG_ID=1234567 XK6_CROCOSPANS_TOKEN=YOUR_GENERATED_TOKEN ./k6 run --out xk6-crocospans=https://insights.k6.io/crocospans/api/v1/push/request --out cloud script.js ``` Replace the values for `XK6_CROCOSPANS_ORG_ID` and `XK6_CROCOSPANS_TOKEN` with the values you got in [[xk6-distributed-tracing#Step 1. Build the custom k6 binary|Step 1]]. You can see the output of your test run in the terminal. Look for something like this: ``` /\ |‾‾| /‾‾/ /‾‾/ /\ / \ | |/ / / / / \/ \ | ( / ‾‾\ / \ | |\ \ | (‾) | / __________ \ |__| \__\ \_____/ .io execution: local script: hotrod-tracing.js output: xk6-crocospans (TestRunID: 12345678), cloud (https://app.k6.io/runs/12345678) scenarios: (100.00%) 2 scenarios, 30 max VUs, 11m30s max duration (incl. graceful stop): * dispatch: Up to 10 looping VUs for 11m0s over 3 stages (gracefulRampDown: 30s, exec: dispatch, gracefulStop: 30s) * home: Up to 20 looping VUs for 11m0s over 3 stages (gracefulRampDown: 30s, exec: homepage, gracefulStop: 30s) INFO[0004] trace_id=dc07189eb0a1dd8031a2b276ea31c83f source=console INFO[0006] trace_id=dc0718fabba1dd8031edf16ad87af8ae source=console INFO[0007] trace_id=dc0718fabba1dd8031517229e8611dfd source=console ``` Look for the part that identifies the `TestRunID`. Copy this number. ### Step 4. Visualize the trace information Go to your tracing dashboard in Grafana Cloud. This should have been provided by Grafana upon signing up to the private beta. %% The HotRod app in the script above can be monitored [using this dashboard](https://sedemo.grafana.net/d/J7Ps8fn4z/k6-insights-summary-dashboard?orgId=1&var-k6_insights_data_source=k6-insights-prom&var-test_run_id=72817&var-scenario=dispatch&var-group=&var-http_url=https:%2F%2Fhotrod-sedemo.test.k6.io%2Fdispatch%3Fcustomer%3D123&var-http_method=GET&var-http_status=200&from=now-30m&to=now). %% ![[k6-insights-summary-dashboard.png]] In the dashboard, enter the corect `test_run_id` that you just copied into that field, and the dashboard will populate with the correct values. ![[k6-insights-summary-dashboard-with-values.png]]