Configuring the Collector
This page explains the settings you can configure in config.yaml. For command usage and operational flags, see CLI Reference.
Required Sections
Section titled “Required Sections”Your configuration must include these four sections:
microsoft_authenticationlicenseoutputcollection_config
Microsoft Authentication
Section titled “Microsoft Authentication”Use the tenant and app credentials from Azure Permissions.
microsoft_authentication: graph: tenant_id: "your-tenant-id" client_id: "your-client-id" client_secret: "your-secret" grant_type: "client_credentials" cloud_deployment: "global"microsoft_authentication: graph: tenant_id: "your-tenant-id" client_id: "your-client-id" client_certificate_path: "/etc/ms-teams-observability-agent/graph.pem" client_certificate_passphrase: "optional" grant_type: "client_credentials" cloud_deployment: "global"microsoft_authentication: graph: tenant_id: "your-tenant-id" client_id: "your-client-id" client_secret: "your-secret" grant_type: "client_credentials" vaac: username: "your-vaac-username" password: "your-vaac-password"Secret references
Section titled “Secret references”Any credential in the configuration can be kept out of the YAML file by writing a reference instead of the literal value. The value is read when the configuration is loaded, so the file itself never contains the secret.
| Reference | Resolved to |
|---|---|
${env:NAME} | Value of the environment variable NAME |
${file:/path/to/file} | Content of the file, with trailing line breaks removed |
microsoft_authentication: graph: tenant_id: "your-tenant-id" client_id: "your-client-id" client_secret: "${env:GRAPH_CLIENT_SECRET}"
output: splunk: enabled: true splunk_hec_url: "https://your-splunk:8088/services/collector" splunk_hec_token: "${file:/etc/ms-teams-observability-agent/splunk.token}"Rules and behaviour:
- Only string values are scanned, never mapping keys. A reference may sit inside
a larger value, for example
Authorization: "Bearer ${env:OTLP_TOKEN}". - Relative
${file:...}paths are resolved from the directory of the configuration file. - Resolution is single pass: a resolved value is never scanned again.
$${env:NAME}is an escape and produces the literal text${env:NAME}.- Any other
${...}form is left untouched.
The runtime is strict: run and test-connection refuse to start when a referenced
variable is unset or a referenced file cannot be read. To check the structure of a
configuration that does not have its secrets available yet, use
validate --skip-secrets (see Validation).
License
Section titled “License”license: filepath: /etc/ms-teams-observability-agent/license.jsonThe collector will not start without a valid license file.
The license signature is verified against the official public key embedded in the
distributed binary or package. That trust anchor is not configurable: no setting, no
environment variable and no file placed next to the executable can substitute it.
license.filepath is the only configurable license setting.
Output Platforms
Section titled “Output Platforms”Enable at least one output backend. Multiple outputs can be active simultaneously.
output: dynatrace: enabled: true dynatrace_tenant_id: "your-tenant-id" dynatrace_api_token: "your-token"output: splunk: enabled: true splunk_hec_url: "https://your-splunk:8088/services/collector" splunk_hec_token: "your-hec-token" splunk_ssl_check: trueoutput: otel: - name: "grafana" enabled: true endpoint: "https://otlp-gateway-prod-eu-west-2.grafana.net/otlp/v1/logs" service_name: "msteams-callrecords" deployment_environment: "production" headers: Authorization: "Basic your-token"output: otel: - name: "datadog" enabled: true endpoint: "https://otlp.datadoghq.com/v1/logs" service_name: "msteams-callrecords" deployment_environment: "production" headers: DD-API-KEY: ***output: otel: - name: "custom-otel" enabled: true endpoint: "https://your-otel-endpoint/v1/logs" service_name: "msteams-callrecords" deployment_environment: "production" headers: Authorization: "Bearer your-token"output: console: enabled: trueCollection Settings
Section titled “Collection Settings”collection_config: interval_collection_minutes: 10 max_call_duration_hours: 5 log_level: "INFO" features: calls_collection: enabled: true issues_collection: enabled: truemax_call_duration_hours sets the maximum call duration in hours (1–60). Calls exceeding this threshold are considered stale and skipped. This is a required field.
Feature flags
Section titled “Feature flags”All feature flags default to false. Enable only what you need:
| Feature flag | Default | Notes |
|---|---|---|
calls_collection | false | Core call records and stream details |
issues_collection | false | Microsoft service health announcements |
pstn_calls_collection | false | PSTN call records |
direct_routing_calls_collection | false | Direct Routing call records |
autoattendant_collection | false | Requires VAAC credentials |
callqueue_collection | false | Requires VAAC credentials |
VAAC (Auto Attendant & Call Queue)
Section titled “VAAC (Auto Attendant & Call Queue)”The Voice Applications Analytics Collector (VAAC) is a Microsoft service that provides historical call data for Teams Auto Attendants and Call Queues. It is the data source for the autoattendant_collection and callqueue_collection features.
What VAAC provides
Section titled “What VAAC provides”VAAC gives access to calls processed by Teams Phone Agents, Auto Attendants, and Call Queues that are not available through the standard Microsoft Graph callRecords API. This includes:
- Auto Attendant analytics: caller paths, menu navigation (DTMF/voice), directory search usage, call transfers, termination reasons
- Call Queue analytics: wait times, abandon rates, agent answer rates, overflow/timeout handling, agent opt-in counts
- Agent Timeline: per-agent call duration, answered calls by date/hour, average handling time
Prerequisites
Section titled “Prerequisites”-
VAAC credentials: A dedicated service account with access to the VAAC Power BI data source. These are the same credentials used in the official Microsoft VAAC Power BI template.
-
Permissions: The account must be either:
- Set up as an Authorized User for the target Auto Attendants and Call Queues, or
- Assigned a CQD access role with View Reports and View EUII fields enabled
-
Cloud deployment: The collector supports the same cloud deployments as the VAAC service:
- Global (includes GCC tenants)
- Government Community Cloud High (GCCH)
- Department of Defence (DoD)
Configuration
Section titled “Configuration”Add the vaac block under microsoft_authentication with your VAAC service account credentials:
microsoft_authentication: graph: tenant_id: "your-tenant-id" client_id: "your-client-id" client_secret: "your-secret" vaac: username: "your-vaac-username" password: "your-vaac-password"| Key | Required | Description |
|---|---|---|
vaac.username | Yes (for AA/CQ) | VAAC service account username |
vaac.password | Yes (for AA/CQ) | VAAC service account password |
Then enable the features in collection_config.features:
collection_config: features: autoattendant_collection: enabled: true callqueue_collection: enabled: trueOptional: Telemetry
Section titled “Optional: Telemetry”Use the telemetry section to control health telemetry sent to Phenisys.
telemetry: enabled: false timeout_seconds: 10| Key | Default | Description |
|---|---|---|
enabled | false | Enable or disable telemetry requests entirely |
timeout_seconds | 10 | Fail-fast timeout in seconds for telemetry HTTP requests (minimum: 1) |
Optional: Advanced Scheduler and Calls Controls
Section titled “Optional: Advanced Scheduler and Calls Controls”Use the advanced section to tune throttling behavior and call processing throughput.
advanced: proxy_url: "http://proxy.example.com:8080" scheduler: respect_persisted_backoff: false backoff_buffer_seconds: 5 calls: throttle: default_retry_after_seconds: 120 max_backoff_seconds: 1800 in_cycle_max_retries: 2 in_cycle_retry_max_wait_seconds: 30 jitter_percent: 0.2 escalation_multiplier: 2.0 escalation_max_seconds: 3600 rate_limits: list_per_second: 2 detail_per_second: 75Outbound proxy
Section titled “Outbound proxy”| Key | Default | Description |
|---|---|---|
advanced.proxy_url | null | Optional HTTP/HTTPS forward proxy for all outbound traffic — Azure AD token requests, Microsoft Graph, VAAC and the log exporters (Dynatrace, Splunk, OTLP). Must start with http:// or https://. Inline credentials are supported: http://user:password@proxy.example.com:8080 (percent-encode special characters in the username or password). |
advanced.ca_bundle_path | null | Optional path to a PEM bundle used to verify TLS certificates. Required in addition to proxy_url when the proxy intercepts TLS (SSL decryption), otherwise certificate validation fails. |
Outbound proxy support covers Microsoft traffic (Azure AD, Microsoft Graph, VAAC) and the log exporters (Dynatrace, Splunk, OTLP). Leave proxy_url unset to connect directly.
Scheduler controls
Section titled “Scheduler controls”| Key | Default | Description |
|---|---|---|
advanced.scheduler.respect_persisted_backoff | false | When true, the main loop honors persisted API backoff windows |
advanced.scheduler.backoff_buffer_seconds | 5 | Extra safety margin added before resuming after backoff (>= 0) |
Calls controls
Section titled “Calls controls”| Key | Default | Description |
|---|---|---|
advanced.calls.throttle.default_retry_after_seconds | 120 | Fallback Retry-After when Graph does not provide one (>= 1) |
advanced.calls.throttle.max_backoff_seconds | 1800 | Cap applied to per-throttle backoff (>= 1) |
advanced.calls.throttle.in_cycle_max_retries | 2 | Maximum short retries within a single collection cycle (>= 0). 0 disables in-cycle retries |
advanced.calls.throttle.in_cycle_retry_max_wait_seconds | 30 | Maximum wait time per in-cycle retry before escalating to persisted backoff (>= 1) |
advanced.calls.throttle.jitter_percent | 0.2 | Random jitter ratio added to backoff (0.0 to 1.0) |
advanced.calls.throttle.escalation_multiplier | 2.0 | Exponential multiplier for consecutive throttles (>= 1.0) |
advanced.calls.throttle.escalation_max_seconds | 3600 | Hard cap for escalated backoff (>= 1) |
advanced.calls.rate_limits.list_per_second | 2 | Local outbound rate limit for LIST requests (> 0). Also applies to PSTN and Direct Routing list endpoints |
advanced.calls.rate_limits.detail_per_second | 75 | Local outbound rate limit for DETAIL requests (> 0) |
Optional: License Settings
Section titled “Optional: License Settings”license: filepath: /etc/ms-teams-observability-agent/license.json expiration_warning_days: 14| Key | Default | Description |
|---|---|---|
filepath | (required) | Path to the license file |
expiration_warning_days | 14 | Days before license expiration to start emitting warnings |
Optional: Log Format
Section titled “Optional: Log Format”Control the format of collector application logs (not exported data):
collection_config: log_format: "text" # Options: "text" (default) or "json"Optional: Console Output Settings
Section titled “Optional: Console Output Settings”When using the console exporter, fine-tune its behavior:
output: console: enabled: true pretty_print: true max_logs_display: 10| Key | Default | Description |
|---|---|---|
output.console.pretty_print | true | Pretty-print JSON records to the console |
output.console.max_logs_display | 10 | Maximum number of log records to display per export batch |
Optional: Timestamp Format
Section titled “Optional: Timestamp Format”Configure how timestamps are formatted in exported records. Applies per output:
output: dynatrace: enabled: true dynatrace_tenant_id: "..." dynatrace_api_token: "..." time_fields_format: "iso8601"| Value | Example |
|---|---|
epoch_ms (default) | 1767262830500 |
epoch_s | 1767262830 |
epoch_ns | 1767262830500000000 |
iso8601 | 2026-01-01T10:20:30.50Z |
rfc3339 | 2026-01-01T10:20:30.50Z |
Optional: Quality Thresholds
Section titled “Optional: Quality Thresholds”Override default call quality classification thresholds:
advanced: quality_thresholds: audio: min_packet_utilization: 500 max_rtt_ms: 500 max_jitter_ms: 30 max_packet_loss_rate: 0.10 video: max_frame_loss_pct: 50.0 min_frame_rate_fps: 7.0 max_post_fec_loss_rate: 0.15 sharing: max_frame_loss_pct: 50.0 min_frame_rate_fps: 1.0Audio quality thresholds
Section titled “Audio quality thresholds”| Key | Default | Description |
|---|---|---|
min_packet_utilization | 500 | Below this value, the stream is classified as Unclassified |
max_rtt_ms | 500 | Maximum acceptable round-trip time in milliseconds |
max_jitter_ms | 30 | Maximum acceptable jitter in milliseconds |
max_packet_loss_rate | 0.10 | Maximum acceptable packet loss rate (10%) |
Video quality thresholds
Section titled “Video quality thresholds”| Key | Default | Description |
|---|---|---|
max_frame_loss_pct | 50.0 | Maximum acceptable video frame loss percentage |
min_frame_rate_fps | 7.0 | Minimum acceptable video frame rate in fps |
max_post_fec_loss_rate | 0.15 | Maximum acceptable post-FEC loss rate (15%) |
Sharing quality thresholds
Section titled “Sharing quality thresholds”| Key | Default | Description |
|---|---|---|
max_frame_loss_pct | 50.0 | Maximum acceptable sharing frame loss percentage |
min_frame_rate_fps | 1.0 | Minimum acceptable sharing frame rate in fps |
Quality thresholds are configurable, but it is recommended to keep the default values unless you have a validated operational reason to tune them.
Validation
Section titled “Validation”Always validate before production rollout:
ms-teams-agent validate --config ./config.yamlms-teams-agent test-connection --config ./config.yamlBoth commands resolve every secret reference and fail if one cannot be resolved, so they need the real credentials. When the secrets are not available yet — for example while preparing a package or validating the structure of a file before it is deployed — run the structure-only check instead:
ms-teams-agent validate --config ./config.yaml --skip-secrets--skip-secrets only defers the resolution of secret references; the schema, the
structure and every non-secret value are still validated. It is accepted by validate
only: run and test-connection always require the real secrets.