Configuration

This page helps you build your file by sections, understand what each part does, then use a complete example at the end.

Required Sections

Your config.yaml should contain these top-level sections:

• microsoft_authentication
• output
• collection_config

Caution

CallRecords.Read.All, Reports.Read.All, and ServiceHealth.Read.All application permissions are required before startup.

1. Build microsoft_authentication

Use one of these authentication approaches.

Client Secret

microsoft_authentication:
    microsoft_tenant_id: 'your_tenant_id'
    microsoft_client_id: 'your_client_id'
    microsoft_client_secret: 'your_client_secret'
    microsoft_scope: 'https://graph.microsoft.com/.default'
    microsoft_grant_type: 'client_credentials'
    # cloud_deployment: 'global'  # Options: global, us_gov_gcc_high, us_gov_dod, china

Certificate

microsoft_authentication:
    microsoft_tenant_id: 'your_tenant_id'
    microsoft_client_id: 'your_client_id'
    microsoft_client_assertion_type: 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
    microsoft_client_certificate_path: '/path/to/pem'
    microsoft_client_certificate_passphrase: 'my_passphrase'
    microsoft_scope: 'https://graph.microsoft.com/.default'
    microsoft_grant_type: 'client_credentials'
    # cloud_deployment: 'global'  # Options: global, us_gov_gcc_high, us_gov_dod, china

VAAC Add-on

microsoft_authentication:
    # add these only for Auto Attendant / Call Queue features
    microsoft_username: 'your_account'
    microsoft_password: 'your_password'

Tip

VAAC credentials are needed only for: ms_teams_autoattendant_collection and ms_teams_callqueue_collection.

Note

National Cloud Deployments

By default the collector targets the worldwide Microsoft cloud. If your organisation uses a national cloud, set cloud_deployment in microsoft_authentication:

Value	Environment
global	Worldwide (default)
us_gov_gcc_high	Microsoft 365 GCC High
us_gov_dod	Microsoft 365 DoD
china	Microsoft 365 operated by 21Vianet (China)

Setting this value automatically adjusts the Microsoft Entra ID authentication endpoint and the Microsoft Graph API endpoint used by the collector. See the Microsoft Graph national cloud deployments reference for the full endpoint list.

2. Build output

Enable only the destinations you need.

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://mysplunk:8088/services/collector/event'
        splunk_hec_token: 'hec_token'
        splunk_ssl_check: false

Console

output:
    console:
        enabled: true

Note

At least one output must be enabled, otherwise the collector exits at startup.

Tip

The console output is useful for local testing. Combined with logfile_log_level: DEBUG in collection_config, it lets you verify the agent is running and collecting data correctly without forwarding anything to an external backend.

3. Build collection_config

This section defines scheduling, logs, license path, and enabled features.

collection_config:
    microsoft_max_call_duration_hours: 5
    logfile_log_level: 'INFO'
    license_file: '/absolute/path/to/license.lic'
    interval_collection_minutes: 1
    features:
        ms_teams_calls_collection:
            enabled: true
        ms_teams_issues_collection:
            enabled: true
        ms_teams_pstn_calls_collection:
            enabled: true
        ms_teams_direct_routing_calls_collection:
            enabled: true
        ms_teams_site_definition:
            enabled: false
        ms_teams_autoattendant_collection:
            enabled: false
        ms_teams_callqueue_collection:
            enabled: false

Tip

Always use an absolute path for license_file to avoid resolution issues.

Caution

DEBUG can produce large logs and expose sensitive metadata. Use it only for short troubleshooting sessions.

4. Advanced Options

The optional advanced block exposes settings for non-standard network environments.

Custom CA Bundle (TLS-inspecting proxies)

If the collector host sits behind a TLS-inspecting proxy or has a non-standard CA chain, certificate verification may fail for Microsoft Graph API calls — including report downloads that redirect through reportsncu.office.com. Set ca_bundle_path to the absolute path of your enterprise CA bundle in PEM format:

advanced:
    ca_bundle_path: "/etc/ssl/certs/corporate-ca-bundle.pem"

This setting applies to:

• All Microsoft Graph API calls
• Report downloads (including the reportsncu.office.com redirect)
• VAAC API calls

Tip

If you see a TLS certificate verification failed error mentioning reportsncu.office.com in the collector logs, this is the setting to configure. This is not a licensing issue.

5. Site Enrichment

Danger

ms_teams_site_definition will be removed in a future version. If it is present in your config, remove it.

To enrich call data with your network site information, use your backend’s native lookup feature instead — see Lookup File.

6. Full Example (config.yaml)

Download config.yaml or copy the template below:

microsoft_authentication:
    microsoft_tenant_id: "your-tenant-id"
    microsoft_client_id: "your-client-id"
    microsoft_client_secret: "your-client-secret"
    microsoft_grant_type: "client_credentials"
    # cloud_deployment: "global"  # Options: global, us_gov_gcc_high, us_gov_dod, china

output:
    dynatrace:
        dynatrace_tenant_id: "your-tenant-id"
        dynatrace_api_token: "your-api-token"
        enabled: true
    splunk:
        splunk_hec_url: "https://your-splunk-url:8088/services/collector/event"
        splunk_hec_token: "your-hec-token"
        splunk_ssl_check: false
        enabled: false
    console:
      enabled: true
collection_config:
    microsoft_max_call_duration_hours: 5
    logfile_log_level: "INFO"
    interval_collection_minutes: 5
    license_file: '/absolute/path/to/your/license.lic'
    features:
        ms_teams_direct_routing_calls_collection:
            enabled: true
        ms_teams_calls_collection:
            enabled: true
        ms_teams_issues_collection:
            enabled: false
        ms_teams_pstn_calls_collection:
            enabled: false
        ms_teams_autoattendant_collection:
            enabled: false
        ms_teams_callqueue_collection:
            enabled: false
        ms_teams_site_definition:
            enabled: false

# advanced:
#     # Optional: path to a CA bundle PEM file.
#     # Required when running behind a TLS-inspecting proxy or using a non-standard CA chain.
#     # Applies to all Microsoft Graph API calls (incl. reportsncu.office.com) and VAAC API calls.
#     ca_bundle_path: "/etc/ssl/certs/corporate-ca-bundle.pem"

7. Validate Before Production Start

1. Check the binary and config path:

   ./ms-teams-agent.bin --version

2. Run one first cycle without historical state:

   ./ms-teams-agent.bin --config ./conf/config.yaml --ignore_state

3. Check logs and backend ingestion before enabling service mode.