From 7b89f4a1c1ebde61e77f9135d80f84c8e07d9608 Mon Sep 17 00:00:00 2001 From: akkomar Date: Fri, 17 May 2024 17:36:07 +0200 Subject: [PATCH] Add documentation on server telemetry (#2840) Co-authored-by: Jan-Erik Rediger --- .dictionary | 2 ++ docs/user/README.md | 2 ++ docs/user/SUMMARY.md | 1 + .../adding-glean-to-your-project/index.md | 1 + .../adding-glean-to-your-project/server.md | 26 +++++++++++++++++++ 5 files changed, 32 insertions(+) create mode 100644 docs/user/user/adding-glean-to-your-project/server.md diff --git a/.dictionary b/.dictionary index 806a7f5ae..1756263c4 100644 --- a/.dictionary +++ b/.dictionary @@ -159,6 +159,7 @@ exe experimentId ffi fi +frontend func gfritzsche glibc @@ -209,6 +210,7 @@ npm ns ol ons +outputter pdoc perrymcmanis pidcat diff --git a/docs/user/README.md b/docs/user/README.md index 24385164d..b74b8e88a 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -26,6 +26,8 @@ To get started adding Glean to your project, choose one of the following guides: - Get started adding Glean to a Qt/QML application or library. +- **[Server](./user/adding-glean-to-your-project/server.md)** + - Get started adding Glean to a server-side application. For development documentation on the `Glean SDK`, refer to [the Glean SDK development book](../dev/index.html). diff --git a/docs/user/SUMMARY.md b/docs/user/SUMMARY.md index 92419ecea..baa9e932a 100644 --- a/docs/user/SUMMARY.md +++ b/docs/user/SUMMARY.md @@ -9,6 +9,7 @@ - [Rust](user/adding-glean-to-your-project/rust.md) - [JavaScript](user/adding-glean-to-your-project/javascript.md) - [Qt/QML](user/adding-glean-to-your-project/qt.md) + - [Server](user/adding-glean-to-your-project/server.md) - [Enable data ingestion](user/adding-glean-to-your-project/enable-data-ingestion.md) - [Integrating Glean for project managers](user/integrating-glean-for-product-managers.md) - [Metrics](user/metrics/adding-new-metrics.md) diff --git a/docs/user/user/adding-glean-to-your-project/index.md b/docs/user/user/adding-glean-to-your-project/index.md index 46e1cb9e2..346032012 100644 --- a/docs/user/user/adding-glean-to-your-project/index.md +++ b/docs/user/user/adding-glean-to-your-project/index.md @@ -41,5 +41,6 @@ Additionally, applications (but not libraries) **must**: > - [Rust](./rust.md) > - [Swift](./swift.md) > - [Qt/QML](./qt.md) +> - [Server](./server.md) [Glean Dictionary]: https://dictionary.telemetry.mozilla.org diff --git a/docs/user/user/adding-glean-to-your-project/server.md b/docs/user/user/adding-glean-to-your-project/server.md new file mode 100644 index 000000000..9c6d6c7d3 --- /dev/null +++ b/docs/user/user/adding-glean-to-your-project/server.md @@ -0,0 +1,26 @@ +# Adding Glean to your Server Application + +Glean enables the collection of behavioral metrics through events in server environments. This method does not rely on the Glean SDK but utilizes the Glean parser to generate native code for logging events in a standard format compatible with the ingestion pipeline. + +## Differences from using the Glean SDK + +This implementation of telemetry collection in server environments has some differences compared to using Glean SDK in client applications and Glean.js in the frontend of web applications. Primarily, in server environments the focus is exclusively on event-based metrics, diverging from the broader range of metric types supported by Glean. Additionally, there is no need to incorporate Glean SDK as a dependency in server applications. Instead, the Glean parser is used to generate native code for logging events. + +## When to use server-side collection + +This method is intended for collecting user-level behavioral events in server environments. It is not suitable for collecting system-level metrics or performance data, which should be collected using cloud monitoring tools. + +## How to add Glean server side collection to your service + +1. Integrate [`glean_parser`](https://github.com/mozilla/glean_parser#usage) into your build system. Follow instructions for other SDK-enabled platforms, e.g. [JavaScript](./javascript.md). Use a server outputter to generate logging code. `glean_parser` currently supports [Go](https://github.com/mozilla/glean_parser/blob/main/glean_parser/go_server.py), [JavaScript/Typescript](https://github.com/mozilla/glean_parser/blob/main/glean_parser/javascript_server.py), [Python](https://github.com/mozilla/glean_parser/blob/main/glean_parser/python_server.py), and [Ruby](https://github.com/mozilla/glean_parser/blob/main/glean_parser/ruby_server.py). +2. Define your metrics in `metrics.yaml` +3. Request a [data review](https://wiki.mozilla.org/Firefox/Data_Collection) for the collected data +4. [Add your product to probe-scraper](./enable-data-ingestion.html#add-your-product-to-probe-scraper) + +## How to add a new event to your server side collection + +Follow the standard Glean SDK guide for adding metrics to `metrics.yaml` file. + +## Technical details - ingestion + +For more technical details on how ingestion works, see the [Confluence page](https://mozilla-hub.atlassian.net/wiki/spaces/DATA/pages/741998604/Backend+telemetry+collection+with+Glean).