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

Your configuration must include these four sections:

• microsoft_authentication
• license
• output
• collection_config

Microsoft Authentication

Use the tenant and app credentials from Azure Permissions.

Note

Azure app registration steps and full permissions reference are maintained in the canonical page: Collector Azure Permissions.

Client secret

microsoft_authentication:
  graph:
    tenant_id: "your-tenant-id"
    client_id: "your-client-id"
    client_secret: "your-secret"
    grant_type: "client_credentials"
    cloud_deployment: "global"

Certificate

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"

VAAC

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"

Note

cloud_deployment controls Graph host, authority, and default scope. Supported values are global, us_gov_gcc_high, us_gov_dod, and china. If you explicitly set scope, it overrides the derived default.

License

license:
  filepath: /etc/ms-teams-observability-agent/license.json

The collector will not start without a valid license file.

Output Platforms

Enable at least one output backend. Multiple outputs can be active simultaneously.

Note

Besides Dynatrace and Splunk, common OTLP targets include Grafana Cloud and Datadog. Use the OTLP tabs below and see OTLP Backend Configuration for endpoint details.

Dynatrace

output:
  dynatrace:
    enabled: true
    dynatrace_tenant_id: "your-tenant-id"
    dynatrace_api_token: "your-token"

Splunk

output:
  splunk:
    enabled: true
    splunk_hec_url: "https://your-splunk:8088/services/collector"
    splunk_hec_token: "your-hec-token"
    splunk_ssl_check: true

Grafana (OTLP)

output:
  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"

Datadog (OTLP)

output:
  otel:
    - name: "datadog"
      enabled: true
      endpoint: "https://otlp.datadoghq.com/v1/logs"
      service_name: "msteams-callrecords"
      deployment_environment: "production"
      headers:
        DD-API-KEY: ***

Other OTEL

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"

Console

output:
  console:
    enabled: true

Note

For OTel outputs, headers must be provided and non-empty for each enabled entry. Common targets include Datadog, Dynatrace OTLP ingestion, and custom OpenTelemetry collectors. See OTLP Backend Configuration for integration details.

Collection Settings

collection_config:
  interval_collection_minutes: 10
  max_call_duration_hours: 5
  log_level: "INFO"
  features:
    calls_collection:
      enabled: true
    issues_collection:
      enabled: true

Tip

interval_collection_minutes should balance freshness and processing capacity. A range between 2 and 10 minutes works well for most tenants, with 5 minutes as a practical sweet spot. For high call volume tenants, prefer higher intervals to let the agent finish processing cleanly and avoid backlog.

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.

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

Note

autoattendant_collection and callqueue_collection require a microsoft_authentication.vaac section with dedicated credentials.

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

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

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)

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

Tip

VAAC data typically becomes available within 30 minutes of call completion, though it can take several hours in some cases. The collector polls VAAC on the configured interval_collection_minutes.

For detailed field definitions and report interpretation, see the Microsoft VAAC documentation.

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

Use the advanced section to tune throttling behavior and call processing throughput.

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

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

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

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

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

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

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

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

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

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

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

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

Always validate before production rollout:

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