Documentation for developing output plugins

Hi,

I want to develop an output plugin (like 1 of here https://k6.io/docs/results-visualization), but couldn’t find a decent documentation.

Can you help me to locate a boilerplate example or documentation that explains/guidelines/walkthrough how to develop an output plugin, please?

Bests,
Engin.

1 Like

We don’t have such documentation yet, sorry. You can take a look at the code of one of the existing outputs (called collectors internally in k6) here: https://github.com/loadimpact/k6/tree/master/stats, for example https://github.com/loadimpact/k6/blob/master/stats/json/collector.go

Keep in mind that there are plenty of things we want to refactor in the current output API and its configuration (https://github.com/loadimpact/k6/issues/1075, https://github.com/loadimpact/k6/issues/917), so there would be some rough edges. And we don’t have a plugin system just yet (it’s WIP - https://github.com/loadimpact/k6/issues/1353#issuecomment-676524828), so you’d have to either wait for that or fork k6 and add it to the core (which I can’t promise we’ll merge). Out of curiosity, what sort of output do you want to add?

Hi @ned,

Thanks for the response.

I’m a Senior Software Engineer with Microsoft and currently adding Application Insights to k6 as an output option for 1 of the projects I’m working on.

I thought it’ll be great for community if I can add it to k6 repo.

Honestly, lacking of a good documentation for developing an output plugin is kind of a bummer.

But at least I have a working solution to push results to Application Insights now, I’m just not sure if I’m doing it in a correct way.

Also, I’m a bit confused about the percentiles in the result, I couldn’t get them in Collect() method with []stats.SampleContainer argument, and couldn’t understand from the source code in the stats folder.

How can I get them?

A little help on here would be great!

Bests,
Engin.

The k6 outputs/collectors deal only with the raw metric measurement values, e.g. how many milliseconds each HTTP request took, etc. The outputs are supposed to calculate the percentiles themselves, based on these raw values.

The percentiles you see in the summary report k6 produces at the end of the test run are calculated by k6 and are not exposed to the outputs. You can think of the end-of-test summary as sort of a special-case output/collector that crunches the metrics in-memory while the test is running. It’s not quite an output, given that the same percentile calculations are also used for the thresholds, but it’s similar. This is the code that calculates percentiles for Trend metrics.

1 Like

Hey @ned,

That means, I understand the output plugins wrong! I thought they just receive metrics at the end of the test run.

If I understand you correctly, they actually receive metrics during the run, right?

So, then, what is the interval output plugins receive metrics? Once per second? Once per iteration? Once per hitting a REST endpoint? or something else?

Btw, I couldn’t find a timeline for the new plugin system. Do you have a date (at least an estimation) for it?

And how much re-work do you expect for the current plugins to adjust with the new plugin system?

Yes.

The k6 engine sends a chunk of metrics to every output every 50 milliseconds. It’s then up to each output to potentially buffer metrics into larger chunks, for example the JSON output flushes them every 200ms, while the InfluxDB output has the period configurable.

We will likely start working on it next week and we should have some rough first version roughly in time for k6 v0.29.0, so mid-November. But I think you’re also misunderstanding what the first version of the plugin system is going to do - it’s not going to allow you to write output plugins, just JS plugins. So, essentially, it would allow you to import more native code in your scripts (e.g. import whatever from "k6/x/whatever"). Support for output plugins would follow in a future version, after we refactor some things and fix the issues with the collector/output APIs I linked to above. I can’t give you a time estimate regarding that, but it’s very unlikely to happen this year, so for now your custom output would have to live in a fork of k6. You can submit a PR for us to merge it, but I can’t give any promises about that either, I pretty much don’t know anything about Application Insights.

1 Like

Thanks for the reply @ned :slight_smile: I’ll continue to work on the plugin and create a PR anyway.

I hope it’ll be merged, also, when the new plugin system published, I’ll update the plugin according to the new system.

hey @ned, hope this message finds you well.

I see Plugin support issue is closed, so I was expecting to see the “new” plugin system (which is described here caddyserver.com/docs/extending-caddy ; if I understand it correctly) in the output plugins under the stats folder

But I see output plugins are still in the “old” system, for example; stats/csv/collector.go

Can you clarify it a bit, is it safe to use the new plugin system or do you recommend to wait for more to see it’s implemented in the current output plugins?

Not quite. The link you posted is describing the caddy plugin/extension system. We have modeled the k6 extensions after the caddy extensions, but there are some differences. We had some information about the k6 extensions in our latest release notes and we’re currently working on better documentation and a tutorial on the topic, but for now you can take a look at https://github.com/k6io/xk6

The k6 outputs are not really plugins, they are built-in modules of k6. The new xk6 extension system still doesn’t have a way to allow you to write output extensions, you can only write extensions you can import from your JS scripts. We still have some refactoring to do, before we support output extensions. Track https://github.com/loadimpact/k6/issues/1075 and https://github.com/loadimpact/k6/issues/917 (see the latest comment I made today) for updates.