Skip to content

Configuring the Collector

This page explains the settings you can configure in config.yaml. For command usage and operational flags, see CLI Reference.

Your configuration must include these four sections:

  • microsoft_authentication
  • license
  • output
  • collection_config

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"

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.

ReferenceResolved 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:
filepath: /etc/ms-teams-observability-agent/license.json

The 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.

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"
collection_config:
interval_collection_minutes: 10
max_call_duration_hours: 5
log_level: "INFO"
features:
calls_collection:
enabled: true
issues_collection:
enabled: true

max_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.

All feature flags default to false. Enable only what you need:

Feature flagDefaultNotes
calls_collectionfalseCore call records and stream details
issues_collectionfalseMicrosoft service health announcements
pstn_calls_collectionfalsePSTN call records
direct_routing_calls_collectionfalseDirect Routing call records
autoattendant_collectionfalseRequires VAAC credentials
callqueue_collectionfalseRequires VAAC credentials

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.

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
  1. 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.

  2. 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
  3. 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)

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"
KeyRequiredDescription
vaac.usernameYes (for AA/CQ)VAAC service account username
vaac.passwordYes (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: true

Use the telemetry section to control health telemetry sent to Phenisys.

telemetry:
enabled: false
timeout_seconds: 10
KeyDefaultDescription
enabledfalseEnable or disable telemetry requests entirely
timeout_seconds10Fail-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: 75
KeyDefaultDescription
advanced.proxy_urlnullOptional 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_pathnullOptional 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.

KeyDefaultDescription
advanced.scheduler.respect_persisted_backofffalseWhen true, the main loop honors persisted API backoff windows
advanced.scheduler.backoff_buffer_seconds5Extra safety margin added before resuming after backoff (>= 0)
KeyDefaultDescription
advanced.calls.throttle.default_retry_after_seconds120Fallback Retry-After when Graph does not provide one (>= 1)
advanced.calls.throttle.max_backoff_seconds1800Cap applied to per-throttle backoff (>= 1)
advanced.calls.throttle.in_cycle_max_retries2Maximum short retries within a single collection cycle (>= 0). 0 disables in-cycle retries
advanced.calls.throttle.in_cycle_retry_max_wait_seconds30Maximum wait time per in-cycle retry before escalating to persisted backoff (>= 1)
advanced.calls.throttle.jitter_percent0.2Random jitter ratio added to backoff (0.0 to 1.0)
advanced.calls.throttle.escalation_multiplier2.0Exponential multiplier for consecutive throttles (>= 1.0)
advanced.calls.throttle.escalation_max_seconds3600Hard cap for escalated backoff (>= 1)
advanced.calls.rate_limits.list_per_second2Local outbound rate limit for LIST requests (> 0). Also applies to PSTN and Direct Routing list endpoints
advanced.calls.rate_limits.detail_per_second75Local outbound rate limit for DETAIL requests (> 0)
license:
filepath: /etc/ms-teams-observability-agent/license.json
expiration_warning_days: 14
KeyDefaultDescription
filepath(required)Path to the license file
expiration_warning_days14Days before license expiration to start emitting warnings

Control the format of collector application logs (not exported data):

collection_config:
log_format: "text" # Options: "text" (default) or "json"

When using the console exporter, fine-tune its behavior:

output:
console:
enabled: true
pretty_print: true
max_logs_display: 10
KeyDefaultDescription
output.console.pretty_printtruePretty-print JSON records to the console
output.console.max_logs_display10Maximum number of log records to display per export batch

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"
ValueExample
epoch_ms (default)1767262830500
epoch_s1767262830
epoch_ns1767262830500000000
iso86012026-01-01T10:20:30.50Z
rfc33392026-01-01T10:20:30.50Z

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.0
KeyDefaultDescription
min_packet_utilization500Below this value, the stream is classified as Unclassified
max_rtt_ms500Maximum acceptable round-trip time in milliseconds
max_jitter_ms30Maximum acceptable jitter in milliseconds
max_packet_loss_rate0.10Maximum acceptable packet loss rate (10%)
KeyDefaultDescription
max_frame_loss_pct50.0Maximum acceptable video frame loss percentage
min_frame_rate_fps7.0Minimum acceptable video frame rate in fps
max_post_fec_loss_rate0.15Maximum acceptable post-FEC loss rate (15%)
KeyDefaultDescription
max_frame_loss_pct50.0Maximum acceptable sharing frame loss percentage
min_frame_rate_fps1.0Minimum 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.

Always validate before production rollout:

Terminal window
ms-teams-agent validate --config ./config.yaml
ms-teams-agent test-connection --config ./config.yaml

Both 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:

Terminal window
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.