How to report a problem

This section describes when, where, and how to ask for help while working with the YTsaurus system. It provides recommendations on writing support requests and bug reports.

Using LLMs to compose requests

You can compose support requests using an LLM. However, keep the following points in mind:

• Do not delegate communication with support to neural networks. YTsaurus support consists of real engineers, and solving a problem requires a dialogue with a person. Meaningful troubleshooting is essential to this dialogue: a live user — not an autonomous agent — must test hypotheses, safely apply proposed solutions, and evaluate their results.

• Check the facts. LLMs often make mistakes, invent nonexistent parameters, or draw incorrect conclusions. Please review generated logs, configurations, and descriptions before sending them. If your ticket or request contains incorrect information, resolving the issue may take longer.

• Remove fluff. Raw text from neural networks often contains many unnecessary details, generic phrases, and complex wording — this makes it harder to identify the problem. Please proofread and edit the generated text: leave only the technical facts, the essence of the issue, and your specific questions.

When to submit a request

The YTsaurus system consists of various components and services, so there are several ways to get help or ask a question.

For each situation, there is a best way to report a problem or ask for help with the system. Choose it before submitting your request — this will reduce the time it takes for the right specialist to receive your request.

Questions can fall into the following categories:

• Web interface issues
• System operation issues
• Development questions
• Other questions

Web interface issues

Report layout problems, data update issues in the web interface, and other similar problems to the mailing list ui@ytsaurus.tech.
Be sure to describe the problem, the expected behavior, and provide the page address.

System operation issues

Questions about the current operation of the YTsaurus system include, but are not limited to:

• Slow data read/write and long computations on the cluster
• Unknown errors when running operations or making queries to the cluster

Send a description of the problem and a minimal example that allows the team to reproduce the issue to the mailing list dev@ytsaurus.tech.

Development questions

This category includes questions about the technology in general and any consultations:

• API and its usage
• Capabilities and limitations
• Questions about ways to optimize computations
• Questions about YTsaurus quota types and the process of obtaining them
• Questions about metric purpose and correct interpretation of graphs
• Questions about estimating required resources
• Questions about error causes and self-diagnosis methods
• Conceptual questions and suggestions

Ask such questions on Stack Overflow with the tag ytsaurus.

Other questions

If your question or problem does not fit into any of the described categories, send an email to the mailing list (mailto:community@ytsaurus.tech).

How to write effective bug reports

The tips below will help you not miss important details in bug reports and describe the situation in its original form, without prior interpretation, in full detail.

Formulating the problem

Before sending a bug report, reread it and put yourself in the shoes of the person who will be helping you. Where would you start solving the problem? Is the information provided sufficient?

Provide more background for performance debugging.

Supporting information

Try to provide raw data. Show the problem and everything related to it in its "raw" form — the YTsaurus service team will make every effort to understand the root cause.

Always show the full error message. In YTsaurus, errors are hierarchical: in addition to the text itself, the error has attributes and nested errors. Do not trim the information — show everything that is available. If trimming occurred before printing, try to figure out why that happened. This might be useful in the future.

If the API you are using trims the information, send an email to the mailing list community@.

Enable logging. Most SDKs provided by YTsaurus use the environment variable YT_LOG_LEVEL. Set its value to debug, collect logs from stderr, and attach them to the bug report. Also consider the following specific circumstances:

• When using the Python library, configure logging through the logging module: logging.getLogger('Yt').setLevel(logging.DEBUG)

• In Java libraries, slf4j is used for logging. Enable debug level for the tech.ytsaurus loggers

• If the problem can be reproduced using local YTsaurus, enable debug logs in it by passing the --enable-debug-logging option when calling yt_local start

The YTsaurus system writes detailed logs on the server side, but if the problem lies, for example, in the network communication between the client and the server, the server logs are useless.

Provide more context:

• Be sure to share as much information about your cluster as possible
• If an operation fails with an error, provide a reproducible example
• If the code crashes due to an exception, attach a backtrace
• If the code terminates with an error and creates a core dump , provide a link to the core dump so it can be downloaded and examined

If the problem can be reproduced, try to find a minimal reproduction example. A minimal reproduction example often helps find an error in the user's code. If your computations depend on additional data (tables, local files), prepare reliable links to them. The YTsaurus service team may need additional data to reproduce the problem independently if they cannot find the cause by reading logs.

Structure and order

Try to separate problems. Do not write about different issues in a single bug report. Write two separate reports.

Self-help

Make maximum use of the tools provided by the system for self-diagnosis.

Read the documentation, especially the FAQ, which is located in a separate section.