Metrics Dictionary Guide - Phenisys/microsoft-teams-observability GitHub Wiki

Table of Contents

Metrics Documentation

This document provides a detailed description of the metrics sent by the Teams Observability script to Dynatrace or Splunk. The script collects data from the Microsoft Graph API related to Teams call records and service announcements, processes it, and sends it as logs for monitoring and analysis.

MS Teams Issue Logs

These logs provide information about unresolved issues related to Microsoft Teams services retrieved from the Microsoft Graph API service announcements.

Field Type Description
log.source String The source of the log. In this context, this is "MSTeams_ServiceAnnouncement".
loglevel String The log level indicating the severity or type of the log message (e.g., INFO, ERROR).
timestamp Integer The timestamp when the log was generated, in milliseconds since the epoch (UTC).
id String The unique identifier of the issue.
title String The title of the issue.
classification String The classification of the issue (e.g., Incident, Advisory).
impactDescription String A description of the impact caused by the issue.
serviceHealthStatus String The current status of the issue (e.g., ServiceDegradation, ServiceRestored).
service String The name of the affected service, which is Microsoft Teams in this context.
feature String The specific feature of the service affected by the issue.
featureGroup String The group or category of the feature affected.
startDateTime Integer The start date and time of the issue, in milliseconds since the epoch (UTC).
details String The latest detailed description or content about the issue.

Call Record Summary Logs

These logs contain global metadata about individual Teams calls, including call duration, participants, and modalities.

Field Type Description
log.source String The source of the log. For call record logs, this is "MSGraphAPI_CallRecords_GlobalMetadata".
startDateTime Integer The start time of the call in milliseconds since the epoch (UTC).
timestamp Integer The end time of the call in milliseconds since the epoch (UTC).
call.id String The unique identifier of the call.
type String The type of the call (e.g., peerToPeer, groupCall).
modalities Array of Strings The modalities used in the call (e.g., audio, video, videoBasedScreenSharing).
callDurationS Integer The duration of the call in seconds.
countParticipants Integer The number of participants in the call.
participantsNames Array of Strings The display names of the participants in the call.

Call Record Stream Details Logs

These logs provide detailed information about individual media streams within a call, including network metrics and participant details.

Field Type Description
log.source String The source of the log. For stream logs, this is "MSGraphAPI_CallRecords_StreamDetails".
startDateTime Integer The start time of the stream segment in milliseconds since the epoch (UTC).
timestamp Integer The end time of the stream segment in milliseconds since the epoch (UTC).
call.id String The unique identifier of the call.
type String The type of the call (e.g., peerToPeer, groupCall).
streamDirection String The direction of the stream relative to the participant, either send or receive.
mediaLabel String The label of the media stream (e.g., main-audio, main-video, applicationsharing-video).
streamDurationS Integer The duration of the stream in seconds.
streamHealth String The health classification of the stream, either Good, Poor, or Unclassified.
streamHealthCause String A short summary of the primary reason(s) for the stream being classified as Poor.
streamHealthCauseDetails String A more detailed explanation, including metric values, of why the stream was classified as Poor.

Participant Information

Depending on the call type (peerToPeer or groupCall), different participant details are included.

Common Fields (Caller)
Field Type Description
caller.id String The unique identifier of the caller.
caller.displayName String The display name of the caller.
caller.userPrincipalName String The user principal name (UPN) of the caller.
caller.deviceName String The device name used by the caller.
caller.cpuName String The CPU name of the caller's device.
caller.platform String The platform used by the caller (e.g., Windows, iOS).
caller.productFamily String The product family of the caller's application.
caller.teamsVersion String The version of Teams used by the caller.
Network Information (Caller)
Field Type Description
callerNetwork.ipAddress String The IP address of the caller's network.
callerNetwork.subnet String The subnet of the caller's network.
callerNetwork.reflexiveipAddress String The reflexive (public) IP address of the caller.
callerNetwork.relayIPAddress String The relay IP address used by the caller (if any).
callerNetwork.connectionType String The type of network connection used by the caller (WiFi, etc).
callerNetwork.networkTransportProtocol String The type of network protocol used by the caller (UDP, TCP).
Additional Fields for peerToPeer Calls (Callee)
Field Type Description
callee.id String The unique identifier of the callee.
callee.displayName String The display name of the callee.
callee.userPrincipalName String The user principal name (UPN) of the callee.
callee.deviceName String The device name used by the callee.
callee.cpuName String The CPU name of the callee's device.
callee.platform String The platform used by the callee (e.g., Windows, iOS).
callee.productFamily String The product family of the callee's application.
callee.teamsVersion String The version of Teams used by the callee.
Network Information (Callee)
Field Type Description
calleeNetwork.ipAddress String The IP address of the callee's network.
calleeNetwork.subnet String The subnet of the callee's network.
calleeNetwork.reflexiveipAddress String The reflexive (public) IP address of the callee.
calleeNetwork.relayIPAddress String The relay IP address used by the callee (if any).
calleeNetwork.connectionType String The type of network connection used by the callee (WiFi, etc).
calleeNetwork.networkTransportProtocol String The type of network protocol used by the callee (UDP, TCP).
Additional Fields for groupCall Calls
Field Type Description
calleeNetwork.reflexiveipAddress String The reflexive IP address of the Microsoft server in group calls.

Media-Specific Metrics

Depending on the media label, additional metrics are included:

Audio Streams (main-audio)
Field Type Description
averageRoundTripTimeMs Integer The average round-trip time in milliseconds.
averageJitterMs Integer The average network jitter in milliseconds.
averagePacketLossRatePercent Float The average packet loss rate as a percentage.
Video Streams (main-video, applicationsharing-video)
Field Type Description
averageVideoFrameLossPercentage Float The average video frame loss percentage.
averageVideoFrameRate Float The average video frame rate.
postForwardErrorCorrectionPacketLossRate Float The packet loss rate after forward error correction.
videoCodec String The video codec used (e.g., H264, RTVideo).

Call Record PSTN Logs

These logs contain detailed metadata about PSTN (Public Switched Telephone Network) call records in Microsoft Teams. Each log entry represents a single PSTN call event and includes information such as duration, cost, routing, and user details.

Field Type Description
log.source String Log source. For PSTN calls, always "MSTeams_CallRecords_PSTN".
loglevel String Log severity level (e.g., "INFO").
call.id String Unique identifier of the PSTN call.
userPrincipalName String UPN of the user who placed or received the call.
userDisplayName String Display name of the user involved in the call.
startDateTime Integer Call start time (ms since epoch, UTC).
timestamp Integer Call end time (ms since epoch, UTC).
duration Integer Duration of the call in seconds.
charge Float Total cost of the call.
callType String Indicates the type of call.
currency String Billing currency (e.g., USD, EUR).
calleeNumber String Called number in E.164 format.
callerNumber String Calling number in E.164 format.
usageCountryCode String Country code of the user.
tenantCountryCode String Country code of the tenant.
connectionCharge Float One-time connection fee, if applicable.
destinationName String Name of the destination (e.g., country or region).
licenseCapability String Microsoft license that enabled the call.
inventoryType String Number type (e.g., Service, serviceNumber).
operator String Telecom operator that routed the call.
callDurationSource String Source of call duration data (e.g., operator, microsoft).

Call Record Direct Routing Logs

These logs contain metadata for Direct Routing calls in Microsoft Teams. Each entry includes signaling and media details, SIP response information, and user/trunk identifiers.

Field Type Description
log.source String Log source. For Direct Routing calls, always "MSTeams_CallRecords_DirectRouting".
loglevel String Log severity level (e.g., "INFO").
call.id String Unique identifier of the Direct Routing call.
userPrincipalName String UPN of the user who placed or received the call.
userDisplayName String Display name of the user involved in the call.
startDateTime Integer Call start time (ms since epoch, UTC).
inviteDateTime Integer SIP INVITE received time (ms since epoch, UTC).
failureDateTime Integer Call failure time if applicable (ms since epoch, UTC).
timestamp Integer Call end time (ms since epoch, UTC).
duration Integer Call duration in seconds.
callType String Call type and direction.
successfulCall Boolean Indicates whether the call was successfully completed.
calleeNumber String The number called, in E.164 format.
callerNumber String The number of the caller, in E.164 format.
mediaPathLocation String Location used for the media path (e.g., US, EMEA).
signalingLocation String Location used for SIP signaling.
finalSipCode Integer Final SIP response code (e.g., 200, 487, 503).
callEndSubReason Integer Sub-reason for call termination. Provides context beyond SIP codes.
finalSipCodePhrase String SIP phrase associated with the final SIP response code.
trunkFullyQualifiedDomainName String FQDN of the SBC (Session Border Controller) trunk.
mediaBypassEnabled Boolean Indicates if media bypass was enabled for the call.

Agent Health Telemetry

These logs provide a summary of the script's execution and processing statistics.

Field Type Description
log.source String The source of the log. For summary logs, this is "MSTeams_CollectionHealth".
loglevel String The severity level of the log (e.g., "INFO", "WARNING", "ERROR").
timestamp Integer The timestamp when the log was generated, in milliseconds since the epoch (UTC).
version String The version of the script or application generating the log.
lastProcessedTimestamp String The ISO 8601 timestamp indicating the last time the script processed data.
requestedTimePeriodStart String The start of the requested time period for fetching call records.
requestedTimePeriodEnd String The end of the requested time period for fetching call records.
numberLogsSent Integer The number of logs sent to the destination.
logsSendingTimeSeconds Float The duration in seconds taken to send the logs.
callsCleaned Integer The number of calls removed from the cache due to retention policies.
PSTNCallsCleaned Integer The number of PSTN calls removed from the cache.
initialPSTNCallIdsInCache Integer The number of PSTN call IDs in the cache before processing.
PSTNCallIdsListed Integer The total number of PSTN call IDs fetched from the API.
PSTNCallIdsToProcess Integer The number of PSTN call IDs that were processed.
directRoutingCallsCleaned Integer The number of Direct Routing calls removed from the cache.
initialDirectRoutingCallIdsInCache Integer The number of Direct Routing call IDs in the cache before processing.
DirectRoutingCallIdsListed Integer The total number of Direct Routing call IDs fetched from the API.
DirectRoutingCallIdsToProcess Integer The number of Direct Routing call IDs that were processed.
successfulDirectRoutingCallsProcessed Integer The number of Direct Routing calls processed successfully.
initialCallIdsInCache Integer The number of call IDs in the cache before processing.
callIdsListed Integer The total number of call IDs fetched from the API.
callIdsToProcess Integer The number of call IDs that were processed.
averageProcessingTimePerCallIdSeconds Float The average processing time per call ID in seconds.
successfulCallsProcessed Integer The number of calls processed successfully.
scriptExecutionDurationSeconds Float The total duration of the script execution in seconds.
license_validation_information String Informational message regarding license validation.
license_validation_error String Error message, if any, encountered during license validation.
license Object Detailed license information.
features Object Feature configuration details.