Matchmaking X-ray guide
Overview
The AccelByte Gaming Services (AGS) Matchmaking X-ray tool provides game developers with visibility into the matchmaking process. With this tool, you can observe how tickets are matched, along with the factors, conditions, and circumstances influencing the process until a match is formed. This enhanced visibility allows for a comprehensive understanding of the matchmaking process.
This article covers the AGS Matchmaking X-ray tool in detail.
Why do you need X-ray?
The X-ray tool helps alleviate issues like the following:
Lack of visibility: Without comprehensive tools, it's challenging to gain insights into the status of matchmaking processes. The X-ray tool addresses this by providing two primary sections: the X-ray overview and the X-ray timeline. These sections offer both high-level and detailed views of matchmaking events, ensuring visibility at every stage of the process.
Difficulty in monitoring performance: Monitoring the performance of matchmaking processes can be time-consuming and complex. The X-ray overview section of the X-Ray tool presents matchmaking metrics in a concise format, allowing users to quickly assess performance without extensive manual analysis. This enables timely adjustments and optimizations to improve overall efficiency.
Inability to identify issues: Without detailed insights into matchmaking events, it's challenging to pinpoint where the specific issues or bottlenecks are in the process. The X-ray timeline section of the X-ray tool offers a chronological view of matchmaking events, including the identification of unpicked tickets and detailed matchmaking outcomes. This enables users to identify and address issues promptly, leading to smoother operations and better user experiences.
Lack of flexibility in analyses: Limited search options make it difficult to conduct targeted analysis and troubleshooting. The X-Ray tool allows users to conduct searches based on various criteria, such as Match ID, Match Pool, Ticket ID, and User ID, providing flexibility in analysis. This facilitates swift identification of specific information and the streamlining of troubleshooting.
Glossary
| Term | Definition |
|---|---|
| Matchmaking ruleset | The set of predefined criteria and parameters that dictate how the matchmaking process operates within a gaming environment. Matchmaking rulesets define various aspects, such as acceptable player skill levels, preferred game modes, and other conditions that influence the formation of matches. |
| Metrics | Quantitative measures used to assess and evaluate the performance and effectiveness of the matchmaking process. These metrics include various parameters such as total tickets created, total matches formed, average player counts per session, and average match length, among others. |
| Match ID | A unique identifier assigned to each match formed during the matchmaking process. Match IDs allow for easy tracking and referencing of individual matches within the system. |
| Match Pool | A specific variant or configuration of gameplay offering distinct rules and various matchmaking configurations. Each match pool provides a unique gaming experience, catering to different player preferences and styles of play. |
| Ticket ID | A unique identifier assigned to each matchmaking ticket created by players seeking to join a game session. Ticket IDs facilitate tracking and management of individual matchmaking requests within the system. |
| Worker | A unique identifier assigned to each matchmaking process that happened within the system. |
| Ticket Observability | A feature that allows the X-ray tool to track individual matchmaking tickets throughout the matchmaking process. By enabling ticket observability, developers gain insights into how tickets are processed and matched, facilitating debugging and optimization of the matchmaking system. |
| P99 of Matchmaking | A statistical metric that represents the time it takes for the 99th percentile of matchmaking requests to be processed. |
| Unmatched ticket | A ticket within the matchmaking system that has not yet been successfully matched with other players or game sessions. Unpicked tickets may remain in the matchmaking pool for various reasons, such as insufficient player availability or mismatches in skill levels. |
| Average Acquiring DS Wait Time | The average amount of time players spend waiting to connect to a dedicated server (DS) after a match has been formed. |
| Ticket Cancellation | The process of canceling a matchmaking ticket initiated by a player. Ticket cancellations may occur due to player preferences, changes in availability, or other factors, resulting in the removal of the ticket from the matchmaking pool. |
| Queuing Tickets | Tickets within the matchmaking system that are currently awaiting processing and matching with other players or game sessions. Queuing tickets represent active matchmaking requests initiated by players seeking to join multiplayer matches. |
| Expired Tickets | Tickets within the matchmaking system that have exceeded a predefined timeout period without successfully finding a match. Expired tickets are removed from the matchmaking pool and may require players to reinitiate matchmaking requests. |
Features
Within the X-ray tool, visibility is facilitated through two primary sections. The first section, known as the X-ray overview section, presents matchmaking metrics at a high level, allowing you to quickly grasp the status of their matchmaking processes. The second section, the x-ray timeline section, offers a detailed chronological view of matchmaking events, from queuing tickets to obtaining matches, including the identification of unpicked tickets during the matchmaking process, and the presentation of detailed matchmaking outcomes. You can conduct searches based on various criteria, such as Match ID, Match Pool, Ticket ID, and User ID
For the matchmaking X-ray to be able to track the ticket, you will need to add this parameter "ticket_observability_enable": true in your matchmaking ruleset.
While this feature is indispensable for debugging and gaining insights into matchmaking behavior, its implementation may incur additional expenses due to the intensive monitoring and tracking involved. Therefore, it's advisable to evaluate the trade-offs and ensure that your infrastructure can accommodate the increased workload before activating this feature.
Please note that enabling the X-ray setting on or off won't change how the game itself works. Instead, it's there to help developers find and fix any issues that might pop up during matchmaking.
X-ray overview section
The X-ray overview section offers a quick summary of your matchmaking status. It includes various metrics: total tickets created (including canceled and successfully matched ones), the number of active multiplayer sessions and their average player count, and session durations. Additionally, it features a dashboard displaying the 99th percentile (P99) and average queue times for tickets to find a match, as well as the wait time for players to connect to dedicated servers.
- Ticket Created
- Total Ticket Created: The overall count of tickets created within the specified time period.
- Total Match Created: The total number of matches created during a specific time frame.
- Total Ticket Canceled: The total number of tickets that were initiated but subsequently canceled or expired.
- Active Multiplayer Session
- Total Active Multiplayer Session: The total number of active multiplayer gaming sessions within the specified time frame.
- Average Player Per Session: The average number of players participating in each multiplayer gaming session.
- Average Match Length: The average duration of game sessions.
- Matchmaking Time
- P99 of matchmaking: The time it takes for the 99th request to be processed.
- Average matchmaking time: The time it takes in an average of the matchmaking process from the player creating a ticket until the ticket is matched.
- Average Acquiring DS Wait Time
- Successful acquiring DS: The total number of sessions that successfully acquired a DS.
- Failed acquiring DS: The total number of sessions that encountered a failure in acquiring a DS despite the match being formed.
X-ray timeline section
The X-ray timeline section provides a comprehensive overview of matchmaking activities. Here, game developers can search for specific users, matches, game modes, or tickets involved in the matchmaking process. The page offers detailed timestamps, ticket statuses, requested game modes and rulesets, and information on whether tickets are matched, queued back into the pool, or expired (due to timeout configurations). This feature offers valuable insights into how tickets are matched and the overall matchmaking process, allowing users to observe the number and types of tickets processed within each cycle.
Search by User ID
In this section, you can search for a user ID, view a list of requested ticket IDs associated with that user, and identify the worker responsible for processing each request. Additionally, you can expand individual ticket IDs to access detailed information, including ticket specifics, involved players, ticket history, and JSON data of the tickets.
Search by Ticket ID
In this section, users can search by a ticket ID to track the progress and status of their tickets. By entering a specific ticket ID, you can view the journey of their ticket, including its current status and any ongoing processes. Additionally, users can access details such as the request body/payload, ticket histories, flex status, reasons for non-backfilling, and explanations for unmatched tickets.
Search by Match ID
In this section, you can search for a match ID to access information about the matchmaking process. Additionally, users can view details about the workers involved, leading to a page with comprehensive match worker details, allowing them to identify other tickets being processed simultaneously. Furthermore, this section includes requested region data, providing insights into the requested region for the match.
Search by Match pool
In this section, you can search by a match pool to gain insight into the number of input tickets, created matches, and unmatched tickets within specific time frames. This feature is commonly used during periods of low concurrent users (CCU) to understand the volume of processed tickets at specific times.
Example use cases
The following outlines some example scenarios of how and when to use the AGS Matchmaking X-ray tool.
The player cannot find a match even though they meet all the necessary requirements
Detailed problem statement: The player attempts to enter the matchmaking queue yet encounters ongoing challenges as matches fail to initiate despite adherence to all necessary conditions.
Previous debug approach:
- Compare the player ticket with the ruleset to ensure the correct parameters are sent.
- Verify, either through sampling or log analysis, if other players have experienced similar issues.
- Reproduce the steps to understand and resolve the issue.
- Confirm whether the player ticket is processed or if the matchmaking system received the request.
X-ray utilization:
- Visit the overview page to monitor the current status of matchmaking, identifying any potential service outages or individual player issues.
- Access the timeline page to search for the user ID or ticket ID.
- Review detailed information on the specific user and whether his ticket is processed or not along with the reason why it couldn’t match (e.g., a low pool of super-high Matchmaking Rating (MMR) with mismatching players in queue)
The matchmaker fails to place players within the same session
Detailed problem statement: The matchmaker's inability to group players into the same gaming session results in fragmented multiplayer experiences, even when players of similar skill levels queue simultaneously with the expectation of being matched together.
Previous debug approach:
- Cross-reference the player ticket with other players expected to join the same session.
- Verify if the requested game mode supports backfilling, assessing the likelihood of a player backfilling other sessions while another player creates a new session due to session capacity constraints.
- Analyze how the two players queued for matchmaking and examine the chronological log entries.
- Debug more thoroughly by going deep into the logs to see if matchmaking is being processed under the same tick, as there would have been no way to know this beforehand.
X-ray utilization:
- Access the timeline page to search details of each user ticket ID.
- Check if both tickets have the same matchTickID.
- If they do, open the details of the specific matchTickID and review the data of all tickets being processed in a specific matchTickID.
- If they don't, pinpoint that the ticket is being processed in a different matchmaking tick, which can explain how it is not being matched with each other (e.g. the matchmaking queue is crowded and it only has a small possibility for the two to be matched in a same game session).