Runbook

Use this runbook for day-to-day collector operations.

Start the Collector

ms-teams-agent run --config /path/to/config.yaml

Continuous mode runs one collection cycle every collection_config.interval_collection_minutes.

Recommended Operation Flow

1. Validate configuration:

ms-teams-agent validate --config ./config.yaml

2. Test authentication and backend connectivity:

ms-teams-agent test-connection --config ./config.yaml

3. Start collection:

ms-teams-agent run --config ./config.yaml

Linux Service Operations

sudo ms-teams-agent service status --instance default
sudo ms-teams-agent service restart --instance default
sudo journalctl -u ms-teams-observability-agent@default.service -f

See Service Management for setup and upgrade flow.

Common Errors and Fixes

Error / symptom	Most likely cause	What to do
Configuration file not found	Wrong config path	Verify path and file permissions
Configuration validation failed	Invalid or missing YAML values	Compare with your template and re-run validate
License validation failed	Missing, invalid, or expired license	Replace with a valid license file
No exporters enabled!	All outputs disabled	Enable at least one output backend
No data in dashboards	Connectivity or auth issue	Re-run test-connection and check backend setup
Service setup fails	Missing Linux/systemd/root requirements	Use supported host and run with sudo

Quick Health Checks

• Collector log file:

tail -f logs/agent.log

• Service logs:

journalctl -u ms-teams-observability-agent@default.service -f

• Collection state:

ms-teams-agent state show

Operational Notes

• Use --dry-run only for testing because it does not export data.
• If data seems delayed, wait at least one full collection interval.
• Keep license and credentials at stable system paths with restricted permissions.

Tip

When troubleshooting ingestion issues, validate in this order: config, auth, connectivity, then backend routing.