Matchmaker logs

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

Read time 2 minutes

Last updated a day ago

Logging is a feature of Matchmaker to detect and debug live issues.

Logs are available in the Unity Dashboard. You can filter logs by time range, and by content using a query language.

The log schema is OpenTelemetry compliant.

Logging has the following key features:

Structured log schema
Seven days of retention
Time range filter
Log fields filter
Pagination

Note

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

Access logs

The following instructions explain how to access the Matchmaker logging feature from the Unity Dashboard.

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

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 (only available on `body` )
`!~=`	does not contain (only available on `body` )
`\>`	greater than
`<`	less than
`<=`	less than or equal to
`\>=`	greater than or equal to

Boolean expressions and grouping

You can create complex filter queries using boolean expressions and grouping with parentheses. This allows you to combine multiple conditions 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.

Line feeds are also interpreted as boolean

AND

s to simplify query writing. This means that you can write one condition per line when you want them all to be matched.

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 project ID	`ResourceAttributes.unity.project.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 backfill ticket ID	`LogAttributes.matchmaker.backfillTicket.id == "uuid"`
Search logs for an allocation ID	`LogAttributes.matchmaker.allocation.id == "uuid"`
Search logs for a region ID	`LogAttributes.matchmaker.region.id == "uuid"`
Select all logs with a certain severity level	`severityText = "ERROR"`
Select all logs that are above a certain severity level (newlines are treated as AND)	`resourceAttributes.service.name = "matchmaker"` `severityNumber >= 12`
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")`

Be aware of the following filter query language rules:

The
```
severityText
```
field is also aliased as
```
severity
```
for convenience.
Fuzzy match operators (~= and !~=) are only supported for the
```
body
```
field.
The
```
LogAttributes
```
keys are case-sensitive.
The
```
LogAttributes
```
values are automatically converted to string.

Documentation

Development

User Acquisition

Monetization

Industry

Documentation

Development

User Acquisition

Monetization

Industry

Multiplayer Services SDK

All Services

Multiplayer Services SDK

Matchmaker logs

Access logs

Filter logs

Basic syntax and operators

Component

Condition

Operator

Meaning

Boolean expressions and grouping

Boolean expression

Meaning

Examples of filter queries

Description

Filter query