Matchmaker logs

Learn how Matchmaker logs provide insights into matchmaking activity and help diagnose issues.

읽는 시간 8분

최근 업데이트: 10일 전

Matchmaker writes a log record for each significant event in the life of a matchmaking ticket, so you can detect and debug live issues. Records are available in the Unity Dashboard, and you can filter them by time range and by content using a query language.

Logging has the following characteristics:

Structured, OpenTelemetry-compliant log schema
Seven days of retention
Time range and log field filters
Pagination

For an explanation of the ticket states these records describe, refer to Matchmaker ticket flow.

참고

This product isn't designed to collect Personally Identifiable Information and must not be used for that purpose.

Access logs

To access Matchmaker logs from the Unity Dashboard, follow these steps:

In the Unity Dashboard, go to Development > Products.
Select Matchmaker.
Select Logs.

Understand record types

Matchmaker emits two kinds of records. Both appear in the same log stream and both carry log attributes, but you read their message bodies in different ways.

Ticket lifecycle records
Match builder snapshots

Ticket lifecycle records describe a single event, such as the creation of a ticket or a match. The

matchmaker.event.name

attribute identifies the event, and the message body carries the payload your game sent. For example, a

ticket.created

body contains the whole ticket, including its players, custom data, Quality of Service (QoS) results, attributes, and author.

Match builder snapshots describe an attempt to build a match that didn't succeed. Matchmaker emits a snapshot when a ticket expires without matching, which makes snapshots the primary signal for diagnosing tickets that never match. A snapshot carries a JSON message body rather than prose, and the body contains the applied rules, the teams, the per-ticket player details with their QoS results, the match definition, and a

timeoutReason

field. Parse the body to read these values.

Snapshots carry no

matchmaker.event.name

, because event names describe ticket lifecycle events. Snapshots do carry

matchmaker.ticket.id

and

matchmaker.player.ids

, so a filter on either attribute returns the snapshots for a ticket alongside its lifecycle records. A record with a JSON body and no event name is a snapshot.

참고

The

traceId

and

spanId

fields are normally empty on Matchmaker records. No single trace spans a matchmaking flow, because a match is built from many tickets that each arrive on a separate request. To group the records for one match, use

matchmaker.match.id

and

matchmaker.ticket.ids

instead.

Log attributes

Matchmaker adds a set of attributes to each record, which you can both filter on and read back. Every record also carries the

unity.project.id

and

unity.environment.id

resource attributes, and a unique

log.record.uid

The following table lists the attributes that appear in the

logAttributes

field of a log response, and the records each one appears on.

Attribute	Description	Appears on
`matchmaker.event.name`	The lifecycle event this record describes. Refer to Event names.	Ticket lifecycle records
`matchmaker.queue.name`	The name of the queue the ticket or match belongs to.	Records where the queue is known
`matchmaker.pool.name`	The name of the pool the ticket or match belongs to.	Records where the pool is known
`matchmaker.ticket.id`	The ID of a single matchmaking ticket.	Ticket-scoped records
`matchmaker.ticket.ids`	A comma-separated list of the IDs of the tickets that formed the match.	Match creation records
`matchmaker.player.ids`	A comma-separated list of the IDs of the players on the ticket or in the snapshot.	Ticket-scoped records and match builder snapshots
`matchmaker.match.id`	The ID of the match.	Match-scoped and allocation-scoped records
`matchmaker.backfillTicket.id`	The ID of the backfill ticket.	Backfill records

중요

The

matchmaker.ticket.ids

and

matchmaker.player.ids

values hold at most 100 entries. When Matchmaker truncates a value, the value ends in

...

. The message body always carries the full list, so parse the body when you need every entry.

Event names

The

matchmaker.event.name

attribute takes one of the following values.

Event name	Occurs when
`ticket.created`	Your game creates a matchmaking ticket.
`ticket.deleted`	Matchmaker deletes a ticket.
`ticket.timed_out`	A ticket reaches its timeout before Matchmaker matches it.
`ticket.assignment.created`	Matchmaker creates the assignment that tells a player where to connect.
`match.created`	Matchmaker creates a match from a set of tickets.
`backfill.ticket.created`	Matchmaker creates a backfill ticket.
`backfill.ticket.updated`	Matchmaker updates a backfill ticket.
`backfill.ticket.deleted`	Matchmaker deletes a backfill ticket.
`backfill.match.created`	Matchmaker adds players to an existing match through backfill.
`allocation.requested`	Matchmaker requests a server allocation for a match.
`allocation.succeeded`	A server allocation succeeds.
`allocation.failed`	A server allocation fails.

참고

Matchmaker emits no record when a backfill ticket expires. Only regular tickets produce a

ticket.timed_out

record.

Filter logs

The logging service supports a custom query language that allows you to filter the structured logs. This section walks you through the syntax and usage of the query language, and provides some examples to help you get started.

Basic syntax and operators

A filter query consists of one or more conditions. The basic syntax of a condition consists of the following components:

Component	Condition
Field	The field you want to filter on, such as `severityText` , `body` , or `logAttributes` .
Operator	One of the supported operators. Refer to the table of operators below.
Value	The value you want to compare the field against.

Refer to the table below for a list of supported operators.

Operator	Meaning
`=`	equals
`!=`	not equals
`~=`	contains
`!~=`	does not contain
`\>`	greater than
`<`	less than
`<=`	less than or equal to
`\>=`	greater than or equal to

The contains operators match a substring anywhere in the value, and they ignore case. Use them on any field, including log attributes, which is how you find one player in a comma-separated list.

Boolean expressions and grouping

You can create complex filter queries with Boolean expressions and parentheses. Combine multiple conditions this way to create precise filters.

Boolean expression	Meaning
`AND` or `&&`	Require both conditions on either side to be true.
`OR` or `\|\|`	Require at least one of the conditions on either side to be true.
Grouping	Use parentheses `(` and `)` to group expressions and control the order of evaluation.

The query language also interprets line feeds as Boolean

AND

operators, which simplifies query writing. Write one condition per line when you want all of them to match:


resourceAttributes.service.name = "matchmaker"severityNumber >= 12

Examples of filter queries

Consult the following example filter queries to search through your logs:

Description	Filter query
Search logs for a pool by name	`logAttributes.matchmaker.pool.name = "default-pool"`
Search logs for a queue by name	`logAttributes.matchmaker.queue.name = "default-queue"`
Search logs for an environment ID	`resourceAttributes.unity.environment.id = "uuid"`
Search logs for a match ID	`logAttributes.matchmaker.match.id = "uuid"`
Search logs for a ticket ID	`logAttributes.matchmaker.ticket.id = "uuid"`
Search logs for a match that contains a ticket	`logAttributes.matchmaker.ticket.ids ~= "uuid"`
Search logs for a backfill ticket ID	`logAttributes.matchmaker.backfillTicket.id = "uuid"`
Select all records for one lifecycle event	`logAttributes.matchmaker.event.name = "ticket.timed_out"`
Select all logs with a certain severity level	`severityText = "ERROR"`
Exclude logs with a particular word in the message	`body !~= "healthcheck"`
Combine multiple conditions and groupings (using severity alias)	`(logAttributes.matchmaker.pool.name = "default-pool" AND body ~= "timeout") OR (logAttributes.matchmaker.queue.name = "default-queue" AND severity = "WARN")`

Filter query rules

Be aware of the following filter query language rules:

The
```
severityText
```
field is also aliased as
```
severity
```
for convenience.
Field names such as
```
logAttributes
```
and
```
severityText
```
aren't case-sensitive, but the attribute keys that follow them are. Write
```
matchmaker.backfillTicket.id
```
exactly as it appears in Log attributes.
The logging service converts attribute values to strings automatically.
A query can't contain the
```
[
```
,
```
]
```
, or
```
?
```
characters.
You can't filter on the record timestamp. Use the time range parameters instead.
You can't filter on the project ID. The project the query runs against is fixed by the request.

Diagnose a ticket that never matched

When a player reports that they can't get a match, the ticket timeout record and the match builder snapshot together explain why. Matchmaker emits both when the ticket expires.

To find out why a ticket didn't match, follow these steps:

Retrieve every record for the ticket:


logAttributes.matchmaker.ticket.id = "<ticketId>"

Confirm the ticket expired. The timeout record is the one whose
```
matchmaker.event.name
```
is
```
ticket.timed_out
```
.
Find the match builder snapshot in the same result set. It's the record with a JSON body and no
```
matchmaker.event.name
```
.
Parse the snapshot's body and read the
```
timeoutReason
```
field, then compare the applied rules and the per-ticket QoS results against the pool configuration.

Find the records for one player

The

matchmaker.player.ids

attribute holds a comma-separated list, because a ticket can carry a party of several players. An equality filter only matches a ticket whose entire list is that one player, so use the contains operator to match a single player:


logAttributes.matchmaker.player.ids ~= "<playerId>"

This query returns both the ticket lifecycle records and the match builder snapshots for that player, which gives you the ticket's history and the explanation of why it never matched in one result set.

중요

The contains operator matches a substring, so a player ID that's a substring of another player's ID also matches. The value also holds at most 100 entries, so this filter doesn't match a player beyond that limit.

기술 자료

Development

User Acquisition

Monetization

산업 분야

기술 자료

Development

User Acquisition

Monetization

산업 분야

Multiplayer Services SDK

All Services

Multiplayer Services SDK

Matchmaker logs

Access logs

Understand record types

Log attributes

Attribute

Description

Appears on

Event names

Event name

Occurs when

Filter logs

Basic syntax and operators

Component

Condition

Operator

Meaning