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"

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: "ms-teams-agent"
      deployment_environment: "test"
      headers:
        Authorization: "Basic your-token"

Datadog (OTLP)

output:
  otel:
    - name: "datadog"
      enabled: true
      endpoint: "https://otlp.datadoghq.com/v1/logs"
      service_name: "ms-teams-agent"
      deployment_environment: "test"
      headers:
        DD-API-KEY: "your-api-key"

Other OTEL

output:
  otel:
    - name: "custom-otel"
      enabled: true
      endpoint: "https://your-otel-endpoint/v1/logs"
      service_name: "ms-teams-agent"
      deployment_environment: "test"
      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 Grafana, Datadog, and Dynatrace OTLP ingestion. 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.

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:
    max_items_per_cycle: null    # No cap by default
    throttle:
      default_retry_after_seconds: 120
      max_backoff_seconds: 1800
      jitter_percent: 0.2
      escalation_multiplier: 2.0
      escalation_max_seconds: 3600
    rate_limits:
      list_per_second: 1.0
      detail_per_second: 20.0

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.max_items_per_cycle	null	Maximum number of new call IDs processed per cycle (>= 1). null means no cap (default).
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.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	1.0	Local outbound rate limit for LIST requests (> 0)
advanced.calls.rate_limits.detail_per_second	20.0	Local outbound rate limit for DETAIL requests (> 0)

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: Database Retention

The collector stores state in a local SQLite database (state.db). Use the database section to control its growth:

database:
  outbox_sent_retention_days: 7
  outbox_max_attempts: 12
  outbox_max_log_age_hours: 168
  max_processed_objects_per_type: 100000

Key	Default	Description
outbox_sent_retention_days	7	Days to keep sent outbox messages before purging
outbox_max_attempts	12	Max export attempts per outbox message before dead-lettering
outbox_max_log_age_hours	168	Drop stale logs before enqueue and auto-purge stale pending rows during export cycles (null disables this guard)
max_processed_objects_per_type	100000	Max deduplication cache entries per object type
processed_objects_max_age_hours	auto	Max age for cache entries (derived automatically if unset)

Omitting the database section keeps all defaults.

Optional: Quality Thresholds

Override default call quality classification thresholds:

advanced:
  quality_thresholds:
    audio:
      max_rtt_ms: 500
      max_jitter_ms: 30

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