Matchmaker logs
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, open 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 ANDs 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
severityTextfield is also aliased asseverityfor convenience. - Fuzzy match operators (~= and !~=) are only supported for the
bodyfield. - The
LogAttributeskeys are case-sensitive. - The
LogAttributesvalues are automatically converted to string.