Documentation

Support

Matchmaker

Matchmaker

Matchmaker logs

Learn how Matchmaker logs provide insights into matchmaking activity and help diagnose issues.
Read time 2 minutesLast updated 2 days 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

Access logs

The following instructions explain how to access the Matchmaker logging feature from the Unity Dashboard.
  1. In the Unity Dashboard, open Matchmaker.
  2. 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

FieldThe field you want to filter on, such as 
severityText
, 
body
, or 
logAttributes
.
OperatorOne of the supported operators. Refer to the table of operators below.
ValueThe 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.
GroupingUse 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.