k6registry

README

k6registry

Data model for the k6 extension registry

This repository contains the JSON schema of the k6 extension registry and the golang data model generated from it.

Concept

The k6 extension registry is a JSON file that contains the most important properties of extensions.

Registered Properties

Only those properties of the extensions are registered, which either cannot be detected automatically, or delegation to the extension is not allowed.

Properties that are available using the repository manager API are intentionally not registered.

The string like properties that are included in the generated Grafana documentation are intentionally not accessed via the API of the repository manager. It is not allowed to inject arbitrary text into the Grafana documentation site without approval. Therefore, these properties are registered (eg description)

Extension Identification

The primary identifier of an extension is the extension's go module path.

The extension has no name property, the module path or part of it can be used as the extension name. For example, using the first two elements of the module path after the host name, the name grafana/xk6-dashboard can be formed from the module path github.com/grafana/xk6-dashboard. This is typically the repository owner name (grafana) and the repository name in the repository manager (xk6-dashboard).

The extension has no URL property, a URL can be created from the module path that refers to the extension within the repository manager.

JavaScript Modules

The JavaScript module names implemented by the extension can be specified in the imports property. An extension can register multiple JavaScript module names, so this is an array property.

Output Names

The output names implemented by the extension can be specified in the outputs property. An extension can register multiple output names, so this is an array property.

Cloud Enabled

The true value of the cloud flag indicates that the extension is also available in the Grafana k6 cloud.

Officially Supported

The true value of the official flag indicates that the extension is officially supported by Grafana.

Example

{
  "extensions": [
    {
      "module": "github.com/grafana/xk6-dashboard",
      "description": "Web-based metrics dashboard for k6",
      "outputs": ["dashboard"],
      "official": true
    },
    {
      "module": "github.com/grafana/xk6-sql",
      "description": "Load test SQL Servers",
      "imports": ["k6/x/sql"],
      "official": true
    },
    {
      "module": "github.com/grafana/xk6-distruptor",
      "description": "Inject faults to test",
      "imports": ["k6/x/distruptor"],
      "official": true
    },
    {
      "module": "github.com/szkiba/xk6-faker",
      "description": "Generate random fake data",
      "imports": ["k6/x/faker"]
    }
  ]
}

Development

The source of the schema is contained in the registry.schema.yaml file. This file must be edited if required. The go generate command generates the registry_gen.go and registry.schema.json files and updates the example code block in the README.md from the example.json file.

Documentation

Overview

Package k6registry contains the data model of the k6 extensions registry.

Index

• type Extension
• type Registry

Types

type Extension

type Extension struct {
	// Cloud-enabled extension flag.
	//
	// A value of true indicates that the extension is also available in the Grafana
	// k6 cloud.
	//
	Cloud bool `json:"cloud,omitempty" yaml:"cloud,omitempty" mapstructure:"cloud,omitempty"`

	// Brief description of the extension.
	//
	Description string `json:"description" yaml:"description" mapstructure:"description"`

	// List of JavaScript import paths registered by the extension.
	//
	// Currently, paths must start with the prefix `k6/x/`.
	// The extensions used by k6 scripts are automatically detected based on the
	// values specified here, therefore it is important that the values used here are
	// consistent with the values registered by the extension at runtime.
	//
	Imports []string `json:"imports,omitempty" yaml:"imports,omitempty" mapstructure:"imports,omitempty"`

	// The extension's go module path.
	//
	// This is the unique identifier of the extension.
	// More info about module paths: https://go.dev/ref/mod#module-path
	//
	// The extension has no name property, the module path or part of it can be used
	// as the extension name. For example, using the first two elements of the module
	// path after the host name, the name `grafana/xk6-dashboard` can be formed from
	// the module path `github.com/grafana/xk6-dashboard`. This is typically the
	// repository owner name and the repository name in the repository manager.
	//
	// The extension has no URL property, a URL can be created from the module path
	// that refers to the extension within the repository manager.
	//
	Module string `json:"module" yaml:"module" mapstructure:"module"`

	// Officially supported extension flag.
	//
	// A value of true indicates that the extension is officially supported by
	// Grafana. Extensions owned by the `grafana` GitHub organization are not
	// officially supported by Grafana by default.
	//
	Official bool `json:"official,omitempty" yaml:"official,omitempty" mapstructure:"official,omitempty"`

	// List of output names registered by the extension.
	//
	// The extensions used by k6 scripts are automatically detected based on the
	// values specified here, therefore it is important that the values used here are
	// consistent with the values registered by the extension at runtime.
	//
	Outputs []string `json:"outputs,omitempty" yaml:"outputs,omitempty" mapstructure:"outputs,omitempty"`
}

Properties of the registered k6 extension.

Only those properties of the extensions are registered, which either cannot be detected automatically, or delegation to the extension is not allowed.

Properties that are available using the repository manager API are intentionally not registered.

The string like properties that are included in the generated Grafana documentation are intentionally not accessed via the API of the repository manager. It is not allowed to inject arbitrary text into the Grafana documentation site without approval. Therefore, these properties are registered (eg `description`)

type Registry

type Registry struct {
	// An array containing the registration data of the k6 golang extensions.
	//
	Extensions []Extension `json:"extensions,omitempty" yaml:"extensions,omitempty" mapstructure:"extensions,omitempty"`
}

k6 Extension Registry.

The k6 extension registry contains the most important properties of registered extensions.