# Matchmaker Session Observability

> Monitor and analyze multiplayer session performance through detailed events and session data.

> **Important:**
>
> The Session Observability service is deprecated and will be removed on November 1st, 2026. Use [Matchmaker logs](./mm-logs.md) for matchmaking observability instead.

The Session Observability service exposes key Matchmaker events that occur in a multiplayer session.

The [Session observability API](https://services.docs.unity.com/session-observability/v1) allows fetching of session details by ID or by the following filter criteria:

* Pool ID
* Pool Name
* Queue Name
* Region ID
* Matchmaking Ticket ID
* Created After
* Updated After

Session details are stored for 30 days from its creation.

## Authentication

The Session Observability service uses [service account authentication](https://services.docs.unity.com/docs/service-account-auth/index.html). Service accounts that are granted the project-level [Multiplayer Session Details Viewer](https://services.docs.unity.com/docs/service-account-auth/index.html#multiplayer-session-details-viewer) role will be authorized to make requests to the API for that project.

## Session events

> **Note:**
>
> Player IDs in session events are anonymized to `Player 1`, `Player 2`, etc. to comply with policies regarding retention of personal identifiable information. These anonymized IDs are consistent across one session only.

The following session events are currently supported:

| Event name             | Description                                                                                                                                                                                             |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Match Created          | A match was created by matchmaker. The `matchId` of this match is the `sessionId` of this session. This event contains the teams in this match and the rules applied to create this match.              |
| Allocation Requested   | A Multiplay Hosting allocation was requested for this session in the specified region.                                                                                                                  |
| Allocation Succeeded   | The requested Multiplay Hosting allocation was successful.                                                                                                                                              |
| Allocation Failed      | The requested Multiplay Hosting allocation has failed.                                                                                                                                                  |
| Players Assigned       | Players have been assigned to this session by the matchmaker.                                                                                                                                           |
| Backfill Match Created | Requires backfill to be enabled. A match has been created for the backfill ticket associated with this session. This event contains the teams in this match and the rules applied to create this match. |
| Players Connected      | Requires backfill to be enabled. Players external to the matchmaker have connected to the session. The matchmaker uses backfill updates sent by the DGS to determine these players.                     |
| Players Disconnected   | Requires backfill to be enabled. Players external to the matchmaker have disconnected from the session. The matchmaker uses backfill updates sent by the DGS to determine these players.                |

## Sample session detail

The following is an example of a response received from the API of a session detail where backfill is not enabled.

```json
{
    "allocation": {
        "completedAt": "2024-03-19T22:12:48.237Z",
        "regionId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
        "requestedAt": "2024-03-19T22:12:47.981Z",
        "status": "Allocated"
    },
    "createdAt": "2024-03-19T22:12:47.847Z",
    "environmentId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
    "gameMode": {
        "poolId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
        "poolName": "default-pool",
        "queueId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
        "queueName": "default-queue"
    },
    "matchmakingStatus": "OpenNotBackfilling",
    "projectId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
    "sessionEvents": [
        {
            "appliedRules": [
                {
                    "context": "Team",
                    "teamId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
                    "name": "Blue Team",
                    "type": "Difference",
                    "source": "Players.CustomData.Skill",
                    "reference": 500,
                    "not": false,
                    "externalData": {}
                }
            ],
            "teams": [
                {
                    "id": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
                    "name": "Red Team",
                    "playerIds": [
                        "Player 1",
                        "Player 2",
                        "Player 3"
                    ]
                },
                {
                    "id": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
                    "name": "Blue Team",
                    "playerIds": [
                        "Player 4",
                        "Player 5",
                        "Player 6"
                    ]
                }
            ],
            "timestamp": "2024-03-19T22:12:47.847Z",
            "type": "match.created"
        },
        {
            "regionId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
            "timestamp": "2024-03-19T22:12:47.981Z",
            "type": "allocation.requested"
        },
        {
            "timestamp": "2024-03-19T22:12:48.237Z",
            "type": "allocation.succeeded"
        },
        {
            "assignmentStatus": "Found",
            "players": [
                {
                    "customData": {
                        "Skill": 2000
                    },
                    "id": "Player 3",
                    "qosResults": [],
                    "ticketId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5"
                },
                {
                    "customData": {
                        "Skill": 1800
                    },
                    "id": "Player 4",
                    "qosResults": [],
                    "ticketId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5"
                },
                {
                    "customData": {
                        "Skill": 2100
                    },
                    "id": "Player 5",
                    "qosResults": [],
                    "ticketId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5"
                },
                {
                    "customData": {
                        "Skill": 1750
                    },
                    "id": "Player 6",
                    "qosResults": [],
                    "ticketId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5"
                },
                {
                    "customData": {
                        "Skill": 1950
                    },
                    "id": "Player 1",
                    "qosResults": [],
                    "ticketId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5"
                },
                {
                    "customData": {
                        "Skill": 1675
                    },
                    "id": "Player 2",
                    "qosResults": [],
                    "ticketId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5"
                }
            ],
            "timestamp": "2024-03-19T22:12:49.198Z",
            "type": "players.assigned"
        }
    ],
    "sessionId": "0e5a4f23-5e1a-4a82-80b0-a1bd80019bc5",
    "updatedAt": "2024-03-19T22:12:49.198Z"
}
```