Skip to content

Commit c562285

Browse files
authored
Add Telemetry Documentation (#345)
- Created a new page that describes what telemetry is collected, how it’s used, and how to opt out. - Updated README for the repo and the Docs homepage to reflect that telemetry collection is now in place. --- ### **Checklist** - [ ] Tests added/updated - [x] Documentation updated (if needed) - [ ] Code conforms to style guidelines
1 parent 1fb42a4 commit c562285

File tree

3 files changed

+77
-0
lines changed

3 files changed

+77
-0
lines changed

README.md

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,14 @@ detailed instructions on getting started and building.
3232
Have questions, found a bug, or need a new feature? Open an issue in our [GitHub
3333
repository](https://github.com/microsoft/azure-linux-image-tools/issues/new?template=Blank+issue).
3434

35+
## Telemetry
36+
37+
Image Customizer collects usage data to help improve the product. This data
38+
helps us understand usage patterns, diagnose issues, improve reliability, and
39+
prioritize new features based on real-world usage. Learn how Image Customizer
40+
collects and uses telemetry, and how to opt out
41+
[here](https://microsoft.github.io/azure-linux-image-tools/imagecustomizer/telemetry.html).
42+
3543
---
3644

3745
## Trademarks

docs/imagecustomizer/README.md

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,13 @@ other Linux distributions as well.
6161
- [Configuration](./api/configuration.md) - Understand how to configure Image
6262
Customizer to suit your needs
6363

64+
## Telemetry
65+
66+
Image Customizer collects usage data to help improve the product. This data
67+
helps us understand usage patterns, diagnose issues, improve reliability, and
68+
prioritize new features based on real-world usage. Learn how Image Customizer
69+
collects and uses telemetry, and how to opt out [here](telemetry.md).
70+
6471
## Help and Feedback
6572

6673
If you'd like to report bugs, request features, or contribute to the tool, you

docs/imagecustomizer/telemetry.md

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
---
2+
title: Telemetry
3+
parent: Image Customizer
4+
nav_order: 7
5+
---
6+
7+
# Telemetry in Image Customizer
8+
9+
Image Customizer collects usage data to help improve the product. This data
10+
helps us understand usage patterns, diagnose issues, improve reliability and
11+
prioritize new features based on real-world usage. This section describes what
12+
telemetry is collected, how it’s used, and how to opt out.
13+
14+
## Scope
15+
16+
Image Customizer can be run in two ways:
17+
18+
- As a container image downloaded from Microsoft Artifact Registry
19+
- As a binary built from the GitHub repository
20+
21+
Telemetry is collected in both cases.
22+
23+
## How to opt out
24+
25+
Telemetry collection for Image Customizer is enabled by default. To opt out, use
26+
the flag `--disable-telemetry`. Here is a sample command:
27+
28+
```bash
29+
docker run \
30+
--rm \
31+
--privileged=true \
32+
-v /dev:/dev \
33+
-v "$HOME/staging:/mnt/staging:z" \
34+
mcr.microsoft.com/azurelinux/imagecustomizer:0.15.0 \
35+
imagecustomizer \
36+
--image-file "/mnt/staging/image.vhdx" \
37+
--config-file "/mnt/staging/image-config.yaml" \
38+
--build-dir "/build" \
39+
--output-image-format "vhdx" \
40+
--output-image-file "/mnt/staging/out/image.vhdx"
41+
--disable-telemetry
42+
```
43+
44+
### Data Collection and Storage
45+
46+
Image Customizer doesn't collect personal data, such as IP addresses, usernames,
47+
Azure subscription IDs or email addresses. Telemetry is collected using the
48+
[OpenTelemetry (OTel)](https://learn.microsoft.com/en-us/azure/azure-monitor/app/opentelemetry-overview)
49+
framework and is stored securely in an Azure Monitor Workspace to be used only
50+
for product improvement and diagnostics.
51+
52+
The telemetry feature collects the following data:
53+
54+
| Category |Examples |
55+
|-------------------|--------------------------------------------------------------------------|
56+
| Usage Metrics | Number of image customizations, API call frequency, Number of Image Customizer downloads |
57+
| Environment Info | Host OS (e.g., WSL, Ubuntu, Azure Linux), base image-format |
58+
| Performance | Image creation success and failure rates, error codes, Time taken to create images |
59+
60+
61+
Protecting your privacy is important to us. You can always opt out and continue
62+
using the tool without restrictions.

0 commit comments

Comments
 (0)