KinesisClient on Grafana Labs

createStream

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

createStream

KinesisClient.createStream(streamName, [options]) creates a new Kinesis stream.

Parameters

Parameter	Type	Description
streamName	string	The name of the Kinesis stream to create.
options	object	Optional configuration for the stream creation.

Options

Parameter	Type	Description
shardCount	number	The number of shards for the stream (for provisioned mode).
streamModeDetails	object	Configuration for the stream mode.
streamModeDetails.streamMode	string	The billing mode for the stream. Either `PROVISIONED` or `ON_DEMAND`.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the stream creation request is complete.

Example

import {
  AWSConfig,
  KinesisClient,
} from 'https://jslib.k6.io/aws/0.14.0/kinesis.js';

const awsConfig = new AWSConfig({
  region: __ENV.AWS_REGION,
  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
});

const kinesis = new KinesisClient(awsConfig);

export default async function () {
  // Create a stream with provisioned billing and 2 shards
  await kinesis.createStream('my-provisioned-stream', {
    shardCount: 2,
  });

  // Create a stream with on-demand billing
  await kinesis.createStream('my-on-demand-stream', {
    streamModeDetails: {
      streamMode: 'ON_DEMAND',
    },
  });
}

deleteStream

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

deleteStream

KinesisClient.deleteStream(streamName) deletes a Kinesis stream.

Parameters

Parameter	Type	Description
streamName	string	The name of the Kinesis stream to delete.

Returns

Type	Description
`Promise<void>`	A Promise that fulfills when the stream deletion request is complete.

Example

import {
  AWSConfig,
  KinesisClient,
} from 'https://jslib.k6.io/aws/0.14.0/kinesis.js';

const awsConfig = new AWSConfig({
  region: __ENV.AWS_REGION,
  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
});

const kinesis = new KinesisClient(awsConfig);

export default async function () {
  const streamName = 'my-test-stream';

  // Delete the stream
  await kinesis.deleteStream(streamName);
  console.log(`Stream ${streamName} deleted`);
}

getRecords

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

getRecords

KinesisClient.getRecords(shardIterator, [options]) gets records from a Kinesis stream shard using a shard iterator.

Parameters

Parameter	Type	Description
shardIterator	string	The shard iterator from which to get records.
options	object	Optional configuration for the get records operation.

Options

Parameter	Type	Description
limit	number	The maximum number of records to return.

Returns

Type	Description
`Promise<Object>`	A Promise that fulfills with the records response.

Returns object

Property	Type	Description
records	Array	An array of records retrieved from the stream.
nextShardIterator	string	The next shard iterator to use for subsequent calls.
millisBehindLatest	number	The number of milliseconds behind the latest record.

Record object

Property	Type	Description
sequenceNumber	string	The sequence number of the record.
approximateArrivalTimestamp	Date	The approximate arrival timestamp of the record.
data	string	The data payload of the record.
partitionKey	string	The partition key of the record.

Example

import {
  AWSConfig,
  KinesisClient,
} from 'https://jslib.k6.io/aws/0.14.0/kinesis.js';

const awsConfig = new AWSConfig({
  region: __ENV.AWS_REGION,
  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
});

const kinesis = new KinesisClient(awsConfig);

export default async function () {
  const streamName = 'my-test-stream';

  // First, get the shards for the stream
  const shards = await kinesis.listShards(streamName);

  if (shards.shards.length > 0) {
    const shardId = shards.shards[0].shardId;

    // Get a shard iterator for the first shard
    const shardIteratorResponse = await kinesis.getShardIterator(
      streamName,
      shardId,
      'TRIM_HORIZON'
    );

    const shardIterator = shardIteratorResponse.shardIterator;

    // Get records from the shard
    const recordsResponse = await kinesis.getRecords(shardIterator, { limit: 10 });

    console.log('Records retrieved:', recordsResponse.records.length);
    console.log('Milliseconds behind latest:', recordsResponse.millisBehindLatest);

    // Process the records
    recordsResponse.records.forEach((record, index) => {
      console.log(`Record ${index}:`);
      console.log('  Sequence number:', record.sequenceNumber);
      console.log('  Partition key:', record.partitionKey);
      console.log('  Data:', record.data);
      console.log('  Arrival timestamp:', record.approximateArrivalTimestamp);

      // Parse JSON data if applicable
      try {
        const jsonData = JSON.parse(record.data);
        console.log('  Parsed data:', jsonData);
      } catch (e) {
        console.log('  Data is not JSON');
      }
    });

    // Continue reading with the next shard iterator
    if (recordsResponse.nextShardIterator) {
      const nextBatch = await kinesis.getRecords(recordsResponse.nextShardIterator, { limit: 5 });
      console.log('Next batch size:', nextBatch.records.length);
    }
  }
}

getShardIterator

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

getShardIterator

KinesisClient.getShardIterator(streamName, shardId, shardIteratorType, [options]) gets a shard iterator for reading records from a Kinesis stream shard.

Parameters

Parameter	Type	Description
streamName	string	The name of the Kinesis stream.
shardId	string	The shard ID for which to get the iterator.
shardIteratorType	string	The type of shard iterator to get.
options	object	Optional configuration for the shard iterator.

Shard Iterator Types

Type	Description
TRIM_HORIZON	Start reading at the last untrimmed record in the shard.
LATEST	Start reading just after the most recent record in the shard.
AT_SEQUENCE_NUMBER	Start reading from the position denoted by a specific sequence number.
AFTER_SEQUENCE_NUMBER	Start reading right after the position denoted by a specific sequence number.
AT_TIMESTAMP	Start reading from the position denoted by a specific timestamp.

Options

Parameter	Type	Description
startingSequenceNumber	string	The sequence number to start from (required for `AT_SEQUENCE_NUMBER` and `AFTER_SEQUENCE_NUMBER` types).
timestamp	Date	The timestamp to start from (required for `AT_TIMESTAMP` type).

Returns

Type	Description
`Promise<Object>`	A Promise that fulfills with the shard iterator response.

Returns object

Property	Type	Description
shardIterator	string	The shard iterator to use for reading records.

Example

import {
  AWSConfig,
  KinesisClient,
} from 'https://jslib.k6.io/aws/0.14.0/kinesis.js';

const awsConfig = new AWSConfig({
  region: __ENV.AWS_REGION,
  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
});

const kinesis = new KinesisClient(awsConfig);

export default async function () {
  const streamName = 'my-test-stream';

  // First, get the shards for the stream
  const shards = await kinesis.listShards(streamName);

  if (shards.shards.length > 0) {
    const shardId = shards.shards[0].shardId;

    // Get a shard iterator starting from the beginning
    const trimHorizonIterator = await kinesis.getShardIterator(streamName, shardId, 'TRIM_HORIZON');
    console.log('Trim horizon iterator:', trimHorizonIterator.shardIterator);

    // Get a shard iterator starting from the latest records
    const latestIterator = await kinesis.getShardIterator(streamName, shardId, 'LATEST');
    console.log('Latest iterator:', latestIterator.shardIterator);

    // Get a shard iterator starting from a specific timestamp
    const timestampIterator = await kinesis.getShardIterator(streamName, shardId, 'AT_TIMESTAMP', {
      timestamp: new Date(Date.now() - 3600000), // 1 hour ago
    });
    console.log('Timestamp iterator:', timestampIterator.shardIterator);

    // Use the iterator to read records
    const records = await kinesis.getRecords(trimHorizonIterator.shardIterator);
    console.log('Records retrieved:', records.records.length);

    // If we have records, we can get an iterator starting after a specific sequence number
    if (records.records.length > 0) {
      const sequenceNumber = records.records[0].sequenceNumber;
      const afterSequenceIterator = await kinesis.getShardIterator(
        streamName,
        shardId,
        'AFTER_SEQUENCE_NUMBER',
        {
          startingSequenceNumber: sequenceNumber,
        }
      );
      console.log('After sequence iterator:', afterSequenceIterator.shardIterator);
    }
  }
}

listShards

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

listShards

KinesisClient.listShards(streamName, [options]) lists the shards in a Kinesis stream.

Parameters

Parameter	Type	Description
streamName	string	The name of the Kinesis stream.
options	object	Optional configuration for the list shards operation.

Options

Parameter	Type	Description
nextToken	string	The token to use for pagination.
exclusiveStartShardId	string	The shard ID to start listing from (exclusive).
maxResults	number	The maximum number of shards to return.

Returns

Type	Description
`Promise<Object>`	A Promise that fulfills with the list of shards.

Returns object

Property	Type	Description
shards	Array	An array of shard objects.
nextToken	string	The token to use for the next page of results.

Shard object

Property	Type	Description
shardId	string	The unique identifier of the shard.
parentShardId	string (optional)	The shard ID of the parent shard (if any).
adjacentParentShardId	string (optional)	The shard ID of the adjacent parent shard (if any).
hashKeyRange	Object	The hash key range for the shard.
sequenceNumberRange	Object	The sequence number range for the shard.

Example

import {
  AWSConfig,
  KinesisClient,
} from 'https://jslib.k6.io/aws/0.14.0/kinesis.js';

const awsConfig = new AWSConfig({
  region: __ENV.AWS_REGION,
  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
});

const kinesis = new KinesisClient(awsConfig);

export default async function () {
  const streamName = 'my-test-stream';

  // List all shards in the stream
  const shardsResponse = await kinesis.listShards(streamName);

  console.log('Number of shards:', shardsResponse.shards.length);

  // Display information about each shard
  shardsResponse.shards.forEach((shard, index) => {
    console.log(`Shard ${index}:`);
    console.log('  Shard ID:', shard.shardId);
    console.log('  Parent Shard ID:', shard.parentShardId || 'None');
    console.log('  Adjacent Parent Shard ID:', shard.adjacentParentShardId || 'None');
    console.log('  Hash Key Range:', shard.hashKeyRange);
    console.log('  Sequence Number Range:', shard.sequenceNumberRange);
  });

  // List shards with pagination
  const limitedShards = await kinesis.listShards(streamName, { maxResults: 2 });
  console.log('Limited shards:', limitedShards.shards.length);

  // Continue pagination if there are more shards
  if (limitedShards.nextToken) {
    const nextPage = await kinesis.listShards(streamName, {
      nextToken: limitedShards.nextToken,
    });
    console.log('Next page shards:', nextPage.shards.length);
  }
}

listStreams

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

listStreams

KinesisClient.listStreams([options]) lists the Kinesis streams in the current region.

Parameters

Parameter	Type	Description
options	object (optional)	Configuration for the listing operation.

Options

Parameter	Type	Description
exclusiveStartStreamName	string	The name of the stream to start listing from (exclusive).
limit	number	The maximum number of streams to return.

Returns

Type	Description
`Promise<Object>`	A Promise that fulfills with the list of streams.

Returns object

Property	Type	Description
streamNames	Array	An array of stream names.
hasMoreStreams	boolean	Indicates if there are more streams to list.

Example

import {
  AWSConfig,
  KinesisClient,
} from 'https://jslib.k6.io/aws/0.14.0/kinesis.js';

const awsConfig = new AWSConfig({
  region: __ENV.AWS_REGION,
  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
});

const kinesis = new KinesisClient(awsConfig);

export default async function () {
  // List all streams
  const streams = await kinesis.listStreams();
  console.log('Available streams:', streams.streamNames);
  console.log('Has more streams:', streams.hasMoreStreams);

  // List streams with pagination
  const limitedStreams = await kinesis.listStreams({ limit: 5 });
  console.log('First 5 streams:', limitedStreams.streamNames);

  // List streams starting from a specific stream
  if (limitedStreams.hasMoreStreams && limitedStreams.streamNames.length > 0) {
    const nextBatch = await kinesis.listStreams({
      exclusiveStartStreamName: limitedStreams.streamNames[limitedStreams.streamNames.length - 1],
    });
    console.log('Next batch of streams:', nextBatch.streamNames);
  }
}

putRecords

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

putRecords

KinesisClient.putRecords(streamName, records) puts multiple records into a Kinesis stream.

Parameters

Parameter	Type	Description
streamName	string	The name of the Kinesis stream to put records into.
records	Array	An array of records to put into the stream.

Records

Each record in the records array should be an object with the following properties:

Property	Type	Description
data	string	The data payload of the record.
partitionKey	string	The partition key for the record.
explicitHashKey	string	Optional. The explicit hash key for the record.

Returns

Type	Description
`Promise<Object>`	A Promise that fulfills with the put records response.

Returns object

Property	Type	Description
failedRecordCount	number	The number of records that failed to be put.
records	Array	An array of record results.

Record result object

Property	Type	Description
sequenceNumber	string	The sequence number of the record (if successful).
shardId	string	The shard ID where the record was placed (if successful).
errorCode	string	The error code (if the record failed).
errorMessage	string	The error message (if the record failed).

Example

import {
  AWSConfig,
  KinesisClient,
} from 'https://jslib.k6.io/aws/0.14.0/kinesis.js';

const awsConfig = new AWSConfig({
  region: __ENV.AWS_REGION,
  accessKeyId: __ENV.AWS_ACCESS_KEY_ID,
  secretAccessKey: __ENV.AWS_SECRET_ACCESS_KEY,
});

const kinesis = new KinesisClient(awsConfig);

export default async function () {
  const streamName = 'my-test-stream';

  // Create records to put into the stream
  const records = [
    {
      data: JSON.stringify({
        message: 'Hello from k6!',
        timestamp: Date.now(),
        userId: 'user123',
      }),
      partitionKey: 'user123',
    },
    {
      data: JSON.stringify({
        message: 'Another message',
        timestamp: Date.now(),
        userId: 'user456',
      }),
      partitionKey: 'user456',
    },
    {
      data: JSON.stringify({
        message: 'Load test data',
        timestamp: Date.now(),
        userId: 'user789',
      }),
      partitionKey: 'user789',
      explicitHashKey: '123456789012345678901234567890123456789',
    },
  ];

  // Put records into the stream
  const result = await kinesis.putRecords(streamName, records);

  console.log('Put records result:');
  console.log('Failed record count:', result.failedRecordCount);

  // Check individual record results
  result.records.forEach((record, index) => {
    if (record.errorCode) {
      console.log(`Record ${index} failed: ${record.errorCode} - ${record.errorMessage}`);
    } else {
      console.log(
        `Record ${index} succeeded: sequence=${record.sequenceNumber}, shard=${record.shardId}`
      );
    }
  });
}