--- name: azion-configure-sampling-on-a-stream description: >- Send a share of a stream's events with Data Stream sampling, in Azion Console or with the Azion API, and check which streams stay active. --- # Configure sampling on a stream You can configure sampling on a [Data Stream](/en/documentation/platform/data-stream/) stream from Azion Console or with the Azion API. To limit a stream to the workloads you choose, which leaves the other streams active, refer to [Associate workloads with a stream](/en/documentation/guides/platform/observability/data-stream-associate-workloads/) instead. Sampling sends a percentage of the events a stream collects, picked at random. A lower rate reduces the volume, and the cost, of the data you collect and analyze. A stream with sampling covers every workload on the account, including workloads created later. For the bounds of each field, refer to [Stream settings](/en/documentation/platform/data-stream/stream-settings/#transform). > **Caution** > > Saving an active stream with sampling deactivates every other stream on the account, at any rate, `100` included. The API returns no error and no warning. To run several streams at once, give each one a workload filter instead of sampling. --- Select your interface once. The prerequisites and every task below show only that path. ## Prerequisites - A stream on your Azion account. To create one, refer to the [Data Stream quickstart](/en/documentation/platform/data-stream/quickstart/). - The **Edit Data Stream** permission. For details, refer to [Stream settings](/en/documentation/platform/data-stream/stream-settings/#permissions). **Console** - Access to Azion Console. To sign in, refer to [Access Azion Console](/en/documentation/guides/platform/account-and-billing/how-to-access-azion-console/). - An account with fewer than 3,000 workloads. At 3,000 workloads or more, the Console blocks the stream forms, and you manage streams through the API only. **API** - A [personal token](/en/documentation/guides/platform/account-and-billing/personal-tokens/) and `curl`. - The ID of the stream and the ID of its template. The list response of `GET /v4/workspace/stream/streams?fields=id,name,active,transform` carries both: the stream's `id`, and `template` in the `render_template` item of its `transform`. --- ## Set the sampling rate The rate is a whole number from 1 to 100: the percentage of events the stream sends. A rate of `100` sends every event, and it still counts as sampling. **Console** To set the sampling rate in Azion Console: 1. **Open Data Stream** Access [Azion Console](https://console.azion.com/) > **Data Stream**. 2. **Open the stream** In the list, select the row of the stream. The create form, opened with **+ Stream**, has the same **Transform** section. 3. **Select all workloads** In the **Transform** section, set **Option** to *All Current and Future Workloads*. The **Sampling** switch shows only with this option. 4. **Turn on Sampling** If **Sampling** is off, turn it on. **Sampling Rate (%)** appears. 5. **Enter the rate** In **Sampling Rate (%)**, enter the percentage of events to send, for example `60`. 6. **Select Save** 7. **Confirm the sampling warning** The **Attention** dialog shows `After activating and saving these settings, all other Data Streams will be disabled.` Select **Confirm**. The Console shows `Your data stream has been updated`. **API** To set the rate with the API, send a `PATCH` request with the `transform` array of the stream. Set `rate` in the `sampling` item, and keep the `render_template` item with the template ID of your stream. This example keeps template `2`, *Applications Event Collector*. Replace `` with the ID of your stream: ```bash curl -X PATCH 'https://api.azion.com/v4/workspace/stream/streams/' \ -H 'Content-Type: application/json' \ -H 'Authorization: Token [TOKEN VALUE]' \ -d '{ "transform": [ { "type": "sampling", "attributes": { "rate": 50 } }, { "type": "render_template", "attributes": { "template": 2 } } ] }' ``` The API answers `200` with the stream, which now carries the new rate: ```json { "state": "executed", "data": { "id": 12361, "name": "sampled-stream", … "transform": [ { "type": "sampling", "attributes": { "rate": 50 } }, { "type": "render_template", "attributes": { "template": 2 } } ], … } } ``` The `transform` you send replaces the stored one, so send every item the stream keeps. A rate outside 1 to 100 is refused with `400`: `0` with `10050` `Min Value`, and `101` with `10068` `Max Value`. A valid rate returns no warning that the other streams are deactivated. Data Stream picks the sampled events at random. The **Attention** dialog also states `Sampling percentage is statistical and not absolutely precise. When multiple Data Streams have different sampling rates, the system uses the lowest percentage.` A change of active stream takes effect after one to two minutes, and other edits take a few minutes to propagate. During that window, a stream that the save deactivated can keep sending. --- ## Check which streams are active After the save, the stream with sampling is the only active stream on the account. Wait two minutes, then check the status of each stream. **Console** To check the streams in Azion Console: 1. **Open Data Stream** Access [Azion Console](https://console.azion.com/) > **Data Stream**. 2. **Read the Status column** The stream you saved reads *Active*. Every other stream reads *Inactive*. 3. **Open the stream** Select the row of the stream. **Sampling Rate (%)** shows the stored rate. Only the sampled stream is *Active*, at the rate you set. **API** To check the streams with the API, list them with their `active` state and their `transform`: ```bash curl -X GET 'https://api.azion.com/v4/workspace/stream/streams?fields=id,name,active,transform' \ -H 'Authorization: Token [TOKEN VALUE]' ``` The API answers `200` with one entry for each stream: ```json { "count": 4, "total_pages": 1, "page": 1, "page_size": 10, "next": null, "previous": null, "results": [ { "id": 12345, "name": "activity-to-bucket", "active": false, "transform": [ { "type": "sampling", "attributes": { "rate": 100 } }, { "type": "render_template", "attributes": { "template": 251 } } ] }, … { "id": 12346, "name": "sampled-stream", "active": true, "transform": [ { "type": "sampling", "attributes": { "rate": 100 } }, { "type": "render_template", "attributes": { "template": 251 } } ] }, … ] } ``` The stream saved last with sampling is the only one with `"active": true`, such as `12346` in the sample above. Its `sampling` item carries the rate it uses. To see what the stream sends, read its sends in [Real-Time Events](/en/documentation/platform/real-time-events/data-sources/#data-stream). Each send is recorded with the status code of the endpoint and the number of log lines it carried. --- ## Next steps - [Stream settings](/en/documentation/platform/data-stream/stream-settings.md#transform): Look up the bounds of the sampling rate and the workload filter, and their errors. - [Associate workloads with a stream](/en/documentation/guides/platform/observability/data-stream-associate-workloads.md): Limit a stream to chosen workloads, so several streams can run at once. - [How Data Stream works](/en/documentation/platform/data-stream/how-it-works.md#sampling-and-workload-filters): Compare what sampling and a workload filter collect, and what each one costs. - [Troubleshoot Data Stream](/en/documentation/platform/data-stream/troubleshooting.md#another-stream-stopped-sending-after-you-saved-one): Restore a stream that stopped sending after a sampled stream was saved.