diff --git a/.dictionary b/.dictionary index baafec85af..cd56c3d518 100644 --- a/.dictionary +++ b/.dictionary @@ -1,4 +1,4 @@ -personal_ws-1.1 en 289 utf-8 +personal_ws-1.1 en 290 utf-8 AAR AARs ABI @@ -160,6 +160,7 @@ enqueue enqueued enum envs +etl exe experimentId ffi diff --git a/docs/user/SUMMARY.md b/docs/user/SUMMARY.md index 1362192e9c..94c7de3483 100644 --- a/docs/user/SUMMARY.md +++ b/docs/user/SUMMARY.md @@ -46,6 +46,8 @@ - [JavaScript](user/debugging/javascript.md) - [Walkthroughs and How-tos](user/howto/index.md) - [Server Knobs Walkthrough](user/howto/server-knobs-walkthrough/server-knobs-walkthrough.md) + - ["Real-Time" Events](user/howto/real-time-events/real-time-events.md) + # API Reference - [YAML Registry Format](reference/yaml/index.md) @@ -101,6 +103,7 @@ - [Command Line Interface](language-bindings/javascript/cli.md) - [Plugins](language-bindings/javascript/plugins/index.md) - [Ping Encryption Plugin](language-bindings/javascript/plugins/encryption.md) + # Appendix - [Glossary](appendix/glossary.md) diff --git a/docs/user/user/howto/real-time-events/real-time-events.md b/docs/user/user/howto/real-time-events/real-time-events.md new file mode 100644 index 0000000000..6d806048ee --- /dev/null +++ b/docs/user/user/howto/real-time-events/real-time-events.md @@ -0,0 +1,37 @@ +# "Real-Time" Events + +## Defining "Real-Time" Glean Events + +"Real-Time" in the context of [Glean events](../../../reference/metrics/event.md) directly relates to configuring the Glean SDK to send each event in an ["events" ping](../../pings/events.md) as soon as it is recorded. +This minimizes the time between instrumentation and reporting, but doesn't describe how quickly received data is made available for querying. + +## Configuring Glean For "Real-Time" Events + +Glean "events" ping submission can either be configured at [initialization](../../../reference/general/initializing.md) or through [Server Knobs](../../../user/server-knobs/other/max-events.md). + +Setting the maximum event threshold to a value of `1` will configure the Glean SDK to submit an "events" ping for every event recorded. + +## Considerations + +### What "Real-Time" Glean Events Are _Not_ + +Configuring the Glean SDK to submit events as soon as they are recorded does not mean to imply that the event data is available for analysis in +real time. There are networks to traverse, ingestion pipelines, etl, etc. that are all factors to keep in mind when considering how soon the data +is available for analysis purposes. This documentation only purports to cover configuring the Glean SDK to send the data in a real-time fashion and +does not make any assumptions about the analysis of data in real-time. + +### More Network Requests + +For every event recorded, a network request will be generated when the event is submitted for ingestion. By default, the Glean SDK batches up to +500 events per "events" ping, so this has the potential to generate up to 500 times as many network requests than the current default. + +### More Ingestion Endpoint Traffic + +As a result of the increased network requests, the ingestion endpoint will need to handle this additional traffic. This increases the load +of all the processing steps that are involved with ingesting event data from an application. + +### Storage Space + +Typically the raw dataset for Glean events contains 1-500 events in a single row of the database. This row also includes metadata such as +information about the client application and the ping itself. With only a single event per "events" ping, the replication of this metadata +across the database will use additional space to house this repeated information that should rarely if ever change between events diff --git a/docs/user/user/pings/events.md b/docs/user/user/pings/events.md index f55105096c..e71cc5a20f 100644 --- a/docs/user/user/pings/events.md +++ b/docs/user/user/pings/events.md @@ -19,7 +19,7 @@ The `events` ping is automatically submitted under the following circumstances: 1. If there are any recorded events to send when the application becomes inactive (on mobile, this means going to [background](sent-by-glean.md#defining-foreground-and-background-state)). 2. When the queue of events exceeds `Glean.configuration.maxEvents` (default 1 for Glean.js, 500 for all other SDKs). This configuration -option can be changed at [initialization](../../reference/general/initializing.md). +option can be changed at [initialization](../../reference/general/initializing.md) or through [Server Knobs](../../user/server-knobs/other/max-events.md). 3. If there are any unsent events found on disk when starting the application. _(This results in this ping never containing the [`glean.restarted`](./custom.md#the-gleanrestarted-event) event.)_