Skip to content

Add Sentry PowerShell SDK integration for telemetry #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Draft
vaind wants to merge 15 commits into
base: main
Choose a base branch
from
Draft

Add Sentry PowerShell SDK integration for telemetry #19

vaind wants to merge 15 commits into from

Conversation

@vaind
Copy link
Contributor

@vaind vaind commented Nov 6, 2025 •
edited
Loading

Summary

Integrates sentry-powershell SDK (v0.4.0) to provide operational visibility into test infrastructure failures, device connection issues, and automation errors.

The Sentry module is bundled in the repository at vendor/Sentry/ to eliminate external dependencies and ensure consistent behavior across all environments.

Implementation Status:

  • ✅ Phase 1: Core Infrastructure (TrySentry module with bundled Sentry)
  • ✅ Phase 2: Module Integration (app-runner, sentry-api-client)
  • ✅ Phase 3: Error Reporting (simplified, no breadcrumbs or context data)
  • ✅ Phase 4: Documentation

Resolves #18

Changes

Core Infrastructure

Added utils/TrySentry.psm1 - Wrapper module for graceful Sentry integration:

  • Start-Sentry - Optional early initialization with context tags
  • Out-Sentry - Send errors/messages to Sentry
  • Add-SentryBreadcrumb - Add diagnostic breadcrumbs (exported but not used)
  • Edit-SentryScope - Modify scope (exported but not used internally)
  • Start-SentryTransaction - Start performance monitoring (exported but not used)

Features:

  • Bundled Sentry module - Loads from vendor/Sentry/ (no PSGallery dependency)
  • Graceful degradation if bundled module unavailable
  • Respects $env:SENTRY_DSN for override/disable
  • All failures are silent (Write-Debug only)
  • Module-qualified function names to avoid conflicts

Bundled Dependencies

Added vendor/Sentry/ - Sentry PowerShell module v0.4.0:

  • Downloaded from GitHub release
  • Size: ~1.6MB (PowerShell Core assemblies only)
  • Removed lib/net462/ - Windows PowerShell not supported
  • Includes net8.0 and net9.0 assemblies for PowerShell 7+

Added vendor/README.md:

  • Documents bundling rationale (reliability, consistency, offline support)
  • Update instructions for future Sentry module versions
  • PowerShell Core 7+ requirement

Module Integration

Modified:

  • app-runner/SentryAppRunner.psm1 - Auto-initialize telemetry on import
  • sentry-api-client/SentryApiClient.psm1 - Auto-initialize telemetry on import

Both modules automatically track module name, version, PowerShell version, OS as tags.

Error Handling

Enhanced app-runner/Private/ErrorHandling.ps1:

  • ErrorHandler::LogError() sends all errors to Sentry with:
    • Error ID, category, platform, session ID as tags
    • Full detailed message as event content
    • No context data (removed to prevent potential PII/sensitive data leakage)

Simplified approach:

  • No breadcrumbs (will use structured logging in future)
  • No scope modifications for context data
  • Tags only (error_id, category, platform, session_id)

Documentation

Updated root README.md:

  • Added comprehensive Telemetry section
  • Documented what data is collected
  • Explained how to disable telemetry ($env:SENTRY_DSN = $null)
  • Explained how to use custom Sentry project
  • Clarified DSN security (public keys, safe to expose)
  • Updated to reflect bundled module (no installation required)

Configuration

Default behavior:

  • Hardcoded DSN in utils/TrySentry.psm1 (single project for all telemetry)
  • Automatically initializes on module import
  • Loads bundled Sentry module from vendor/Sentry/

To use a custom Sentry project:

$env:SENTRY_DSN = 'https://your-key@o123.ingest.sentry.io/your-project'

To disable telemetry:

$env:SENTRY_DSN = $null  # or empty string

Testing

Telemetry works out of the box with bundled Sentry module:

Import-Module ./app-runner/SentryAppRunner.psd1
Import-Module ./sentry-api-client/SentryApiClient.psd1

All wrapper functions fail gracefully if bundled module is missing or fails to load.

Dependencies

Bundled: Sentry PowerShell module v0.4.0 in vendor/Sentry/

Key Commits

  1. 836c6f6 - Add TrySentry module with core wrapper functions
  2. 8c7d34b - Add performance monitoring support (transactions/spans)
  3. 2b89e52 - Integrate into app-runner and sentry-api-client modules
  4. 11657e4 - Integrate into error handling and add breadcrumbs
  5. 54d21bc - Add telemetry documentation to root README
  6. f0b520e - Enhance telemetry documentation
  7. ee60c38 - Use module-qualified names to eliminate warnings
  8. 4395b6c - Simplify telemetry by removing breadcrumbs and context data
  9. b7ae964 - Bundle Sentry PowerShell module to eliminate external dependency
  10. 7422614 - Add vendor README and remove Windows PowerShell assemblies

🤖 Generated with Claude Code

vaind and others added 15 commits November 6, 2025 12:04
@vaind @claude
feat: add TrySentry module for graceful Sentry telemetry integration
836c6f6 
Add wrapper module that provides graceful degradation when Sentry PowerShell
SDK is unavailable. This enables operational visibility into test infrastructure
failures without creating hard dependencies or breaking functionality when
Sentry is not installed.

Key features:
- Auto-loads Sentry module if available, fails silently if not
- Checks [Sentry.SentrySdk]::IsEnabled before initialization
- Respects $env:SENTRY_DSN for override/disable (empty = disabled)
- Caches initialization state to avoid repeated module import attempts
- Exports wrapper functions: TryStart-Sentry, TryOut-Sentry,
  TryAdd-SentryBreadcrumb, TryEdit-SentryScope

This is Phase 1 of implementation per issue #18.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind @claude
feat: add performance monitoring support to TrySentry module
8c7d34b 
Add TryStart-SentryTransaction wrapper to enable performance tracking
of critical operations like device connections, app deployments, and builds.

The transaction object supports creating child spans using the null-conditional
operator (?.) pattern, ensuring graceful degradation when Sentry is unavailable:

  $transaction = TryStart-SentryTransaction -Name "Connect" -Operation "device.connect"
  $span = $transaction?.StartChild("lock.acquire")
  $span?.Finish()
  $transaction?.Finish()

This enables identifying performance bottlenecks in test automation workflows.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind @claude
feat: integrate TrySentry telemetry into app-runner and sentry-api-cl…
2b89e52 
…ient modules

Auto-initialize Sentry telemetry on module import with module name and version
context. The initialization is fully optional and fails silently if:
- Sentry PowerShell SDK is not installed
- SENTRY_DSN environment variable is empty/null
- TrySentry module import fails

Both modules now automatically track operational errors and performance metrics
without requiring any code changes by consumers. Telemetry can be disabled by
setting $env:SENTRY_DSN to empty string or null.

This completes Phase 2 of implementation per issue #18.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind @claude
feat: integrate Sentry telemetry into error handling and critical ope…
11657e4 
…rations

Enhanced error handling and added diagnostic breadcrumbs throughout the codebase:

**Error Handling:**
- Modified ErrorHandler::LogError() to send all errors to Sentry with:
  - Error ID, category, platform, session ID as tags
  - Exception context as extra data
  - Full detailed message as event content

**Breadcrumb Integration:**

Connect-Device:
- Starting device connection
- Acquiring/acquired device lock
- Creating device provider
- Establishing/established connection

Invoke-DeviceApp:
- Starting application deployment
- Invoking application on device
- Application execution completed (with exit code)

Integration.TestUtils:
- EVENT_CAPTURED lines mismatch (with expected/found counts)
- Starting Sentry event polling (by ID or tag)
- Sentry event polling timed out (with last error)

All breadcrumbs include relevant context data (platform, executable, counts, etc.)
to provide diagnostic trail when errors occur. All integrations fail gracefully
when Sentry is unavailable.

This completes Phase 3 of implementation per issue #18.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind @claude
docs: add telemetry documentation to root README
54d21bc 
Add comprehensive Telemetry section documenting:
- What data is collected (errors, breadcrumbs, performance metrics)
- How to disable telemetry ($env:SENTRY_DSN = $null)
- How to use custom Sentry project
- DSN security explanation (public keys, safe to expose)
- Optional Sentry module dependency

Positioned before Requirements section for visibility. Emphasizes user control
and privacy while explaining operational benefits.

This completes Phase 4 of implementation per issue #18.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind
docs: enhance telemetry section in README for clarity and detail
f0b520e
@vaind @claude
refactor: use module-qualified names to eliminate unapproved verb war…
ee60c38 
…nings

Renamed TrySentry wrapper functions to use standard approved PowerShell verbs
and updated all call sites to use module-qualified names (TrySentry\*):

**Function renames:**
- TryStart-Sentry → Start-Sentry
- TryOut-Sentry → Out-Sentry
- TryAdd-SentryBreadcrumb → Add-SentryBreadcrumb
- TryEdit-SentryScope → Edit-SentryScope
- TryStart-SentryTransaction → Start-SentryTransaction

**Call site updates:**
- app-runner/SentryAppRunner.psm1: TrySentry\Start-Sentry
- sentry-api-client/SentryApiClient.psm1: TrySentry\Start-Sentry
- app-runner/Private/ErrorHandling.ps1: TrySentry\Out-Sentry, TrySentry\Edit-SentryScope
- app-runner/Public/Connect-Device.ps1: TrySentry\Add-SentryBreadcrumb (5 calls)
- app-runner/Public/Invoke-DeviceApp.ps1: TrySentry\Add-SentryBreadcrumb (3 calls)
- utils/Integration.TestUtils.psm1: TrySentry\Add-SentryBreadcrumb (3 calls)

Module-qualified names make it clear these are safe wrappers (TrySentry namespace)
while eliminating PowerShell warnings about unapproved verbs. Modules now load
silently without any warnings.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind @claude
refactor: simplify telemetry by removing breadcrumbs and context data
4395b6c 
Remove breadcrumb tracking from device operations and test utilities in favor of future structured logging implementation. Also fix SENTRY_DSN disable check to properly distinguish between unset (uses default) and explicitly disabled (empty string), and remove exception context data that could leak sensitive information.

Changes:
- Fix null-checking logic in TrySentry to use Test-Path for proper disable detection
- Remove all Add-SentryBreadcrumb calls from Connect-Device, Invoke-DeviceApp, and Integration.TestUtils
- Remove Edit-SentryScope block that added exception context as extra data
- Simplify error reporting to only include message and basic tags

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind @claude
feat: bundle Sentry PowerShell module to eliminate external dependency
b7ae964 
Bundle sentry-powershell v0.4.0 directly in the repository at vendor/Sentry to provide out-of-the-box telemetry without requiring manual installation from PSGallery. This ensures consistent behavior across all environments (CI, dev, offline) and eliminates potential installation failures.

Changes:
- Add bundled Sentry module v0.4.0 from GitHub release to vendor/Sentry
- Update TrySentry.psm1 to load bundled module instead of system-installed
- Update README to reflect that Sentry is now bundled and ready to use
- Remove PSGallery installation instructions

The bundled module includes .NET assemblies for net462, net8.0, and net9.0 frameworks (~4.2MB total).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind @claude
docs: add vendor README and remove Windows PowerShell assemblies
7422614 
Add documentation explaining why Sentry module is bundled and how to update it. Remove lib/net462 assemblies since this toolkit requires PowerShell Core 7+ (not Windows PowerShell 5.1).

Changes:
- Add vendor/README.md documenting bundling rationale and update process
- Remove vendor/Sentry/lib/net462/ directory (~2.6MB of Windows PowerShell assemblies)
- Document PowerShell Core 7+ requirement
- Update size estimate to 1.6MB (down from 4.2MB)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind
Merge branch 'main' into feat/sentry-powershell-integration
e29de10
@vaind @claude
refactor: simplify TrySentry import logic
593b68a 
Remove unnecessary conditional check when importing TrySentry module. Since TrySentry.psm1 is part of this repository (not an external dependency), we can import it directly. The try-catch handles any import failures, and TrySentry itself provides graceful degradation if the bundled Sentry module is unavailable.

Changes:
- Remove `if (Get-Module -Name TrySentry)` conditional check
- Change ErrorAction from SilentlyContinue to Stop for clearer error handling
- Update comment to remove "optional" - telemetry is always initialized
- Update debug message from "skipped" to "failed" for accuracy

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind @claude
refactor: remove unused ErrorHandler class
03cba48 
Remove ErrorHandling.ps1 which defines an ErrorHandler class that is never used anywhere in the codebase. The file was being dot-sourced via wildcard import but no code calls [ErrorHandler]::LogError().

The codebase uses standard PowerShell error handling (throw/catch) throughout, making this abstraction unnecessary. If we need centralized error reporting to Sentry in the future, we can use PowerShell's built-in error stream hooks instead.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
@vaind
refactor: change debug messages to include type context and improve w…
9a9848f 
…arning output for Sentry initialization
@vaind @claude
refactor: change telemetry to opt-in with module-specific DSNs
549ae7c 
- Remove hardcoded default DSN from TrySentry.psm1
- Add -Dsn parameter to Start-Sentry function
- Require explicit SENTRY_APP_RUNNER_DSN for app-runner module
- Require explicit SENTRY_API_CLIENT_DSN for sentry-api-client module
- Update README to reflect opt-in telemetry behavior
- Change initialization failure from Write-Warning to Write-Debug

Telemetry is now disabled by default and must be explicitly enabled
by setting the appropriate environment variable for each module.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Add Sentry PowerShell SDK integration for telemetry

2 participants

@vaind