1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK
2
3Using the Error Reporting Tool
4******************************
5
6The error reporting tool allows you to submit errors encountered during
7builds to a central database. Outside of the build environment, you can
8use a web interface to browse errors, view statistics, and query for
9errors. The tool works using a client-server system where the client
10portion is integrated with the installed Yocto Project
11:term:`Source Directory` (e.g. ``poky``).
12The server receives the information collected and saves it in a
13database.
14
15There is a live instance of the error reporting server at
16https://errors.yoctoproject.org.
17When you want to get help with build failures, you can submit all of the
18information on the failure easily and then point to the URL in your bug
19report or send an email to the mailing list.
20
21.. note::
22
23   If you send error reports to this server, the reports become publicly
24   visible.
25
26Enabling and Using the Tool
27===========================
28
29By default, the error reporting tool is disabled. You can enable it by
30inheriting the :ref:`ref-classes-report-error` class by adding the
31following statement to the end of your ``local.conf`` file in your
32:term:`Build Directory`::
33
34   INHERIT += "report-error"
35
36By default, the error reporting feature stores information in
37``${``\ :term:`LOG_DIR`\ ``}/error-report``.
38However, you can specify a directory to use by adding the following to
39your ``local.conf`` file::
40
41   ERR_REPORT_DIR = "path"
42
43Enabling error
44reporting causes the build process to collect the errors and store them
45in a file as previously described. When the build system encounters an
46error, it includes a command as part of the console output. You can run
47the command to send the error file to the server. For example, the
48following command sends the errors to an upstream server::
49
50   $ send-error-report /home/brandusa/project/poky/build/tmp/log/error-report/error_report_201403141617.txt
51
52In the previous example, the errors are sent to a public database
53available at https://errors.yoctoproject.org, which is used by the
54entire community. If you specify a particular server, you can send the
55errors to a different database. Use the following command for more
56information on available options::
57
58   $ send-error-report --help
59
60When sending the error file, you are prompted to review the data being
61sent as well as to provide a name and optional email address. Once you
62satisfy these prompts, the command returns a link from the server that
63corresponds to your entry in the database. For example, here is a
64typical link: https://errors.yoctoproject.org/Errors/Details/9522/
65
66Following the link takes you to a web interface where you can browse,
67query the errors, and view statistics.
68
69Disabling the Tool
70==================
71
72To disable the error reporting feature, simply remove or comment out the
73following statement from the end of your ``local.conf`` file in your
74:term:`Build Directory`::
75
76   INHERIT += "report-error"
77
78Setting Up Your Own Error Reporting Server
79==========================================
80
81If you want to set up your own error reporting server, you can obtain
82the code from the Git repository at :yocto_git:`/error-report-web/`.
83Instructions on how to set it up are in the README document.
84
85