Skip to content

Commit e7cefa3

Browse files
author
Rajdeep Chandra
committed
test: testing telemetry system
1 parent b00b6b0 commit e7cefa3

File tree

7 files changed

+1388
-0
lines changed

7 files changed

+1388
-0
lines changed

‎packages/theme/src/telemetry-config.ts

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
/*
2+
Copyright 2024 Adobe. All rights reserved.
3+
This file is licensed to you under the Apache License, Version 2.0 (the "License");
4+
you may not use this file except in compliance with the License. You may obtain a copy
5+
of the License at http://www.apache.org/licenses/LICENSE-2.0
6+
7+
Unless required by applicable law or agreed to in writing, software distributed under
8+
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
9+
OF ANY KIND, either express or implied. See the License for the specific language
10+
governing permissions and limitations under the License.
11+
*/
12+
13+
export interface TelemetryConfig {
14+
enabled: boolean;
15+
projectId: string;
16+
endpoint: string;
17+
collection: {
18+
performance: boolean;
19+
interaction: boolean;
20+
accessibility: boolean;
21+
environment: boolean;
22+
sendInterval: number;
23+
batchSize: number;
24+
};
25+
privacy: {
26+
anonymize: boolean;
27+
includeUrls: boolean;
28+
retentionPeriod: number;
29+
};
30+
}
31+
32+
const defaultConfig: TelemetryConfig = {
33+
enabled: false,
34+
projectId: '',
35+
endpoint: '',
36+
collection: {
37+
performance: true,
38+
interaction: true,
39+
accessibility: true,
40+
environment: true,
41+
sendInterval: 60000,
42+
batchSize: 10,
43+
},
44+
privacy: {
45+
anonymize: true,
46+
includeUrls: false,
47+
retentionPeriod: 90,
48+
},
49+
};
50+
51+
export class TelemetryConfigManager {
52+
private static instance: TelemetryConfigManager;
53+
private config: TelemetryConfig;
54+
55+
private constructor() {
56+
this.config = { ...defaultConfig };
57+
}
58+
59+
static getInstance(): TelemetryConfigManager {
60+
if (!TelemetryConfigManager.instance) {
61+
TelemetryConfigManager.instance = new TelemetryConfigManager();
62+
}
63+
return TelemetryConfigManager.instance;
64+
}
65+
66+
getConfig(): TelemetryConfig {
67+
return { ...this.config };
68+
}
69+
70+
updateConfig(updates: Partial<TelemetryConfig>): void {
71+
this.config = { ...this.config, ...updates };
72+
}
73+
}

‎packages/theme/src/telemetry.ts

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
/*
2+
Copyright 2024 Adobe. All rights reserved.
3+
This file is licensed to you under the Apache License, Version 2.0 (the "License");
4+
you may not use this file except in compliance with the License. You may obtain a copy
5+
of the License at http://www.apache.org/licenses/LICENSE-2.0
6+
7+
Unless required by applicable law or agreed to in writing, software distributed under
8+
the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
9+
OF ANY KIND, either express or implied. See the License for the specific language
10+
governing permissions and limitations under the License.
11+
*/
12+
13+
export interface TelemetryData {
14+
componentName: string;
15+
timestamp: number;
16+
interaction?: {
17+
clicks?: number;
18+
hovers?: number;
19+
focusEvents?: number;
20+
keyboardEvents?: number;
21+
};
22+
performance?: {
23+
loadTime?: number;
24+
renderTime?: number;
25+
memoryUsage?: number;
26+
};
27+
accessibility?: {
28+
ariaAttributes?: Record<string, string>;
29+
role?: string;
30+
tabIndex?: number;
31+
};
32+
environment?: {
33+
browser?: string;
34+
os?: string;
35+
viewport?: {
36+
width: number;
37+
height: number;
38+
};
39+
pixelRatio?: number;
40+
language?: string;
41+
theme?: {
42+
color?: string;
43+
scale?: string;
44+
system?: boolean;
45+
};
46+
};
47+
}
48+
49+
export class TelemetryService {
50+
private static instance: TelemetryService;
51+
private data: TelemetryData[] = [];
52+
private listeners: ((data: TelemetryData) => void)[] = [];
53+
54+
private constructor() {}
55+
56+
static getInstance(): TelemetryService {
57+
if (!TelemetryService.instance) {
58+
TelemetryService.instance = new TelemetryService();
59+
}
60+
return TelemetryService.instance;
61+
}
62+
63+
trackComponentUsage(component: HTMLElement): void {
64+
const data: TelemetryData = {
65+
componentName: component.tagName.toLowerCase(),
66+
timestamp: Date.now(),
67+
environment: {
68+
browser: navigator.userAgent,
69+
os: navigator.platform,
70+
viewport: {
71+
width: window.innerWidth,
72+
height: window.innerHeight,
73+
},
74+
pixelRatio: window.devicePixelRatio,
75+
language: navigator.language,
76+
},
77+
};
78+
this.data.push(data);
79+
this.notifyListeners(data);
80+
}
81+
82+
addListener(listener: (data: TelemetryData) => void): void {
83+
this.listeners.push(listener);
84+
}
85+
86+
removeListener(listener: (data: TelemetryData) => void): void {
87+
this.listeners = this.listeners.filter((l) => l !== listener);
88+
}
89+
90+
getData(): TelemetryData[] {
91+
return [...this.data];
92+
}
93+
94+
clearData(): void {
95+
this.data = [];
96+
}
97+
98+
private notifyListeners(data: TelemetryData): void {
99+
this.listeners.forEach((listener) => listener(data));
100+
}
101+
}

‎tools/theme/TELEMETRY.md

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
# Spectrum Web Components Telemetry System
2+
3+
## Overview
4+
5+
The telemetry system in Spectrum Web Components (SWC) automatically collects usage data from components to help understand adoption, usage patterns, and potential issues. This data is collected anonymously and can be used to improve the library.
6+
7+
## Implementation Details
8+
9+
### Automatic Collection
10+
11+
- All components extending `SpectrumElement` automatically collect telemetry data
12+
- Data is collected when components are connected to the DOM
13+
- No additional code is needed in individual components
14+
15+
### Data Collected
16+
17+
1. **Component Usage**
18+
19+
- Component name
20+
- Timestamp
21+
- Theme settings (color, scale, system)
22+
- Environment info (browser, OS, viewport)
23+
24+
2. **Performance Metrics**
25+
26+
- Load time
27+
- Render time
28+
- Memory usage
29+
30+
3. **Accessibility**
31+
32+
- ARIA attributes
33+
- Role information
34+
- Tab index
35+
36+
4. **Interaction Data**
37+
- Click events
38+
- Hover events
39+
- Focus events
40+
- Keyboard events
41+
42+
## Accessing Telemetry Data
43+
44+
### In Development
45+
46+
```typescript
47+
import { TelemetryService } from '@spectrum-web-components/theme/src/telemetry.js';
48+
49+
// Get telemetry instance
50+
const telemetry = TelemetryService.getInstance();
51+
52+
// Get collected data
53+
const data = telemetry.getData();
54+
55+
// Clear collected data
56+
telemetry.clearData();
57+
58+
// Listen for new data
59+
telemetry.addListener((data) => {
60+
console.log('New telemetry data:', data);
61+
});
62+
```
63+
64+
### Using the Dashboard
65+
66+
The telemetry dashboard component (`sp-telemetry-dashboard`) provides a visual interface for viewing telemetry data:
67+
68+
```html
69+
<sp-telemetry-dashboard></sp-telemetry-dashboard>
70+
```
71+
72+
The dashboard shows:
73+
74+
- Component usage statistics
75+
- Theme distribution
76+
- Environment information
77+
- Performance metrics
78+
- Accessibility statistics
79+
80+
## Best Practices for SWC Team
81+
82+
### 1. Data Collection
83+
84+
- Keep telemetry collection lightweight
85+
- Only collect essential data
86+
- Respect user privacy settings
87+
- Document all collected metrics
88+
89+
### 2. Analysis
90+
91+
- Regularly review telemetry data
92+
- Look for usage patterns
93+
- Identify potential issues
94+
- Track component adoption
95+
96+
### 3. Privacy
97+
98+
- All data is collected anonymously
99+
- No personal information is collected
100+
- Users can opt-out via configuration
101+
- Data is stored locally by default
102+
103+
### 4. Configuration
104+
105+
The telemetry system can be configured through `TelemetryConfigManager`:
106+
107+
```typescript
108+
import { TelemetryConfigManager } from '@spectrum-web-components/theme/src/telemetry-config.js';
109+
110+
const config = TelemetryConfigManager.getInstance();
111+
112+
// Configure telemetry settings
113+
config.updateConfig({
114+
enabled: true,
115+
endpoint: 'https://your-telemetry-endpoint.com',
116+
collectPerformance: true,
117+
collectInteraction: true,
118+
collectAccessibility: true,
119+
privacy: {
120+
anonymizeData: true,
121+
retentionPeriod: 30, // days
122+
},
123+
});
124+
```
125+
126+
## Development Guidelines
127+
128+
### Adding New Metrics
129+
130+
1. Update the `TelemetryData` interface in `telemetry.ts`
131+
2. Add collection logic in `TelemetryService`
132+
3. Update the dashboard component if needed
133+
4. Document the new metric
134+
135+
### Testing
136+
137+
- Test telemetry collection in development
138+
- Verify data accuracy
139+
- Check performance impact
140+
- Ensure privacy compliance
141+
142+
### Deployment
143+
144+
- Enable telemetry in staging first
145+
- Monitor data collection
146+
- Verify dashboard functionality
147+
- Document any issues
148+
149+
## Troubleshooting
150+
151+
### Common Issues
152+
153+
1. **No Data Collection**
154+
155+
- Check if telemetry is enabled
156+
- Verify component inheritance
157+
- Check browser console for errors
158+
159+
2. **Dashboard Not Showing Data**
160+
161+
- Verify data collection
162+
- Check dashboard configuration
163+
- Clear and refresh data
164+
165+
3. **Performance Impact**
166+
- Monitor memory usage
167+
- Check collection frequency
168+
- Review collected metrics
169+
170+
## Future Improvements
171+
172+
- [ ] Add more detailed performance metrics
173+
- [ ] Implement data export functionality
174+
- [ ] Add custom metric collection
175+
- [ ] Create analytics dashboard
176+
- [ ] Add A/B testing support
177+
178+
## Contact
179+
180+
For questions or issues regarding the telemetry system, contact the SWC team or create an issue in the repository.

0 commit comments

Comments
 (0)