Skip to content

Destination function batching updates [DOC-527] #3115

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

Merged
merged 12 commits into from
Jun 30, 2022
Merged

Destination function batching updates [DOC-527] #3115

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
2c521a9
Removed beta note, updated batch parameters section
forstisabella Jun 21, 2022
95fc296
Merge branch 'develop' into DOC-527-IG
forstisabella Jun 21, 2022
bf132d4
Fixing casing [DOC-527]
forstisabella Jun 22, 2022
a255752
Updates to batch parameters, error sections
forstisabella Jun 23, 2022
107e3c8
Updating the error names to be consistent with earlier section
forstisabella Jun 23, 2022
92f9ca4
Updating the batching errors section with new info
forstisabella Jun 23, 2022
e179bd3
Merge branch 'develop' into DOC-527-IG
forstisabella Jun 23, 2022
4d5cff7
Word choice update
forstisabella Jun 23, 2022
bf4b7aa
Clarifying language
forstisabella Jun 23, 2022
da82d68
[netlify-build] Vale, adding {:target="_blank"} to external links, sc…
forstisabella Jun 24, 2022
7667648
Removed images that were commented out [DOC-527]
forstisabella Jun 24, 2022
05b22c7
Making requested changes [netlify-build] DOC-527
forstisabella Jun 28, 2022
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
6 changes: 3 additions & 3 deletions src/_includes/content/functions/settings.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,11 +4,11 @@ Settings allow you to pass configurable variables to your function, which is the

First, add a setting in **Settings** tab in the code editor:

![Settings Tab](/docs/connections/functions/images/settings-tab-empty.png){:width="500"}
![A screenshot of the functions settings tab](/docs/connections/functions/images/settings-tab-empty.png){:width="500"}

Click **Add Setting** to add your new setting.

![Add Setting Dialog](/docs/connections/functions/images/add-setting-dialog.png)
![A screenshot of the "Add Setting" section of the functions settings tab, with apiKey settings included](/docs/connections/functions/images/add-setting-dialog.png)

You can configure the details about this setting, which change how it's displayed to anyone using your function:

Expand All @@ -25,4 +25,4 @@ Click **Add Setting** to save the new setting.

Once you save a setting, it appears in the **Settings** tab for the function. You can edit or delete settings from this tab.

![Settings Tab](/docs/connections/functions/images/settings-tab-non-empty.png){:width="500"}
![A screenshot of the functions settings tab, showing the apiKey setting](/docs/connections/functions/images/settings-tab-non-empty.png){:width="500"}
88 changes: 53 additions & 35 deletions src/connections/functions/destination-functions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,27 +11,25 @@ Destination functions allow you to transform and annotate your Segment events an
All functions are scoped to your workspace, so members of other workspaces can't view or use them.

> info ""
> Functions is available to all customer plan types with a free allotment of usage hours. Read more about [Functions usage limits](/docs/connections/functions/usage/), or see [your workspace's Functions usage stats](https://app.segment.com/goto-my-workspace/settings/usage?metric=functions).
> Functions is available to all customer plan types with a free allotment of usage hours. Read more about [Functions usage limits](/docs/connections/functions/usage/), or see [your workspace's Functions usage stats](https://app.segment.com/goto-my-workspace/settings/usage?metric=functions){:target="_blank"}.

![](images/destination_functions_overview.png)
![An illusrative graphic showing information flowing from the Segment app, into code, and then into Slack](images/destination_functions_overview.png)


> note ""
> Destination functions does not accept data from [Object Cloud sources](/docs/connections/sources/#object-cloud-sources).

## Create a destination function

1. From your workspace, go to the Catalog and click the [Functions tab](https://app.segment.com/goto-my-workspace/functions/catalog).
1. From your workspace, go to the Catalog and click the [Functions tab](https://app.segment.com/goto-my-workspace/functions/catalog){:target="_blank"}.
2. Click **New Function**.
3. Select **Destination Function** and click **Build**.

> success ""
> **Tip:** Want to see some example functions? Check out the templates available in the Functions UI, or in the open-source [Segment Functions Library](https://github.com/segmentio/functions-library). (Contributions welcome!)
> **Tip:** Want to see some example functions? Check out the templates available in the Functions UI, or in the open-source [Segment Functions Library](https://github.com/segmentio/functions-library){:target="_blank"}. (Contributions welcome!)

When you click **Build**, a code editor appears. Use the editor to write the code for your function, configure settings, and test the function's behavior.

![Functions Editor](images/editor-dest.png)

## Code the destination function

Segment invokes a separate part of the function (called a "handler") for each event type that you send to your destination function.
Expand Down Expand Up @@ -78,7 +76,7 @@ async function onTrack(event) {
To change which event type the handler listens to, you can rename it to the name of the message type. For example, if you rename this function `onIdentify`, it listens for "Identify" events instead.

> info ""
> Functions' runtime includes a `fetch()` polyfill using a `node-fetch` package. Check out the [node-fetch documentation](https://www.npmjs.com/package/node-fetch) for usage examples.
> Functions' runtime includes a `fetch()` polyfill using a `node-fetch` package. Check out the [node-fetch documentation](https://www.npmjs.com/package/node-fetch){:target="_blank"} for usage examples.

### Errors and error handling

Expand Down Expand Up @@ -140,17 +138,14 @@ You can read more about [error handling](#destination-functions-logs-and-errors)
{% include content/functions/runtime.md %}


<!-- TODO - could also go into the `runtime.md` include above, if applied identically to both types of functions.
## Batching in functions -->
<!-- TODO - could also go into the `runtime.md` include above, if applied identically to both types of functions. -->

## Create settings and secrets

{% include content/functions/settings.md %}

Next, fill out this setting's value in the **Test** tab, so you can run the function and verify that the correct setting value is passed. (This value is only for testing your function.)

![Test Value For Setting](images/setting-in-test-tab.png){:width="500"}

Now that you've configured a setting and entered a test value, you can add code to read its value and run the function, as in the example below:

```js
Expand All @@ -162,8 +157,6 @@ async function onTrack(request, settings) {

When you deploy your destination function in your workspace, you fill out the settings on the destination configuration page, similar to how you would configure a normal destination.

![Destination Function Settings](images/dest-settings.png)

## Test the destination function

You can test your code directly from the editor in two ways:
Expand All @@ -172,32 +165,27 @@ You can test your code directly from the editor in two ways:

Click **Use Sample Event** and select the source to use events from.

![Capture events to test your function](images/autofill-events.gif)
![An animation showing someone using the Use Sample Event button, selecting a source, and clicking "Use Event"](images/autofill-events.gif)

Click **Run** to test your function with the event you selected.

### Test using manual input

You can also manually include your own JSON payload of a Segment event, instead of fetching a sample from one of your workspace sources.

![Functions Editor Event Tester](images/editor-test.gif)
![An animation showing someone clicking the run button in the Test panel and viewing a successful output](images/editor-test.gif)

If your function fails, you can check the error details and logs in the **Output** section.

- **Error Message** - This shows the error surfaced from your function.
- **Logs** - This section displays any messages to `console.log()` from the function.

## Batching the destination function (Beta)

> warning ""
> Batch handling for Functions is available as an early access beta release. By enabling batch handlers for your function, you acknowledge that your use of batch handlers is subject to [Segment's Beta Terms and Conditions](https://segment.com/legal/first-access-beta-preview), or the applicable terms governing Beta Releases found in your subscription agreement with Segment.
>
> If you notice any bugs or have any general feedback on this new feature, please fill out [this form](https://airtable.com/shr9TU4huO0PK0DSU).
## Batching the destination function

Batch handlers are an extension of destination functions. When you define an `onBatch` handler alongside the handler functions for single events (for example: `onTrack` or `onIdentity`), you're telling Segment that the destination function can accept and handle batches of events.

> info ""
> Batching is available to destination functions only.
> Batching is available for destination functions only.

### When to use batching

Expand Down Expand Up @@ -283,13 +271,16 @@ async function onIdentifyBatch(events, settings) {

### Configure your batch parameters

You cannot configure batch parameters (either in the code or UI) in this version of the beta. Functions waits up to 10 seconds to form a batch of 20 events. If you would like to change your batch parameters, please fill out [this form](https://airtable.com/shr9TU4huO0PK0DSU) and Support will contact you once this is made available.
By default, Functions waits up to 10 seconds to form a batch of 20 events. You can increase the number of events included in each batch (up to 400 events per batch) by contacting [Segment support](https://segment.com/help/contact/){:target="_blank"}. Segment recommends users who wish to include fewer than 20 events per batch use destination functions without the `onBatch` handler.

### Test the batch handler

The [Functions editing environment](/docs/connections/functions/environment/) supports testing batch handlers. In the right panel of the Functions editor, click **customize the event yourself** to enter Manual Mode. Add events as a JSON array, with one event per element. Click **Run** to preview the batch handler with the specified events.
The [Functions editing environment](/docs/connections/functions/environment/) supports testing batch handlers.

![Batch handler testing](images/batch-function-editor.png)
To test the batch handler:
1. In the right panel of the Functions editor, click **customize the event yourself** to enter Manual Mode.
2. Add events as a JSON array, with one event per element.
3. Click **Run** to preview the batch handler with the specified events.

> note ""
> The Sample Event option tests single events only. You must use Manual Mode to add more than one event so you can test batch handlers.
Expand All @@ -300,7 +291,35 @@ The [Config API](/docs/config-api/) Functions/Preview endpoint also supports tes

### Handling batching errors

Standard [function error types](/docs/connections/functions/destination-functions/#destination-functions-error-types) apply to batch handlers. Segment attempts to retry the batch in the case of Timeout or Retry errors. For all other error types, Segment discards the batch. If only part of a batch succeeds, Segment does not retry the failing part of the batch.
Standard [function error types](/docs/connections/functions/destination-functions/#destination-functions-error-types) apply to batch handlers. Segment attempts to retry the batch in the case of Timeout or Retry errors. For all other error types, Segment discards the batch. It is also possible to report a partial failure by returning status of each event in the batch. Segment retries only the failed events in a batch until those events are successful or until they result in a permanent error.

```json
[
{
"status": 200
},
{
"status": 400,
"errormessage": "Bad Request"
},
{
"status": 200
},
{
"status": 500,
"errormessage": "Error processing request"
},
{
"status": 500,
"errormessage": "Error processing request"
},
{
"status": 200
},
]
```

After receiving the response from the `onBatch` handler, only **event_3** and **event_4** will be retried.

| Error Type | Result |
| ---------------------- | ------- |
Expand All @@ -311,6 +330,7 @@ Standard [function error types](/docs/connections/functions/destination-function
| Timeout | Retry |
| Unsupported Event Type | Discard |


## Save and deploy the function

Once you finish building your destination function, click **Configure** to name it, then click **Create Function** to save it.
Expand All @@ -325,12 +345,12 @@ You can also choose to **Save & Deploy** to save the changes, and then choose wh

A function can throw errors, or Segment might encounter errors while invoking your function. You can view these errors in the [Event Delivery](/docs/connections/event-delivery/) tab for your Destination as in the example below.

![Destination Function Event Delivery tab](images/event-delivery.png)
![A screenshot of the event delivery tab, showing 519 failed events broken into categories explaining why they failed](images/event-delivery.png)

### Destination functions error types

- **Bad Request** - Any error thrown by the function code that is not covered by the other errors.
- **Invalid Settings** - A configuration error prevented Segment from executing your code. If this error persists for more than an hour, [contact Segment Support](https://segment.com/help/contact/).
- **Invalid Settings** - A configuration error prevented Segment from executing your code. If this error persists for more than an hour, [contact Segment Support](https://segment.com/help/contact/){:target="_blank"}.
- **Message Rejected** - Your code threw `InvalidEventPayload` or `ValidationError` due to invalid input.
- **Unsupported Event Type** - Your code does not implement a specific event type (`onTrack()`, etc.) or threw a `EventNotSupported` error.
- **Retry** - Your code threw `RetryError` indicating that the function should be retried.
Expand All @@ -343,9 +363,7 @@ If your function throws an error, execution halts immediately. Segment captures

Segment then displays the captured error information in the [Event Delivery](/docs/connections/event-delivery/) page for your destination function. You can use this information to find and fix unexpected errors.

![Destination Function error logs](images/error-logs-dest.png)

You can throw [an error or a custom error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) and you can also add helpful context in logs using the [`console` API](https://developer.mozilla.org/en-US/docs/Web/API/console). For example:
You can throw [an error or a custom error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error){:target="_blank"} and you can also add helpful context in logs using the [`console` API](https://developer.mozilla.org/en-US/docs/Web/API/console){:target="_blank"}. For example:

```js
async function onTrack(event, settings) {
Expand Down Expand Up @@ -397,7 +415,7 @@ async function getAccessToken () {

### Editing and deleting functions

If you are a **Workspace Owner** or **Functions Admin**, you can manage your function from the [Functions](https://app.segment.com/goto-my-workspace/functions/catalog) page.
If you are a **Workspace Owner** or **Functions Admin**, you can manage your function from the [Functions](https://app.segment.com/goto-my-workspace/functions/catalog){:target="_blank"} page.


### Monitoring destination functions
Expand Down Expand Up @@ -432,19 +450,19 @@ Yes, Functions access is logged in the [Audit Trail](/docs/segment-app/iam/audit

##### Does Segment retry failed function invocations?

Segment retries 9 times over the course of 4 hours. This increases the number of attempts for messages, so we try to re-deliver them another 4 times after some backoff. Segment doesn't retry if your function throws a [non-recoverable error](#errors-and-error-handling).
Segment retries 9 times over the course of 4 hours. This increases the number of attempts for messages, so Segment tries to re-deliver them another 4 times after some backoff. Segment doesn't retry if your function throws a [non-recoverable error](#errors-and-error-handling).

##### Are events guaranteed to send data in order?

No, Segment can't guarantee the order in which the events are delivered to an endpoint.

##### Can I create a device-mode destination?

No, destination functions are currently available as cloud-mode destinations only. We're in the early phases of exploration and discovery for supporting customer "web plugins" for custom device-mode destinations and other use cases, but this is unsupported today.
No, destination functions are currently available as cloud-mode destinations only. Segment is in the early phases of exploration and discovery for supporting customer "web plugins" for custom device-mode destinations and other use cases, but this is unsupported today.

##### How do I publish a destination to the public Segment catalog?

If you are a partner, looking to publish your destination and distribute your app through Segment catalog, visit the [Developer Center](https://segment.com/partners/developer-center/) and check out our [partner docs](/docs/partners/).
If you are a partner, looking to publish your destination and distribute your app through Segment catalog, visit the [Developer Center](https://segment.com/partners/developer-center/){:target="_blank"} and check out the Segment [partner docs](/docs/partners/).

##### How does batching affect visibility?

Expand Down