🌞 [Other]: PowerShell Telemetry Module for Azure Application Insights – Feature Specification

[MariusStorhaug]

Overview

This PowerShell telemetry module provides a configurable way to collect and send telemetry from PowerShell modules and GitHub Actions to Azure Application Insights. The key features include:

• Telemetry Collection: Capturing command usage, execution duration, errors, and environment details.
• Configurable Instrumentation Key: Users configure the key via stored variables, environment variables, or config files.
• Override and Context Integration: Users can override the key dynamically using the PowerShell Context module.
• Telemetry Opt-Out: Users can disable telemetry using environment variables or config settings.
• Efficient Performance: Supports asynchronous transmission and batching to minimize performance impact.
• Azure Integration: Uses Application Insights REST API for seamless data ingestion and analysis.

Instrumentation Key Handling

• Configuration Sources: The key is loaded from environment variables, config files, or the PowerShell Context module.
• Storage in Cleartext: The key is not a secret per Microsoft guidance, so no obfuscation or encryption is applied.
• Context Overrides: Users can override the key dynamically via the Context module.
• Security Considerations: The module ensures proper validation of the key format and prevents exposure in logs.

Azure Application Insights Integration

• Single vs. Multiple Instances: The module allows a single App Insights instance for all telemetry but supports separate keys if needed.
• Telemetry Source Differentiation: Identifies different sources using ai.cloud.role, properties, or tagging.
• Transmission Method: Uses Application Insights REST API to send structured JSON telemetry.
• Data Organization: Logs, metrics, and events are structured to allow efficient querying in App Insights.

Telemetry Data Collection & Transmission

PowerShell Modules

• Command Execution Events: Logs cmdlet execution, duration, and outcome.
• Usage Metrics: Tracks how often commands are used.
• Error Reporting: Captures exceptions and failure reasons while avoiding sensitive data.
• Environment Info: Includes OS, PowerShell version, and session details.
• Session/User Anonymization: Optionally generates unique session identifiers.

GitHub Actions

• Workflow Run Events: Captures workflow name, trigger type, and status.
• Job-Level Metrics: Records job duration and success/failure rates.
• Performance Metrics: Tracks execution times to detect bottlenecks.
• Environment Context: Captures runner OS, instance type, and related metadata.

Data Structure

Telemetry events are structured in JSON format with key properties such as:

{
  "name": "CmdletInvocation",
  "time": "2025-02-10T00:14:00.123Z",
  "iKey": "<InstrumentationKey GUID>",
  "properties": {
    "ModuleName": "MyModule",
    "CommandName": "Get-Foo",
    "Succeeded": true,
    "DurationMs": 142,
    "OS": "Windows 10.0.19045"
  }
}

• Uses baseType: EventData and includes relevant context for filtering and analysis.

Transmission Method

• Real-Time vs. Batching:
  • Sends telemetry immediately if low-frequency.
  • Batches multiple events to minimize HTTP requests.
  • Flushes remaining telemetry before process exit.
• Asynchronous Sending: Uses non-blocking requests to prevent slowdowns.
• Retries & Error Handling: Implements retry logic with backoff for network failures.

Security & Rate Limiting

Opt-Out Mechanism

• Environment Variable: POWERSHELL_TELEMETRY_OPTOUT=true disables telemetry.
• Config File Setting: "TelemetryEnabled": false prevents sending data.
• Context Override: Can disable telemetry for specific sessions.

Rate Limiting

• Max Events per Interval: Caps telemetry at configurable rates (e.g., 5 events/sec).
• Burst Handling: Allows short spikes but enforces sustained limits.
• Behavior on Limit Exceedance: Logs dropped events but prevents excessive network traffic.

Privacy & Security

• Data Anonymization: Ensures user-sensitive data is not transmitted.
• No Credential Logging: Prevents secrets from being included in telemetry.
• Secure HTTPS Transmission: All data is sent encrypted to Azure.

Configuration Options

• Instrumentation Key Management: Set via environment, config file, or context.
• Telemetry Content Control: Users can disable specific event types (e.g., error messages).
• Batching & Rate Limit Settings: Adjust frequency and payload sizes.
• Debug Logging: Enables verbose output for troubleshooting.

Best Practices

• Transparency & Documentation: Clearly communicate telemetry purpose and data collected.
• Minimal Performance Impact: Optimize for lightweight, efficient telemetry.
• Regular Review of Data: Ensure telemetry remains relevant and does not grow excessive.
• Future-Proofing: Support new Azure telemetry capabilities as they evolve.

This module provides a robust, configurable, and privacy-conscious telemetry solution for PowerShell modules and GitHub Actions, ensuring actionable insights with minimal impact.