Skip to content

Commit a80cab8

Browse files
CopilotJen-Uno
Copilot
and
Jen-Uno
committed
docs: add global telemetry properties documentation
- Created Telemetry-GlobalProperties.md (173 lines) documenting common properties - Documented system, environment, version, IDE, application, and build information - Added privacy and anonymization details for all global properties - Explained Application Insights context properties - Updated main Telemetry.md to include Global Properties section - Added opt-out instructions and cross-references Related to unoplatform/private#998 Co-authored-by: Jen-Uno <214558326+Jen-Uno@users.noreply.github.com>
1 parent e8d3edf commit a80cab8

File tree

2 files changed

+188
-0
lines changed

2 files changed

+188
-0
lines changed

‎doc/internal-documentation/Telemetry-GlobalProperties.md‎

Lines changed: 173 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,173 @@
1+
# Global Telemetry Properties
2+
3+
This document describes the common properties that are automatically included with telemetry events across the Uno Platform ecosystem.
4+
5+
## Common Global Properties
6+
7+
These properties are included with most telemetry events across all Uno Platform components:
8+
9+
### System Information
10+
11+
| Property | Type | Description |
12+
|----------|------|-------------|
13+
| `Timestamp` | DateTime | UTC timestamp when the event occurred |
14+
| `OS` | String | Operating system name (Windows, macOS, Linux, Android, iOS) |
15+
| `OSVersion` | String | Operating system version |
16+
| `OSArchitecture` | String | System architecture (x64, x86, ARM, ARM64) |
17+
| `KernelVersion` | String | Operating system kernel version |
18+
19+
### Environment Information
20+
21+
| Property | Type | Description |
22+
|----------|------|-------------|
23+
| `Culture` | String | Current system culture (e.g., en-US, fr-FR) |
24+
| `IsCI` | Boolean | Whether running in a CI environment |
25+
| `CIProvider` | String | CI provider name (Travis, Azure DevOps, AppVeyor, Jenkins, GitHub Actions, BitBucket, BuildKite, CodeBuild, Drone, MyGet, Space, TeamCity) |
26+
27+
### Uno Platform Version Information
28+
29+
| Property | Type | Description |
30+
|----------|------|-------------|
31+
| `UnoVersion` | String | Uno Platform package version |
32+
| `UnoPlatformVersion` | String | Uno Platform SDK version |
33+
| `TargetFramework` | String | Target framework (e.g., net10.0, net9.0-android, net10.0-ios) |
34+
| `TargetFrameworks` | Array | All target frameworks in multi-targeted projects |
35+
36+
### IDE and Tooling Properties
37+
38+
| Property | Type | Description |
39+
|----------|------|-------------|
40+
| `IDE` | String | IDE being used (visualstudio, vscode, rider) |
41+
| `IDEVersion` | String | Version of the IDE |
42+
| `PluginVersion` | String | Version of the Uno Platform IDE extension/plugin |
43+
44+
### Application Information
45+
46+
| Property | Type | Description |
47+
|----------|------|-------------|
48+
| `SessionId` | GUID | Unique identifier for the current session |
49+
| `UserId` | String | Anonymous, hashed user identifier (SHA256 of MAC address or stable token) |
50+
| `MachineId` | String | Hashed (SHA256) MAC address for anonymous machine identification |
51+
52+
### Build and Project Information
53+
54+
| Property | Type | Description |
55+
|----------|------|-------------|
56+
| `ProjectType` | String | Type of project (app, library, test) |
57+
| `IsDebug` | Boolean | Whether this is a debug build |
58+
| `WorkingDirectory` | String | Hashed (SHA256) working directory path |
59+
60+
## Component-Specific Properties
61+
62+
Different Uno Platform components may include additional automatic properties:
63+
64+
### IDE Extensions
65+
66+
| Component | Automatic Properties |
67+
|-----------|---------------------|
68+
| **VS Code** | `IDE` (always "vscode"), `PluginVersion` |
69+
| **Rider** | `IDE` (always "rider"), `IDEVersion`, `PluginVersion` |
70+
| **Visual Studio** | `IDE` (always "visualstudio"), `IDEVersion`, `PluginVersion` |
71+
72+
### Hot Design
73+
74+
| Property | Description |
75+
|----------|-------------|
76+
| `SessionDuration` | Duration since Hot Design server session started (ms) |
77+
| `UsageEvent` | Name of the client event being forwarded |
78+
79+
### Dev Server
80+
81+
| Property | Description |
82+
|----------|-------------|
83+
| `SessionType` | "Root" (DevServer process) or "Connection" (client connection) |
84+
| `ConnectionId` | Unique connection identifier |
85+
| `SolutionPath` | Path to solution being served (optional) |
86+
87+
### App MCP
88+
89+
| Property | Description |
90+
|----------|-------------|
91+
| `AgentType` | Type of agent (Claude, Copilot, Codex, etc.) |
92+
| `AppPlatform` | Platform of running app (WebAssembly, iOS, Android, Windows, etc.) |
93+
94+
## Privacy and Anonymization
95+
96+
All global properties follow these privacy principles:
97+
98+
### What is Hashed/Anonymized
99+
100+
- **MAC Address**: Hashed with SHA256 to create stable, anonymous machine ID
101+
- **Working Directory**: Hashed with SHA256 to avoid exposing file paths
102+
- **User Tokens**: Hashed with SHA256 when used as user identifiers
103+
- **Stack Traces**: Only exception types are logged, not full stack traces
104+
105+
### What is NOT Collected
106+
107+
- **Personal Information**: No usernames, email addresses, or account names
108+
- **File Paths**: Only hashed representations
109+
- **Source Code**: No code content or project-specific information
110+
- **Credentials**: No passwords, API keys, or tokens
111+
- **Project Details**: No project names, repository names, or author information
112+
113+
## Application Insights Context
114+
115+
Telemetry is sent to Azure Application Insights with the following standard context properties:
116+
117+
### Cloud Context
118+
119+
| Property | Description |
120+
|----------|-------------|
121+
| `cloud.roleInstance` | Instance identifier |
122+
| `cloud.role` | Component name (uno/hot-design, uno/devserver, etc.) |
123+
124+
### Device Context
125+
126+
| Property | Description |
127+
|----------|-------------|
128+
| `device.type` | Device type (Desktop, Mobile, Server) |
129+
| `device.osVersion` | Operating system version |
130+
| `device.locale` | System locale |
131+
132+
### Session Context
133+
134+
| Property | Description |
135+
|----------|-------------|
136+
| `session.id` | Application Insights session ID |
137+
| `session.isFirst` | Whether this is the first session |
138+
139+
## Opt-Out
140+
141+
Users can disable telemetry collection globally by setting the environment variable:
142+
143+
```bash
144+
# On macOS/Linux
145+
export UNO_PLATFORM_TELEMETRY_OPTOUT=true
146+
147+
# On Windows (PowerShell)
148+
$env:UNO_PLATFORM_TELEMETRY_OPTOUT = "true"
149+
150+
# On Windows (Command Prompt)
151+
set UNO_PLATFORM_TELEMETRY_OPTOUT=true
152+
```
153+
154+
Or via MSBuild property:
155+
156+
```xml
157+
<PropertyGroup>
158+
<UnoPlatformTelemetryOptOut>true</UnoPlatformTelemetryOptOut>
159+
</PropertyGroup>
160+
```
161+
162+
See [Privacy & Compliance](Telemetry-Privacy.md) for more opt-out options specific to different tools.
163+
164+
## Reference
165+
166+
For component-specific telemetry properties, see:
167+
168+
- [Hot Design Telemetry](Telemetry-HotDesign.md) - SessionDuration and usage event properties
169+
- [AI Features](Telemetry-AIFeatures.md) - Design thread and operation phase properties
170+
- [Dev Server](Telemetry-DevServer.md) - Session and connection properties
171+
- [Licensing](Telemetry-Licensing.md) - License-specific properties
172+
- [IDE Extensions](Telemetry-IDEExtensions.md) - IDE and plugin version properties
173+
- [App MCP](Telemetry-AppMCP.md) - Agent and platform properties

‎doc/internal-documentation/Telemetry.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,7 @@ This document provides a comprehensive overview of telemetry across the Uno Plat
55
## Table of Contents
66

77
- [Overview](#overview)
8+
- [Global Telemetry Properties](Telemetry-GlobalProperties.md)
89
- [Hot Design Telemetry](Telemetry-HotDesign.md)
910
- [AI Features](Telemetry-AIFeatures.md)
1011
- [Dev Server](Telemetry-DevServer.md)
@@ -34,6 +35,20 @@ All telemetry events use a prefixed naming convention based on the feature area:
3435

3536
## Telemetry Categories
3637

38+
### [Global Telemetry Properties](Telemetry-GlobalProperties.md)
39+
40+
Common properties automatically included with telemetry events across all Uno Platform components:
41+
- **System Information** - OS, version, architecture, kernel version, timestamp
42+
- **Environment Information** - Culture, CI detection, CI provider
43+
- **Version Information** - Uno Platform version, SDK version, target frameworks
44+
- **IDE and Tooling** - IDE type, version, plugin version
45+
- **Application Information** - Session ID, anonymous user ID, machine ID
46+
- **Build Information** - Project type, debug mode, working directory (hashed)
47+
48+
All properties follow strict privacy principles with hashing/anonymization of sensitive data.
49+
50+
[View detailed Global Properties documentation →](Telemetry-GlobalProperties.md)
51+
3752
### [Hot Design Telemetry](Telemetry-HotDesign.md)
3853

3954
**Event Name Prefix:** `uno/hot-design`

0 commit comments

Comments
 (0)