---
title: "Microsoft Teams Observability app plugin for Grafana"
description: "Observability app for Microsoft Teams call quality, users, sites, and issue insights. Microsoft Teams Observability app plugin for Grafana by Phenisys."
---

> This is the Markdown version of https://grafana.com/grafana/plugins/phenisys-msteamsobservability-app/

# Microsoft Teams Observability

- Developer: Phenisys
- Version: 1.2.1
- [Installation](https://grafana.com/grafana/plugins/phenisys-msteamsobservability-app/installation.md)
- [Change log](https://grafana.com/grafana/plugins/phenisys-msteamsobservability-app/changelog.md)

![Home](https://grafana.com/api/plugins/phenisys-msteamsobservability-app/versions/1.2.1/images/img/screenshots/home.png)

![Calls](https://grafana.com/api/plugins/phenisys-msteamsobservability-app/versions/1.2.1/images/img/screenshots/calls-2.png)

![Call Overview](https://grafana.com/api/plugins/phenisys-msteamsobservability-app/versions/1.2.1/images/img/screenshots/call-overview-all.png)

![Users](https://grafana.com/api/plugins/phenisys-msteamsobservability-app/versions/1.2.1/images/img/screenshots/users-2.png)

![Sites](https://grafana.com/api/plugins/phenisys-msteamsobservability-app/versions/1.2.1/images/img/screenshots/site-all.png)

![Issues](https://grafana.com/api/plugins/phenisys-msteamsobservability-app/versions/1.2.1/images/img/screenshots/issues.png)

# MS Teams Observability - Grafana Application

The **MS Teams Observability Grafana Application** provides ready-to-use visualizations to monitor Microsoft Teams call quality, users, sites, and service health directly inside **Grafana**.

Installed in a Grafana environment, the application gives operational visibility into Microsoft Teams activity and quality using telemetry collected by the agent and stored in a **Loki datasource**. It helps organizations monitor collaboration experience, investigate service degradations, analyze call quality by stream and participant, and support operational troubleshooting across engineering, operations, and support teams.

The application is designed to work with the [**Microsoft Teams Observability Agent**](https://github.com/Phenisys/microsoft-teams-observability), which collects and forwards the data used by the dashboards and investigation views.

The application also supports a **Demo Mode** with built-in sample data, allowing evaluation, testing, or demonstrations without requiring a live collector connection.

---

## Requirements

- **Grafana** >= 12.3.0
- A **Loki datasource** configured in the Grafana instance, containing the logs emitted by the [Microsoft Teams Observability Agent](https://github.com/Phenisys/microsoft-teams-observability) (Live Mode only)
- The **Microsoft Teams Observability Agent** deployed against the target tenant (Live Mode only)

Demo Mode has no runtime dependencies and can be used immediately after installation.

---

## Getting Started

### Installation

The application can be installed from the **Grafana plugin catalog** or by uploading the application ZIP package manually through the Grafana CLI.

Once installed, enable the app from **Administration -> Plugins -> MS Teams Observability -> Enable**.

### First use

The app ships with **Demo Mode** enabled by default — open any of its pages and explore the full UI with built-in sample data, no configuration required.

To switch to **Live Mode**:

1. Open the **Configuration** page from the app navigation.
2. Select the Loki datasource that receives telemetry from the Teams Observability Agent.
3. Toggle **Demo Mode** off.

The **Test** button in the plugin configuration reports the current mode and confirms that a Loki datasource is wired up when Live Mode is active.

### Datasource configuration

When using Live Mode, the MS Teams Observability datasource supports the following settings:

| Setting                  | Description                                                 | Default            |
| ------------------------ | ----------------------------------------------------------- | ------------------ |
| **Loki URL**             | HTTP URL of the Loki instance                               | `http://loki:3100` |
| **Loki tenant / org ID** | X-Scope-OrgID header value for multi-tenant Loki            | _(empty)_          |
| **Auth type**            | Authentication method (none, bearer, basic)                 | `none`             |
| **Service name**         | Value used in the LogQL selector `{service_name="<value>"}` | `ms-teams-agent`   |
| **Timeout**              | Loki query timeout in milliseconds                          | `30000`            |

The `service_name` field allows configuring the LogQL selector to match the label used by your collector deployment:

```logql
{service_name="ms-teams-agent"} | log_source="MSTeams_CallRecords_CallMetadata"
```

---

## Features

The application provides several views addressing different operational needs:

### Home

High-level observability cockpit for Microsoft Teams, showing a configurable time-range summary of call activity and quality with KPI cards, call health distribution (good / poor / unclassified), platform distribution, and quick links to embedded dashboards.

### Calls

Searchable and filterable list of recorded Microsoft Teams calls, with per-call health status, type (peer-to-peer or group), participant count, duration, and time range. Used to locate calls quickly, investigate quality problems, and navigate to the detailed call analysis view.

### Call Overview

Detailed analysis of a single Microsoft Teams call, organized as an investigation flow:

- **Call Verdict** — overall quality assessment, poor stream count, worst RTT / jitter / packet loss, transport protocol, and primary root cause
- **Quality Evidence** — stream-level evidence with severity, metric thresholds, and participant-level impact
- **Participants** — per-participant health matrix with connection type, protocol, egress ASN, relay region, stream count, and endpoint signals
- **Streams** — stream details table sortable by quality, RTT, jitter, and packet loss, with optional filter for degraded or poor streams
- **Network Evidence** — transport distribution, relay usage, public egress and ASN, shared IP and NAT patterns, IP geolocation map
- **Endpoint & Devices** — per-participant platform, client version, connection type, audio device signals, and CPU status
- **Advanced** — network IP inventory (role, ASN, ISP, geo, participants), raw stream records, and raw call metadata

### Users

Per-user analytics across the Microsoft Teams environment, including identity, email, IP addresses, protocols, call statistics (total, good, poor, unclassified), average duration, platform breakdown, and last seen timestamp. Each row can be expanded to show recent calls and per-protocol quality breakdown.

### Sites

Aggregated analysis of call quality and network performance by geographic location and subnet, with:

- KPI summary (total sites, NPA compliance, call quality, average latency, packet loss, sites at risk)
- Geographic map with site-level markers
- NPA compliance breakdown (compliant / non-compliant / undetermined)
- Sites requiring attention table with poor ratio, latency, jitter, packet loss, and main cause
- Call count by site and call quality distribution charts

### Issues

Displays Microsoft 365 service health incidents affecting the tenant, including active and recently resolved issues with severity, start time, title, and copyable issue ID, helping correlate degradations with known Microsoft outages.

### Configuration

Central configuration area for the application, including:

- License management
- Demo mode toggle
- Loki datasource selection and connection test
- Microsoft Graph integration test
- Domain allow / block filters
- Subnet mappings upload (CSV)
- Application permissions and access control

---

## Operating Modes

The application supports two operating modes:

- **Demo Mode** — uses built-in sample data with multiple realistic scenarios (peer-to-peer, group calls, good / poor / unclassified quality, bot detection, mobile switching) and can be used immediately after installation
- **Live Mode** — uses real tenant data sent by the collector and stored in the configured Loki datasource

This makes it possible to evaluate the UI and workflows before switching to production data.

---

## Related Components

### Teams Observability Agent

Collector project used to send Microsoft Teams observability data to Loki:

- [Phenisys/microsoft-teams-observability](https://github.com/Phenisys/microsoft-teams-observability)

---

## Support

Issues and feature requests can be submitted by opening a GitHub Issue on the plugin repository or by contacting Phenisys directly (<contact@phenisys.com>).
