gsadmin/AutopilotMonitor
1
0
Fork 0
mirror of https://github.com/okieselbach/AutopilotMonitor.git synced 2026-10-24 04:32:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Simplify README and remove outdated docs

Browse Source 
Replace verbose README with a concise overview and link to the
official documentation at autopilotmonitor.com/docs. Remove
CONTRIBUTING.md, QUICKSTART.md, docs/architecture.md, and
docs/getting-started.md as the website docs supersede them.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Oliver Kieselbach
2026-02-23 21:52:11 +01:00
parent cbddf409d5
commit fd6ca05ebc
5 changed files with 6 additions and 1217 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
-251
View File
@@ -1,251 +0,0 @@
# Contributing to Autopilot Monitor
Thank you for your interest in contributing to Autopilot Monitor! This document provides guidelines and instructions for contributing.
## Code of Conduct
Be respectful, professional, and constructive. We're all here to make Autopilot deployments better.
## How Can I Contribute?
### Reporting Bugs
Before submitting a bug report:
1. Check existing GitHub issues
2. Verify you're using the latest version
3. Collect relevant logs and error messages
**Good Bug Report Includes**:
- Clear description of the issue
- Steps to reproduce
- Expected vs actual behavior
- Environment details (OS version, .NET version, etc.)
- Relevant log excerpts
- Screenshots if applicable
### Suggesting Features
We love feature ideas! Before submitting:
1. Check if it's already been suggested
2. Consider if it fits the project scope
3. Think about implementation complexity
**Good Feature Request Includes**:
- Clear description of the feature
- Use case / problem it solves
- Proposed solution (if you have one)
- Alternative approaches considered
### Contributing Code
#### Development Setup
1. Fork the repository
2. Clone your fork
3. Follow the [Getting Started Guide](docs/getting-started.md)
4. Create a feature branch: `git checkout -b feature/my-feature`
#### Coding Standards
**C# / .NET**
- Follow Microsoft C# coding conventions
- Use meaningful variable and method names
- Add XML documentation comments for public APIs
- Keep methods focused and small (<50 lines preferred)
- Use async/await properly (don't block)
**TypeScript / React**
- Use TypeScript for type safety
- Follow React best practices (hooks, functional components)
- Use meaningful component and variable names
- Keep components small and focused
- Extract reusable logic into custom hooks
**PowerShell**
- Use approved verbs (Get-, Set-, New-, etc.)
- Add comment-based help for scripts
- Use meaningful parameter names
- Include error handling
#### Code Review Process
1. Ensure all tests pass
2. Update documentation if needed
3. Submit a pull request with:
- Clear title and description
- Reference to related issues
- Screenshots (if UI changes)
4. Address review feedback
5. Squash commits before merge (if requested)
### Contributing Rules
The **rule engine** (Phase 2+) is designed to be community-driven. You can contribute rules to help diagnose common issues.
#### Rule Structure
Rules are YAML files in the `rules/` directory:
```yaml
id: NET-001
title: "Proxy Authentication Required"
severity: high
category: network
version: 1.0
author: "Your Name"
description: |
Detects when a proxy requires authentication but SYSTEM account cannot authenticate.
conditions:
- signal: "event_407_detected"
source: "windows_events"
provider: "Microsoft-Windows-WinHttp"
event_id: 407
minimum_occurrences: 1
evidence_selectors:
- type: "log_lines"
source: "ime_log"
pattern: "proxy|407|authentication"
context_lines: 3
explanation: |
The device is behind a proxy that requires authentication, but the SYSTEM
account (used during enrollment) cannot authenticate.
remediation:
- "Configure proxy bypass for *.manage.microsoft.com"
- "Configure proxy bypass for *.microsoftonline.com"
- "Use PAC file with proper exclusions"
related_docs:
- "https://learn.microsoft.com/en-us/mem/intune/enrollment/enrollment-autopilot"
confidence_scoring:
base: 50
factors:
- signal: "winhttp_proxy_configured"
weight: 20
- signal: "enrollment_stalled_at_mdm"
weight: 30
```
#### Submitting Rules
1. Create a new YAML file in the appropriate `rules/` subdirectory
2. Follow the schema above
3. Test your rule against sample data
4. Submit a PR with:
- The rule file
- Test data (anonymized)
- Explanation of how to trigger this condition
## Project Structure
```
Autopilot-Monitor/
├── src/
│ ├── Agent/ # Windows monitoring agent
│ ├── Backend/ # Azure Functions API
│ ├── Shared/ # Common models/contracts
│ └── Web/ # Next.js web UI
├── scripts/
│ ├── Bootstrap/ # Intune deployment scripts
│ └── Deployment/ # Azure deployment scripts
├── rules/ # Community rule definitions
├── docs/ # Documentation
└── tests/ # Tests (to be added)
```
## Testing Guidelines
### Unit Tests
- Test core logic in isolation
- Mock external dependencies
- Aim for >80% code coverage on critical paths
### Integration Tests
- Test API endpoints with real Azure Storage Emulator
- Verify agent can upload to Functions
- Test error handling and retries
### End-to-End Tests
- Test full enrollment simulation (when feasible)
- Verify UI displays data correctly
- Test troubleshooting workflows
## Documentation
When adding features, please update:
- **README.md** - If it affects setup or high-level description
- **docs/getting-started.md** - If it affects the getting started process
- **docs/architecture.md** - If it changes architecture
- **Inline code comments** - For complex logic
- **XML docs** - For public APIs
## Git Workflow
We use a simplified Git workflow:
1. **main** branch - Stable, production-ready code
2. **feature/** branches - New features in development
3. **bugfix/** branches - Bug fixes
4. **hotfix/** branches - Critical production fixes
### Commit Messages
Use clear, descriptive commit messages:
```
[Component] Short description
Longer explanation if needed.
Fixes #123
```
Examples:
- `[Agent] Add support for pre-provisioning scenarios`
- `[Web] Implement session detail page with timeline`
- `[Functions] Fix race condition in event ingestion`
- `[Docs] Update architecture diagram`
## Release Process
Releases follow semantic versioning (MAJOR.MINOR.PATCH):
- **MAJOR**: Breaking changes
- **MINOR**: New features (backwards compatible)
- **PATCH**: Bug fixes
### Release Checklist
- [ ] All tests pass
- [ ] Documentation updated
- [ ] CHANGELOG.md updated
- [ ] Version numbers incremented
- [ ] Tag created: `vX.Y.Z`
- [ ] GitHub release published
- [ ] Deployment artifacts published
## Getting Help
- **Questions**: Open a GitHub Discussion
- **Bugs**: Open a GitHub Issue
- **Feature Ideas**: Open a GitHub Issue with "enhancement" label
- **Security Issues**: Email security@yourcompany.com (do NOT open public issue)
## Recognition
Contributors will be:
- Listed in CONTRIBUTORS.md
- Credited in release notes
- Mentioned in documentation for significant contributions
## License
By contributing, you agree that your contributions will be licensed under the MIT License.
## Thank You!
Your contributions make Autopilot Monitor better for everyone. Thank you for taking the time to contribute!
QUICKSTART.md
-183
View File
@@ -1,183 +0,0 @@
# Quick Start Guide
Get Autopilot Monitor running in 10 minutes!
## Prerequisites Check
Before starting, ensure you have:
- [ ] Windows 10/11
- [ ] .NET Framework 4.8 SDK
- [ ] .NET 8 SDK
- [ ] Node.js 18+
- [ ] Visual Studio 2022 or VS Code
Verify installations:
```bash
dotnet --version # Should show 8.x or higher
node --version # Should show v18.x or higher
```
## Step 1: Build the .NET Projects (2 minutes)
```bash
# Open a terminal in the project root
cd C:\Code\GitHubRepos\Autopilot-Monitor
# Restore all packages
dotnet restore
# Build everything
dotnet build
```
Expected output: `Build succeeded`
## Step 2: Install Azure Storage Emulator (2 minutes)
### Option A: Azurite (Recommended)
```bash
npm install -g azurite
# Start Azurite
azurite --silent --location c:\azurite
```
### Option B: Azure Storage Emulator
If you have the legacy Azure Storage Emulator installed, start it:
```bash
AzureStorageEmulator.exe start
```
## Step 3: Start the Backend API (2 minutes)
Open a new terminal:
```bash
cd src\Backend\AutopilotMonitor.Functions
# Start Azure Functions
func start
```
Expected output:
```
Azure Functions Core Tools
...
Functions:
IngestEvents: [POST] http://localhost:7071/api/events/ingest
RegisterSession: [POST] http://localhost:7071/api/sessions/register
```
## Step 4: Start the Web UI (3 minutes)
Open another terminal:
```bash
cd src\Web\autopilot-monitor-web
# Install dependencies (first time only)
npm install
# Copy environment template
copy .env.local.template .env.local
# Start development server
npm run dev
```
Expected output: `Ready on http://localhost:3000`
## Step 5: Test the Agent (2 minutes)
Open PowerShell **as Administrator**:
```powershell
cd src\Agent\AutopilotMonitor.Agent\bin\Debug\net48
# Run in console mode
.\AutopilotMonitor.Agent.exe --console
```
Expected output:
```
Autopilot Monitor Agent - Console Mode
======================================
Session ID: <some-guid>
API URL: http://localhost:7071
Log Directory: C:\ProgramData\AutopilotMonitor\Logs
Agent is running. Press Enter to stop...
```
## Verify It's Working
1. **Check the Agent Console** - Should show "Agent started" event
2. **Check the Functions Console** - Should show incoming requests
3. **Open Browser** - Navigate to http://localhost:3000
4. **View Dashboard** - You should see the Autopilot Monitor homepage
## What's Next?
### Explore the Code
- [Agent Code](src/Agent/AutopilotMonitor.Agent.Core/) - Monitoring logic
- [Backend API](src/Backend/AutopilotMonitor.Functions/) - Azure Functions
- [Web UI](src/Web/autopilot-monitor-web/) - Next.js dashboard
### Read Documentation
- [Getting Started Guide](docs/getting-started.md) - Detailed setup
- [Architecture Overview](docs/architecture.md) - How it all works
- [Contributing Guide](CONTRIBUTING.md) - How to contribute
### Try It Out
1. Modify the agent to emit custom events
2. Add a new API endpoint
3. Create a new page in the web UI
4. Write a rule for the rule engine (Phase 2)
## Troubleshooting
### Agent won't start
- Run as Administrator
- Check .NET Framework 4.8 is installed
- View logs in `C:\ProgramData\AutopilotMonitor\Logs\`
### Functions won't start
- Ensure Azurite/Storage Emulator is running
- Check `local.settings.json` exists
- Install Azure Functions Core Tools v4
### Web UI shows errors
- Run `npm install` again
- Check `.env.local` exists
- Verify Functions are running on port 7071
### Can't connect to API
- Check Windows Firewall
- Verify Functions console shows the correct URLs
- Try `curl http://localhost:7071/api/sessions/register`
## Next Development Steps
1. **Phase 1 Completion**
- Implement Azure Table Storage integration
- Add real-time session monitoring
- Create session detail page
2. **Phase 2: Intelligence**
- Build rule engine
- Add diagnosis panel
- Implement troubleshooting bundles
3. **Phase 3: Production**
- Deploy to Azure
- Configure Intune deployment
- Set up monitoring and alerts
## Getting Help
- Check [README.md](README.md) for overview
- Read [docs/getting-started.md](docs/getting-started.md) for details
- Open an issue on GitHub
- Review the code - it's well-commented!
---
**You're ready to go!** Start exploring and building. 🚀
README.md
+6 -148
View File
@@ -6,157 +6,15 @@ Advanced monitoring and troubleshooting solution for Windows Autopilot deploymen
Autopilot Monitor provides real-time tracking, intelligent diagnostics, and automated troubleshooting for Windows Autopilot enrollment processes. It consists of:
- **Bootstrap Script** - PowerShell script deployed via Intune that starts monitoring early in the enrollment process
- **Monitoring Agent** - Lightweight .NET Windows Service that collects telemetry and evidence
- **Backend API** - Azure Functions-based ingestion and processing pipeline
- **Web Dashboard** - Next.js application for real-time monitoring and fleet analytics
## Architecture
```
Device Side Azure Backend Web UI
┌──────────────┐ ┌──────────────┐ ┌──────────┐
│ Bootstrap │──deploys──▶ │ │ │ │
│ Script │ │ Azure │◀───────────▶ │ Next.js │
└──────┬───────┘ │ Functions │ │ Web App │
│ │ │ │ │
▼ │ • Ingest │ └──────────┘
┌──────────────┐ │ • Store │
│ Monitoring │──telemetry──▶ │ • Analyze │
│ Agent │ (mTLS) │ │
└──────────────┘ └──────┬───────┘
│
▼
┌──────────────┐
│ Azure Table │
│ Azure Blob │
│ Azure SQL │
└──────────────┘
```
## Project Structure
```
Autopilot-Monitor/
├── src/
│ ├── Agent/ # .NET monitoring agent
│ │ ├── AutopilotMonitor.Agent/ # Windows Service host
│ │ └── AutopilotMonitor.Agent.Core/ # Core monitoring logic
│ ├── Backend/ # Azure Functions
│ │ └── AutopilotMonitor.Functions/
│ ├── Shared/ # Shared models/contracts
│ │ └── AutopilotMonitor.Shared/
│ └── Web/ # Frontend
│ └── autopilot-monitor-web/
├── scripts/
│ ├── Bootstrap/ # Intune deployment scripts
│ └── Deployment/ # Azure deployment scripts
├── rules/ # YAML rule definitions
└── docs/ # Documentation
```
## Phase 1 Goals (Current)
- [x] Project structure setup
- [ ] Bootstrap PowerShell script
- [ ] Basic .NET agent with log tailing
- [ ] Azure Functions ingestion API
- [ ] Session registration and event storage
- [ ] Minimal web UI (session list, timeline)
## Getting Started
### Prerequisites
- .NET Framework 4.8 SDK (for Agent)
- .NET 8 SDK (for Azure Functions)
- Node.js 18+ (for Web UI)
- Azure subscription
- Visual Studio 2022 or VS Code
### Development Setup
1. **Clone and restore packages**
```bash
git clone <your-repo>
cd Autopilot-Monitor
dotnet restore
```
2. **Set up local Azure Functions**
```bash
cd src/Backend/AutopilotMonitor.Functions
cp local.settings.json.template local.settings.json
# Edit local.settings.json with your Azure Storage connection string
```
3. **Set up web frontend**
```bash
cd src/Web/autopilot-monitor-web
npm install
cp .env.local.template .env.local
# Edit .env.local with your API endpoint
```
4. **Build the agent**
```bash
cd src/Agent/AutopilotMonitor.Agent
dotnet build
```
### Running Locally
1. **Start Azure Functions** (in one terminal)
```bash
cd src/Backend/AutopilotMonitor.Functions
func start
```
2. **Start Web UI** (in another terminal)
```bash
cd src/Web/autopilot-monitor-web
npm run dev
```
3. **Test agent** (as Administrator)
```bash
cd src/Agent/AutopilotMonitor.Agent/bin/Debug
.\AutopilotMonitor.Agent.exe --console
```
- **Bootstrap Script** — PowerShell script deployed via Intune that starts monitoring early in the enrollment process
- **Monitoring Agent** — Lightweight .NET application that collects telemetry and evidence during enrollment
- **Backend API** — Azure Functions-based ingestion and processing pipeline
- **Web Dashboard** — Next.js application for real-time monitoring and fleet analytics
## Documentation
- [Architecture Overview](docs/architecture.md)
- [Agent Development](docs/agent-development.md)
- [Rule Engine](docs/rule-engine.md)
- [Deployment Guide](docs/deployment.md)
## Contributing
We welcome community contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
Full documentation is available at **[autopilotmonitor.com/docs](https://www.autopilotmonitor.com/docs)**
## License
MIT License - see [LICENSE](LICENSE) for details
## Roadmap
### Phase 1: Foundation (Current)
- Bootstrap and basic agent
- Simple ingestion pipeline
- Minimal UI
### Phase 2: Intelligence
- Rule engine
- Diagnosis panel
- Troubleshooting bundles
### Phase 3: Polish
- Fleet dashboard
- User-facing portal
- Multi-tenant support
### Phase 4: Advanced
- Pre-provisioning support
- Custom rule authoring
- Integration APIs
MIT License — see [LICENSE](LICENSE) for details
docs/architecture.md
-389
View File
@@ -1,389 +0,0 @@
# Architecture Overview
This document describes the technical architecture of Autopilot Monitor.
## High-Level Architecture
Autopilot Monitor consists of four main components:
```
┌─────────────────────────────────────────────────────────────────────────┐
│ DEVICE SIDE │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌──────────────────────────────────────────┐ │
│ │ Bootstrap.ps1 │────▶│ Monitoring Agent (.NET 4.8 Service) │ │
│ │ (Intune Script) │ │ │ │
│ │ │ │ • Log Watchers │ │
│ │ • Deploy agent │ │ • Event Collectors │ │
│ │ • Create session │ │ • Performance Monitors │ │
│ │ • Set correlation│ │ • Upload Manager │ │
│ └──────────────────┘ └─────────────┬────────────────────────────┘ │
│ │ │
└─────────────────────────────────────────┼───────────────────────────────┘
│ HTTPS (mTLS)
▼
┌─────────────────────────────────────────────────────────────────────────┐
│ AZURE BACKEND │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────────┐ │
│ │ Azure Functions (.NET 8 Isolated) │ │
│ │ │ │
│ │ /api/sessions/register │ /api/events/ingest │ /api/bundles/* │ │
│ └────────────────┬────────────────────┬──────────────────┬───────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ Azure Table │ │ Azure Table │ │ Azure Blob │ │
│ │ (Sessions) │ │ (Events) │ │ (Bundles/Logs) │ │
│ └─────────────────────┘ └──────────────────┘ └──────────────────┘ │
│ │
│ ┌────────────────────────┐ ┌───────────────────────────┐ │
│ │ Azure SignalR Service │──────────▶│ Next.js Web App │ │
│ │ (Real-time updates) │ │ (Static Web App) │ │
│ └────────────────────────┘ └───────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
```
## Component Details
### 1. Bootstrap Script (PowerShell)
**Purpose**: Deploy and configure the monitoring agent early in Autopilot enrollment.
**Responsibilities**:
- Generate unique session ID
- Collect device information
- Store configuration in registry
- Install/start monitoring agent
- Register session with backend
**Deployment**: Intune PowerShell Script (required, runs in Device ESP)
**Key Files**:
- [Install-AutopilotMonitor.ps1](../scripts/Bootstrap/Install-AutopilotMonitor.ps1)
### 2. Monitoring Agent (.NET Framework 4.8)
**Purpose**: Continuously monitor enrollment progress and collect telemetry.
**Architecture**:
```
AutopilotMonitor.Agent (Exe)
├── Program.cs (Entry point, console or service mode)
└── AutopilotMonitorService.cs (Windows Service wrapper)
│
└── AutopilotMonitor.Agent.Core (Library)
├── Monitoring/
│ ├── MonitoringService.cs (Main orchestrator)
│ ├── LogWatcher.cs (Tail IME logs)
│ ├── EventMonitor.cs (Watch Windows Event Log)
│ └── PerformanceMonitor.cs (CPU, memory, disk)
│
├── Storage/
│ └── EventSpool.cs (Offline queue)
│
├── Api/
│ └── BackendApiClient.cs (HTTP client for API calls)
│
├── Configuration/
│ └── AgentConfiguration.cs (Settings)
│
└── Logging/
└── AgentLogger.cs (Simple file logger)
```
**Key Features**:
- Runs as Windows Service (LocalSystem account)
- Offline spool for resilient upload
- Batched uploads (configurable interval)
- Exponential backoff on failures
- Low memory footprint (<50MB)
**Data Flow**:
1. Watchers detect events (logs, event log, performance)
2. Events normalized into `EnrollmentEvent` objects
3. Events added to local spool (file-based queue)
4. Periodic upload timer sends batches to backend
5. On success, events removed from spool
**Key Files**:
- [MonitoringService.cs](../src/Agent/AutopilotMonitor.Agent.Core/Monitoring/MonitoringService.cs)
- [EventSpool.cs](../src/Agent/AutopilotMonitor.Agent.Core/Storage/EventSpool.cs)
- [BackendApiClient.cs](../src/Agent/AutopilotMonitor.Agent.Core/Api/BackendApiClient.cs)
### 3. Backend API (Azure Functions)
**Purpose**: Ingest telemetry, store data, and serve web UI.
**Functions**:
#### RegisterSession
- **Route**: `POST /api/sessions/register`
- **Purpose**: Register a new enrollment session
- **Input**: `SessionRegistration` (device info, session ID)
- **Output**: `RegisterSessionResponse` (success, registered timestamp)
- **Storage**: Azure Table Storage (`sessions` table)
#### IngestEvents
- **Route**: `POST /api/events/ingest`
- **Purpose**: Receive batched events from agents
- **Input**: `IngestEventsRequest` (session ID, list of events)
- **Output**: `IngestEventsResponse` (events processed count)
- **Storage**: Azure Table Storage (`events` table)
- **Features**:
- Compression support (gzip)
- Batch processing
- Deduplication (by event ID)
#### UploadBundle
- **Route**: `POST /api/bundles/upload`
- **Purpose**: Get SAS URL for uploading troubleshooting bundle
- **Input**: `UploadBundleRequest` (session ID, file name)
- **Output**: `UploadBundleResponse` (SAS URL, expiry)
- **Storage**: Azure Blob Storage (`bundles` container)
**Authentication** (Future):
- Phase 1: Function key authentication
- Phase 2+: Client certificate (mTLS) using Intune MDM cert
**Key Files**:
- [RegisterSessionFunction.cs](../src/Backend/AutopilotMonitor.Functions/Functions/RegisterSessionFunction.cs)
- [IngestEventsFunction.cs](../src/Backend/AutopilotMonitor.Functions/Functions/IngestEventsFunction.cs)
### 4. Web Dashboard (Next.js)
**Purpose**: Real-time monitoring and troubleshooting UI.
**Technology Stack**:
- Next.js 15 (React 19)
- TypeScript
- Tailwind CSS
- Azure Static Web Apps (deployment)
**Key Pages** (Planned):
```
/ (Dashboard)
├── Active sessions grid
├── Fleet health metrics
└── Recent failures
/sessions/[id] (Session Detail)
├── Phase timeline
├── Event stream
├── Diagnosis panel
└── Download bundle
/sessions (Session List)
├── Filterable table
├── Search by serial/device name
└── Status indicators
/fleet (Fleet Analytics)
├── Success rate trends
├── Failure reason distribution
├── Model/OS breakdown
└── App install leaderboard
```
**Key Files**:
- [app/page.tsx](../src/Web/autopilot-monitor-web/app/page.tsx) (Dashboard)
- [app/layout.tsx](../src/Web/autopilot-monitor-web/app/layout.tsx) (Root layout)
### 5. Shared Library
**Purpose**: Common models and constants across all .NET projects.
**Key Models**:
- `EnrollmentEvent` - Single telemetry event
- `EnrollmentPhase` - Enrollment phase enumeration
- `SessionRegistration` - Device and session info
- `SessionSummary` - Session overview for UI
- `ApiModels` - Request/response contracts
**Key Files**:
- [Models/](../src/Shared/AutopilotMonitor.Shared/Models/)
- [Constants.cs](../src/Shared/AutopilotMonitor.Shared/Constants.cs)
## Data Models
### Azure Table Storage Schema
#### Sessions Table
| Property | Type | Description |
|----------|------|-------------|
| PartitionKey | string | `{TenantId}` |
| RowKey | string | `{SessionId}` |
| SerialNumber | string | Device serial number |
| Manufacturer | string | Device manufacturer |
| Model | string | Device model |
| DeviceName | string | Computer name |
| StartedAt | DateTime | Enrollment start time (UTC) |
| CompletedAt | DateTime? | Enrollment end time (UTC) |
| CurrentPhase | int | Current enrollment phase |
| Status | string | InProgress, Succeeded, Failed |
| EventCount | int | Total events received |
#### Events Table
| Property | Type | Description |
|----------|------|-------------|
| PartitionKey | string | `{TenantId}_{SessionId}` |
| RowKey | string | `{Timestamp}_{Sequence}` |
| EventId | string | Unique event identifier (GUID) |
| EventType | string | Type of event |
| Severity | int | Debug, Info, Warning, Error, Critical |
| Source | string | Where the event originated |
| Phase | int | Phase during which event occurred |
| Message | string | Human-readable message |
| Data | string | JSON-serialized additional data |
### Azure Blob Storage Structure
```
bundles/
{tenant-id}/
{session-id}/
troubleshooting-bundle.zip
logs/
agent.log
ime.log
events/
events.json
diagnostics/
dsregcmd.txt
network.txt
screenshots/
{tenant-id}/
{session-id}/
{timestamp}.jpg
```
## Security Architecture
### Phase 1 (Current)
- Function key authentication (keys in URL)
- No encryption at rest (using Azure defaults)
- HTTPS for transport
### Phase 2+ (Planned)
- Client certificate authentication (mTLS)
- Leverage Intune MDM device certificate
- No secrets on device
- Per-device authentication
- Azure AD authentication for web UI
- Multi-tenant isolation
- Encryption at rest (Azure Storage encryption)
- PII redaction policies
## Scalability Considerations
### Current Capacity (Phase 1)
- ~1,000 devices/month: ~$15/month Azure cost
- ~10,000 devices/month: ~$50-100/month Azure cost
### Storage Scaling
**Azure Table Storage**:
- Massively scalable (billions of entities)
- Auto-sharding by PartitionKey
- PartitionKey strategy: `{TenantId}` for sessions, `{TenantId}_{SessionId}` for events
- Supports 20,000 entities/sec per table
**Azure Blob Storage**:
- Unlimited storage
- Auto-tiering (Hot → Cool → Archive)
- Lifecycle policies for cost optimization
### Compute Scaling
**Azure Functions**:
- Consumption plan: Auto-scale to demand
- Isolated worker process model (better performance)
- Can handle 1000s of concurrent requests
**Web UI (Static Web Apps)**:
- Global CDN distribution
- Scales automatically
- Near-zero cost for read operations
## Monitoring and Observability
### Application Insights Integration
All components log to Azure Application Insights:
- **Agent**: Custom telemetry via API
- **Functions**: Built-in integration
- **Web**: Custom events and page views
### Metrics to Track
- Event ingestion rate (events/sec)
- API response times (p50, p95, p99)
- Failed uploads (count, reasons)
- Storage utilization (GB, transactions)
- Active sessions (count)
- Session success rate (%)
## Cost Optimization Strategies
1. **Use Azure Table Storage** instead of Cosmos DB (99% cheaper)
2. **Batch events** before upload (reduce transactions)
3. **Compress payloads** (reduce bandwidth)
4. **Lifecycle policies** for blob storage (hot → cool → archive)
5. **Summarize aggressively** (don't store every raw log line)
6. **Cache static content** (CDN for web UI)
7. **Use consumption plans** (pay per use, not reserved capacity)
## Future Architecture Enhancements
### Phase 2: Intelligence
- Rule engine (YAML-based, server-side evaluation)
- Real-time SignalR for live updates
- Troubleshooting bundle generation
### Phase 3: Advanced
- Pre-provisioning support
- Custom rule authoring UI
- REST API for integrations
- Webhook notifications
- Teams/Slack integration
### Phase 4: Enterprise
- Multi-tenant SaaS model
- Tenant-level isolation
- RBAC and permissions
- Audit logging
- Compliance controls (GDPR, etc.)
## Development Best Practices
### Code Organization
- Keep shared models in `AutopilotMonitor.Shared`
- Agent logic in `AutopilotMonitor.Agent.Core` (testable)
- Thin wrappers for service/console in `AutopilotMonitor.Agent`
- Stateless Azure Functions (no local state)
### Error Handling
- Agent: Never crash, always spool locally
- Functions: Return proper HTTP status codes
- Web: Graceful degradation, show cached data
### Testing
- Unit tests for core logic
- Integration tests for API endpoints
- End-to-end tests for critical flows
- Load testing for scalability validation
### Deployment
- CI/CD with GitHub Actions
- Separate environments (dev, staging, prod)
- Infrastructure as Code (Bicep/ARM templates)
- Automated rollback on failures
docs/getting-started.md
-246
View File
@@ -1,246 +0,0 @@
# Getting Started with Autopilot Monitor
This guide will help you set up and run Autopilot Monitor locally for development and testing.
## Prerequisites
### Required
- Windows 10/11 (for agent development and testing)
- .NET Framework 4.8 SDK
- .NET 8 SDK
- Visual Studio 2022 or VS Code with C# extensions
- Node.js 18+ and npm
- Azure Storage Emulator or Azurite (for local storage)
- Azure Functions Core Tools v4
### Optional
- Git
- PowerShell 5.1 or later
- Microsoft Intune tenant (for production deployment)
## Quick Start (5 Minutes)
### 1. Clone and Build
```bash
# Clone the repository
git clone <your-repo-url>
cd Autopilot-Monitor
# Restore and build all .NET projects
dotnet restore
dotnet build
```
### 2. Start Local Storage
Install and start Azurite (Azure Storage Emulator):
```bash
npm install -g azurite
azurite --silent --location c:\azurite --debug c:\azurite\debug.log
```
Or use the Azure Storage Emulator if you have it installed.
### 3. Start Azure Functions Backend
```bash
cd src/Backend/AutopilotMonitor.Functions
func start
```
The API will be available at `http://localhost:7071`
### 4. Start Web UI
```bash
cd src/Web/autopilot-monitor-web
# Install dependencies (first time only)
npm install
# Copy environment template
cp .env.local.template .env.local
# Start development server
npm run dev
```
The web UI will be available at `http://localhost:3000`
### 5. Test the Agent
Open a new PowerShell window **as Administrator**:
```powershell
cd src/Agent/AutopilotMonitor.Agent/bin/Debug/net48
.\AutopilotMonitor.Agent.exe --console
```
You should see the agent start and begin sending telemetry to the backend.
## Detailed Setup
### Backend Configuration
The Azure Functions use `local.settings.json` for configuration. This file is created from the template:
```json
{
"IsEncrypted": false,
"Values": {
"AzureWebJobsStorage": "UseDevelopmentStorage=true",
"FUNCTIONS_WORKER_RUNTIME": "dotnet-isolated",
"AzureTableStorageConnectionString": "UseDevelopmentStorage=true",
"AzureBlobStorageConnectionString": "UseDevelopmentStorage=true"
}
}
```
For production, replace `UseDevelopmentStorage=true` with your Azure Storage connection strings.
### Agent Configuration
The agent reads configuration from the Windows Registry (set by the bootstrap script) or falls back to defaults. For testing, you can modify [Program.cs](../src/Agent/AutopilotMonitor.Agent/Program.cs):
```csharp
return new AgentConfiguration
{
ApiBaseUrl = "http://localhost:7071",
SessionId = Guid.NewGuid().ToString(),
TenantId = "test-tenant",
// ... other settings
};
```
### Web UI Configuration
Create `.env.local` in the web project:
```env
NEXT_PUBLIC_API_BASE_URL=http://localhost:7071
```
This tells the web UI where to find the backend API.
## Testing End-to-End
### 1. Verify Backend is Running
Open a browser and navigate to:
```
http://localhost:7071/api/sessions/register
```
You should see a response (even if it's an error, it confirms the function is running).
### 2. Run the Agent
Start the agent in console mode (as Administrator):
```powershell
cd src/Agent/AutopilotMonitor.Agent/bin/Debug/net48
.\AutopilotMonitor.Agent.exe --console
```
### 3. Check Logs
Agent logs are written to:
```
C:\ProgramData\AutopilotMonitor\Logs\agent_YYYYMMDD.log
```
Backend logs appear in the Functions console output.
### 4. View in Web UI
Open `http://localhost:3000` and you should see the dashboard (currently shows placeholder data in Phase 1).
## Common Issues
### Azure Functions won't start
**Error**: `Missing value for AzureWebJobsStorage`
**Solution**: Ensure Azurite or Azure Storage Emulator is running, or update `local.settings.json` with valid connection strings.
### Agent can't connect to API
**Error**: `Error uploading events: The remote name could not be resolved`
**Solution**:
1. Verify Azure Functions is running at `http://localhost:7071`
2. Check Windows Firewall isn't blocking the connection
3. Update agent configuration with correct API URL
### Web UI shows blank page
**Solution**:
1. Check browser console for errors
2. Verify `npm run dev` completed without errors
3. Check `.env.local` exists and has correct API URL
### Permission Errors
Many agent operations require Administrator privileges:
- Reading certain event logs
- Writing to Program Files
- Installing as a Windows Service
Always run the agent as Administrator during development.
## Development Workflow
### Typical Development Session
1. **Start infrastructure** (Azurite, Functions)
```bash
# Terminal 1: Azurite
azurite --silent --location c:\azurite
# Terminal 2: Functions
cd src/Backend/AutopilotMonitor.Functions
func start
# Terminal 3: Web UI
cd src/Web/autopilot-monitor-web
npm run dev
```
2. **Make changes** to agent, backend, or web code
3. **Test changes**
- Agent: Rebuild and run in console mode
- Backend: Hot reload should pick up changes
- Web: Hot reload should pick up changes
4. **Debug**
- Agent: Attach Visual Studio debugger or use console output
- Backend: Use Functions console logs or attach debugger
- Web: Use browser DevTools
### Building for Release
```bash
# Build all projects in Release mode
dotnet build -c Release
# Build web UI for production
cd src/Web/autopilot-monitor-web
npm run build
```
## Next Steps
- Read the [Architecture Overview](architecture.md)
- Learn about [Deploying to Azure](deployment.md)
- Explore the [API Documentation](api-reference.md)
- Understand the [Rule Engine](rule-engine.md) (Phase 2)
## Getting Help
- Check the [README](../README.md) for general information
- Review logs in `C:\ProgramData\AutopilotMonitor\Logs\`
- Check Azure Functions output for backend errors
- Use browser DevTools for web UI issues