2.5.14.6. MessageFormatter
This formatter is used to format messages in BuildStatusGenerator and BuildSetStatusGenerator.
It formats a message using the Jinja2 templating language and picks the template either from a string.
The constructor of the class takes the following arguments:
template_typeThis indicates the type of the generated template. Use either ‘plain’ (the default) or ‘html’.
templateIf set, specifies the template used to generate the message body. If not set, a default template will be used. The default template is selected according to
template_typeso it may make sense to specify appropriatetemplate_typeeven if the default template is used.subjectIf set, specifies the template used to generate the message subject. In case of messages generated for multiple builds within a buildset (e.g. from within
BuildSetStatusGenerator), the subject of the first message will be used. Theis_buildsetkey of the context can be used to detect such case and adjust the message appropriately.ctxThis is an extension of the standard context that will be given to the templates. Use this to add content to the templates that is otherwise not available.
Alternatively, you can subclass MessageFormatter and override the
buildAdditionalContextin order to grab more context from the data API.- buildbot.reporters.message.buildAdditionalContext(master, ctx)
- Parameters:
master – the master object
ctx – the context dictionary to enhance
- Returns:
optionally deferred
default implementation will add
self.ctxinto the current template context
want_propertiesThis parameter (defaults to True) will extend the content of the given
buildobject with the Properties from the build.want_stepsThis parameter (defaults to False) will extend the content of the given
buildobject with information about the steps of the build. Use it only when necessary as this increases the overhead in terms of CPU and memory on the master.want_logsThis parameter (defaults to False) will extend the content of the steps of the given
buildobject with the log metadata of each steps from the build. This implieswantStepsto be True. Use it only when mandatory, as this greatly increases the overhead in terms of CPU and memory on the master.want_logs_contentThis parameter (defaults to
False) controls whether to include log content together with log metadata as controlled bywant_logs.Falsedisables log content inclusion.Trueenables log content inclusion for all logs. A list of strings specifies which logs to include. The logs can be included by name; or by step name and log name separated by dot character. If log name is specified, logs with that name will be included regardless of the step it is in. If both step and log names are specified, then logs with that name will be included only from the specific step.want_logs_contentbeing notFalseimplieswant_logs=Trueandwant_steps=True.Enabling want_logs_content dumps the full content of logs and may consume lots of memory and CPU depending on the log size.
extra_info_cbThis parameter (defaults to
None) can be used to customize extra information that is passed to reporters. If set, this argument must be a function that returns a dictionary of dictionaries either directly or via aDeferred. The interpretation of the return value depends on the exact reporter being used.
Context (build)
In the case the message formatter is used to create message for a build the context that is given to the template consists of the following data:
resultsThe results of the build as an integer. Equivalent to
build['results'].result_namesA collection that allows accessing a textual identifier of build result. The intended usage is
result_names[results].The following are possible values:
success,warnings,failure,skipped,exception,retry,cancelled.buildernameThe name of the builder. Equivalent to
build['builder']['name']modeThe mode argument that has been passed to the report generator.
workernameThe name of the worker. Equivalent to the
workernameproperty of the build or<unknown>if it’s not available.buildsetThe
buildsetdictionary from data API.buildThe
builddictionary from data API. Thepropertiesattribute is populated only ifwant_propertiesis set toTrue. It has the following extra properties:builderThe
builderdictionary from the data API that describes the builder of the build.buildrequestThe
buildrequestdictionary from the data API that describes the build request that the build was built for.buildsetThe
buildsetdictionary from the data API that describes the buildset that the build was built for.parentbuildThe
builddictionary from the data API that describes the parent build. This build is identified by theparent_buildidattribute of the buildset.parentbuilderThe
builderdictionary from the data API that describes the builder of the parent build.urlURL to the build in the Buildbot UI.
prev_buildThe
builddictionary from the data API that describes previous build, if any. This attribute is populated only ifwantPreviousBuildis set toTrue.stepsA list of
stepdictionaries from the data API that describe steps in the build, if any. This attribute is populated only ifwantStepsis set toTrue.Additionally, if
want_logsis set toTruethen the step dictionaries will containlogsattribute with a list oflogdictionaries from the data API that describe the logs of the step. The log dictionaries will additionally containurlkey with URL to the log in the web UI as the value.Additionally, if
want_logs_contentis set toTruethen the log dictionaries will containcontentskey with full contents of the log.
is_buildsetA boolean identifying whether the current message will form a larger message that describes multiple builds in a buildset. This mostly concerns generation of the subject as the message bodies will be merged.
projectsA string identifying the projects that the build was built for.
previous_resultsResults of the previous build, if available, otherwise
None.status_detectedString that describes the build in terms of current build results, previous build results and
mode.build_urlURL to the build in the Buildbot UI.
buildbot_titleThe title of the Buildbot instance as per
c['title']from themaster.cfgbuildbot_urlThe URL of the Buildbot instance as per
c['buildbotURL']from themaster.cfgblamelistThe list of users responsible for the build.
summaryA string that summarizes the build result.
sourcestampsA string identifying the source stamps for which the build was made.
Context (buildset)
In the case the message formatter is used to create message for an buildset itself (see
BuildSetCombinedStatusGenerator), the context that is given to the template consists of the
following data:
resultsThe results of the buildset as an integer. Equivalent to
build['results'].result_namesA collection that allows accessing a textual identifier of build result. The intended usage is
result_names[results].The following are possible values:
success,warnings,failure,skipped,exception,retry,cancelled.modeThe mode argument that has been passed to the report generator.
buildsetThe
buildsetdictionary from data API.buildsA list of
builddictionaries from data API. The builds are part of the buildset that is being formatted.is_buildsetAlways
True.projectsA string identifying the projects that the buildset was built for.
status_detectedString that describes the build in terms of current buildset results, previous build results and
mode.buildbot_titleThe title of the Buildbot instance as per
c['title']from themaster.cfgbuildbot_urlThe URL of the Buildbot instance as per
c['buildbotURL']from themaster.cfgblamelistThe list of users responsible for the buildset.
sourcestampsA string identifying the source stamps for which the buildset was made.
Examples
The following examples describe how to get some useful pieces of information from the various data objects:
- Name of the builder that generated this event
{{ buildername }}- Title of the BuildMaster
{{ projects }}- MailNotifier mode
{{ mode }}(a combination ofchange,failing,passing,problem,warnings,exception,all)- URL to build page
{{ build_url }}- URL to Buildbot main page
{{ buildbot_url }}- Status of the build as string.
This require extending the context of the Formatter via the
ctxparameter with:ctx={"statuses": util.Results}.{{ statuses[results] }}- Build text
{{ build['state_string'] }}- Mapping of property names to (values, source)
{{ build['properties'] }}- For instance the build reason (from a forced build)
{{ build['properties']['reason'][0] }}- Worker name
{{ workername }}- List of responsible users
{{ blamelist | join(', ') }}