xk6-client-prometheus-remote
    Preparing search index...

    Class Client

    Client for sending metrics to Prometheus Remote Write endpoints.

    The Client provides multiple methods for sending metrics, optimized for different use cases:

    import remote from 'k6/x/remotewrite';

    const client = new remote.Client({
        url: "https://prometheus.example.com/api/v1/write"
    });

    export default function () {
        client.store([{
            labels: [
                { name: "__name__", value: "my_metric" },
                { name: "environment", value: "prod" }
            ],
            samples: [{ value: 42 }]
        }]);
    }

    const client = new remote.Client({
        url: "https://user:password@prometheus.example.com/api/v1/write",
        tenant_name: "team-a",
        timeout: "30s"
    });
    Index

    Constructors

    constructor

    Methods

    store storeFromPrecompiledTemplates storeFromTemplates storeGenerated

    Constructors

    • Creates a new Remote Write client.

      Parameters

      Returns Client

      import remote from 'k6/x/remotewrite';

      const client = new remote.Client({
          url: "https://prometheus.example.com/api/v1/write"
      });

    Methods

    • Stores (sends) time series data to the remote write endpoint.

      Parameters

      • timeSeries: TimeSeries[]

        Array of time series to send

      Returns RemoteWriteResponse

      Response from the remote write endpoint

      const res = client.store([{
          labels: [
              { name: "__name__", value: "my_metric" },
              { name: "service", value: "api" }
          ],
          samples: [
              { value: 42, timestamp: Date.now() }
          ]
      }]);

    • Stores metrics using precompiled templates for maximum performance.

      Use precompileLabelTemplates to compile templates once, then reuse them across multiple calls to this method. This is the most efficient approach when generating metrics repeatedly with the same template structure.

      Parameters

      • minValue: number

        Minimum random value for samples

      • maxValue: number

        Maximum random value for samples (exclusive)

      • timestamp: number

        Timestamp in milliseconds

      • seriesIdStart: number

        Start of series ID range (inclusive)

      • seriesIdEnd: number

        End of series ID range (exclusive)

      • template: PrecompiledLabelTemplates

        Precompiled label templates from precompileLabelTemplates

      Returns RemoteWriteResponse

      Response from the remote write endpoint

      const template = {
          __name__: 'k6_metric_${series_id/10}',
          series_id: '${series_id}'
      };
      const compiled = remote.precompileLabelTemplates(template);

      // Reuse compiled template in each iteration
      export default function() {
          client.storeFromPrecompiledTemplates(100, 200, Date.now(), 0, 50, compiled);
      }

    • Generates and stores time series data from a template.

      This method is more efficient than store for generating large numbers of metrics because the samples are generated inside the Go extension, avoiding the overhead of passing objects from JavaScript to Go.

      The template string values can include special variables that are substituted based on the series ID. This allows you to control label cardinality and distribution patterns.

      Parameters

      • minValue: number

        Minimum random value for samples

      • maxValue: number

        Maximum random value for samples (exclusive)

      • timestamp: number

        Timestamp in milliseconds

      • seriesIdStart: number

        Start of series ID range (inclusive)

      • seriesIdEnd: number

        End of series ID range (exclusive)

      • template: MetricTemplate

        Template for generating metric labels

      Returns RemoteWriteResponse

      Response from the remote write endpoint

      const template = {
          __name__: 'k6_generated_metric_${series_id/4}',
          series_id: '${series_id}',
          cardinality_1e1: '${series_id/10}',
          cardinality_2: '${series_id%2}',
      };

      client.storeFromTemplates(
          100,                // min random value
          200,                // max random value
          Date.now(),         // timestamp in ms
          0,                  // series id start
          100,                // series id end (exclusive) - generates IDs 0-99
          template
      );

      MetricTemplate for template variable syntax

    • Generates and stores time series data with automatic cardinality labels.

      This method automatically generates time series with cardinality labels (cardinality_1e1, cardinality_1e2, etc.) based on the total number of series. It's useful for testing scenarios where you need to distribute series across multiple batches or simulate realistic label distributions.

      Each series will have:

      • A metric name like k6_generated_metric_{series_id}
      • A series_id label with the unique series ID
      • Automatic cardinality labels based on powers of 10

      Parameters

      • totalSeries: number

        Total number of series to generate across all batches

      • batches: number

        Total number of batches

      • batchSize: number

        Number of series per batch (must divide evenly: totalSeries = batches × batchSize)

      • batch: number

        Current batch number (1-indexed)

      Returns RemoteWriteResponse

      Response from the remote write endpoint

      // Generate 1000 total series, split into 10 batches of 100 each
      export default function() {
          const batchNumber = (__ITER % 10) + 1;  // Cycles through batches 1-10
          client.storeGenerated(
              1000,  // total series
              10,    // number of batches
              100,   // series per batch
              batchNumber
          );
      }

    Settings

    On This Page

    Constructors
    Methods