1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
|
Taskcluster Mach commands
=========================
A number of mach subcommands are available aside from ``mach taskgraph
decision`` to make this complex system more accessible to those trying to
understand or modify it. They allow you to run portions of the
graph-generation process and output the results.
``mach taskgraph tasks``
Get the full task set
``mach taskgraph full``
Get the full task graph
``mach taskgraph target``
Get the target task set
``mach taskgraph target-graph``
Get the target task graph
``mach taskgraph optimized``
Get the optimized task graph
``mach taskgraph morphed``
Get the morphed task graph
See :doc:`how-tos` for further practical tips on debugging task-graph mechanics
locally.
Parameters
----------
Each of these commands takes an optional ``--parameters`` argument giving a file
with parameters to guide the graph generation. The decision task helpfully
produces such a file on every run, and that is generally the easiest way to get
a parameter file. The parameter keys and values are described in
:doc:`parameters`; using that information, you may modify an existing
``parameters.yml`` or create your own. The ``--parameters`` option can also
take the following forms:
``project=<project>``
Fetch the parameters from the latest push on that project
``task-id=<task-id>``
Fetch the parameters from the given decision task id
If not specified, parameters will default to ``project=mozilla-central``.
Taskgraph JSON Format
---------------------
By default, the above commands will only output a list of tasks. Use `-J` flag
to output full task definitions. For example:
.. code-block:: shell
$ ./mach taskgraph optimized -J
Task graphs -- both the graph artifacts produced by the decision task and those
output by the ``--json`` option to the ``mach taskgraph`` commands -- are JSON
objects, keyed by label, or for optimized task graphs, by taskId. For
convenience, the decision task also writes out ``label-to-taskid.json``
containing a mapping from label to taskId. Each task in the graph is
represented as a JSON object.
Each task has the following properties:
``kind``
The name of this task's kind
``task_id``
The task's taskId (only for optimized task graphs)
``label``
The task's label
``attributes``
The task's attributes
``dependencies``
The task's in-graph dependencies, represented as an object mapping
dependency name to label (or to taskId for optimized task graphs)
``optimizations``
The optimizations to be applied to this task
``task``
The task's TaskCluster task definition.
The results from each command are in the same format, but with some differences
in the content:
* The ``tasks`` and ``target`` subcommands both return graphs with no edges.
That is, just collections of tasks without any dependencies indicated.
* The ``optimized`` subcommand returns tasks that have been assigned taskIds.
The dependencies array, too, contains taskIds instead of labels, with
dependencies on optimized tasks omitted. However, the ``task.dependencies``
array is populated with the full list of dependency taskIds. All task
references are resolved in the optimized graph.
The output of the ``mach taskgraph`` commands are suitable for processing with
the `jq <https://stedolan.github.io/jq/>`_ utility. For example, to extract all
tasks' labels and their dependencies:
.. code-block:: shell
jq 'to_entries | map({label: .value.label, dependencies: .value.dependencies})'
An alternate way of searching the output of ``mach taskgraph`` is
`gron <https://github.com/tomnomnom/gron>`_, which converts json into a format
that's easily searched with ``grep``
.. code-block:: shell
gron taskgraph.json | grep -E 'test.*machine.platform = "linux64";'
./mach taskgraph --json | gron | grep ...
|
