Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document gRPC stram message's metadata #1735

Merged
merged 3 commits into from
Sep 25, 2024
Merged

Document gRPC stram message's metadata #1735

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
3ec1410
clean unused const from gRPC examples
olegbespalov Sep 23, 2024
ba9e0a0
Make example second heading to extract it from gRPC metrics section
olegbespalov Sep 24, 2024
e751e1c
Document gRPC message metadata
olegbespalov Sep 23, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/sources/next/javascript-api/k6-net-grpc/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,7 +15,7 @@ aliases:
k6 takes specific measurements for gRPC requests.
For the complete list, refer to the [Metrics reference](https://grafana.com/docs/k6/<K6_VERSION>/using-k6/metrics/reference#grpc).

### Example
## Example

{{< code >}}

Expand Down
2 changes: 2 additions & 0 deletions docs/sources/next/javascript-api/k6-net-grpc/stream/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,8 @@ Using a gRPC client creates a stream. The client should be connected to the serv
| [Stream.write(message)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/stream-write) | Writes a message to the stream. |
| [Stream.on(event, handler)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/stream-on) | Sets up handler functions for various events on the gRPC stream. |
| [Stream.end()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/stream-end) | Signals to the server that the client has finished sending. |
| [EventHandler](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/event-handler) | The handler function for various events on the gRPC stream. |
| [Metadata](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/message-metadata) | The metadata of a gRPC stream's message. |

### Examples

Expand Down
49 changes: 49 additions & 0 deletions docs/sources/next/javascript-api/k6-net-grpc/stream/event-handler.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
---
title: 'Event Handler'
description: 'The handler function for various events on the gRPC stream.'
weight: 50
---

# Event Handler

The function to call for various events on the gRPC stream. It is set up using the [`stream.on()`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/stream-on) method.

| Name | Type | Description |
| ---------- | ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
| `data` | object or [`Error`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/stream-error) | It's either object with the data from server (a message) or an error object, in case of `error` event |
| `metadata` | [`Metadata`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/message-metadata) | The object that represents the gRPC stream's message metadata. |

### Example

<div class="code-group" data-props='{"labels": ["A handler metadata example"], "lineNumbers": [true]}'>

```javascript
import { Client, Stream } from 'k6/net/grpc';
import { sleep } from 'k6';

const client = new Client();
client.load([], '../../grpc_server/route_guide.proto');

export default () => {
if (__ITER == 0) {
client.connect('127.0.0.1:10000', { plaintext: true });
}

const stream = new Stream(client, 'main.RouteGuide/RecordRoute');

// sets up a handler for the data (server sends data) event
stream.on('data', (stats, metadata) => {
console.log('It took', stats.elapsedTime, 'seconds');
console.log('This message has been received:', metadata.ts);
});

stream.on('end', function () {
// The server has finished sending
client.close();
});

sleep(1);
};
```

</div>
48 changes: 48 additions & 0 deletions docs/sources/next/javascript-api/k6-net-grpc/stream/message-metadata.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,48 @@
---
title: 'Metadata'
description: "The metadata of a gRPC stream's message."
weight: 60
---

# Metadata

The `Metadata` is an object that represents the gRPC stream's message.

| Name | Type | Description |
| ------------- | ------ | -------------------------------------------------------------------------------------------- |
| `Metadata.ts` | number | Contains the timestamp of the original event. For example, when a message has been received. |

### Example

<div class="code-group" data-props='{"labels": ["A handler metadata example"], "lineNumbers": [true]}'>

```javascript
import { Client, Stream } from 'k6/net/grpc';
import { sleep } from 'k6';

const client = new Client();
client.load([], '../../grpc_server/route_guide.proto');

export default () => {
if (__ITER == 0) {
client.connect('127.0.0.1:10000', { plaintext: true });
}

const stream = new Stream(client, 'main.RouteGuide/RecordRoute');

// sets up a handler for the data (server sends data) event
stream.on('data', (stats, metadata) => {
console.log('It took', stats.elapsedTime, 'seconds');
console.log('This message has been received:', metadata.ts);
});

stream.on('end', function () {
// The server has finished sending
client.close();
});

sleep(1);
};
```

</div>
2 changes: 0 additions & 2 deletions docs/sources/next/javascript-api/k6-net-grpc/stream/stream-end.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,6 @@ Signals to the server that the client has finished sending messages.
import { Client, Stream } from 'k6/net/grpc';
import { sleep } from 'k6';

const COORD_FACTOR = 1e7;

const client = new Client();
client.load([], '../../grpc_server/route_guide.proto');

Expand Down
10 changes: 4 additions & 6 deletions docs/sources/next/javascript-api/k6-net-grpc/stream/stream-on.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,10 +10,10 @@ aliases:

Set up handler functions for various events on the gRPC stream.

| Parameter | Type | Description |
| --------- | -------- | -------------------------------------------- |
| event | string | The event name to define a handler for. |
| handler | function | The function to call when the event happens. |
| Parameter | Type | Description |
| --------- | ---------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| event | string | The event name to define a handler for. |
| handler | [`EventHandler`](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/event-handler) | The function to call when the event happens. |

Possible events:

Expand All @@ -31,8 +31,6 @@ Possible events:
import { Client, Stream } from 'k6/net/grpc';
import { sleep } from 'k6';

const COORD_FACTOR = 1e7;

const client = new Client();
client.load([], '../../grpc_server/route_guide.proto');

Expand Down
2 changes: 0 additions & 2 deletions docs/sources/next/javascript-api/k6-net-grpc/stream/stream-write.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,8 +18,6 @@ Writes a message to the stream. The message is a canonical request object, as-pe
import { Client, Stream } from 'k6/net/grpc';
import { sleep } from 'k6';

const COORD_FACTOR = 1e7;

const client = new Client();
client.load([], '../../grpc_server/route_guide.proto');

Expand Down
2 changes: 2 additions & 0 deletions docs/sources/next/shared/javascript-api/k6-net-grpc.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,3 +19,5 @@ The [`k6/net/grpc` module](https://grafana.com/docs/k6/<K6_VERSION>/javascript-a
| [Stream.on(event, handler)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/stream-on) | Adds a new listener to one of the possible stream events. |
| [Stream.write(message)](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/stream-write) | Writes a message to the stream. |
| [Stream.end()](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/stream-end) | Signals to the server that the client has finished sending. |
| [EventHandler](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/event-handler) | The function to call for various events on the gRPC stream. |
| [Metadata](https://grafana.com/docs/k6/<K6_VERSION>/javascript-api/k6-net-grpc/stream/message-metadata) | The metadata of a gRPC stream’s message. |
Loading