Package: ansible-role-collect-logs
Ansible role for aggregating logs from different nodes.The only supported way to call this role is using its main entry point. Do not
usetasks_fromas this count as using private interfaces.RequirementsThis role gathers logs and debug information from a target system and
collates them in a designated directory,artcl_collect_dir, on the
localhost.Additionally, the role will convert templated bash scripts, created and
used by TripleO-Quickstart during deployment, into rST files. These rST
files are combined with static rST files and fed into Sphinx to create
user friendly post-build-documentation specific to an original
deployment.Finally, the role optionally handles uploading these logs to a rsync
server or to an OpenStack Swift object storage. Logs from Swift can be
exposed withos-loganalyze.Role VariablesFile Collectionartcl_collect_list– A list of files and directories to gather
from the target. Directories are collected recursively and need to
end with a ‘/’ to get collected. Should be specified as a YaML list,
e.g.:artcl_collect_list:-/etc/nova/-/home/stack/*.log-/var/log/artcl_collect_list_append– A list of files and directories to be
appended in the default list. This is useful for users that want to
keep the original list and just add more relevant paths.artcl_exclude_list– A list of files and directories to exclude
from collecting. This list is passed to rsync as an exclude filter
and it takes precedence over the collection list. For details see the
‘FILTER RULES’ topic in the rsync man page.artcl_exclude_list_append– A list of files and directories to be
appended in the default exclude list. This is useful for users that want to
keep the original list and just add more relevant paths.artcl_collect_dir– A local directory where the logs should be
gathered, without a trailing slash.collect_log_types- A list of which type of logs will be collected,
such as openstack logs, network logs, system logs, etc.
Acceptable values are system, monitoring, network, openstack and container.artcl_gzip: Archive files, disabled by default.artcl_rsync_collect_list- if true, a rsync filter file is generated forrsyncto collect files, if false,findis used to generate list
of files to collect forrsync.findbrings some benefits like
searching for files in a certain depth (artcl_find_maxdepth) or up to
certain size (artcl_find_max_size).artcl_find_maxdepth- Number of levels of directories below the starting
points, default is 4. Note: this variable is applied only whenartcl_rsync_collect_listis set to false.artcl_find_max_size- Max size of a file in MBs to be included in find
search, default value is 256. Note: this variable is applied only whenartcl_rsync_collect_listis set to false.artcl_commands_extras- A nested dictionary of additional commands to be
run during collection. First level contains the group type, as defined bycollect_log_typeslist which determines which groups are collected and
which ones are skipped.Defined keys will override implicit ones from defaultsartcl_commandswhich is not expected to be changed by user.Second level keys are used to uniqly identify a command and determine the
default output filename, unless is mentioned viacapture_fileproperty.cmdcontains the shell command that would be run.artcl_commands_extras:system:disk-space:cmd:df# will save output to /var/log/extras/dist-space.logmounts:cmd:mount -acapture_file:/mounts.txt# <-- custom capture file locationopenstack:key2:cmd:touch /foo.txtcapture_disable:true# <-- disable implicit std redirectionwhen:"1>2"# <-- optional conditionDocumentation generation relatedartcl_gen_docs: false/true – If true, the role will use build
artifacts and Sphinx and produce user friendly documentation
(default: false)artcl_docs_source_dir– a local directory that serves as the
Sphinx source directory.artcl_docs_build_dir– A local directory that serves as the
Sphinx build output directory.artcl_create_docs_payload– Dictionary of lists that direct what
and how to construct documentation.included_deployment_scripts– List of templated bash scripts
to be converted to rST files.included_deployment_scripts– List of static rST files that
will be included in the output documentation.table_of_contents– List that defines the order in which rST
files will be laid out in the output documentation.artcl_verify_sphinx_build– false/true – If true, verify items
defined inartcl_create_docs_payload.table_of_contentsexist in
sphinx generated index.html (default: false)artcl_create_docs_payload:included_deployment_scripts:-undercloud-install-undercloud-post-installincluded_static_docs:-env-setup-virttable_of_contents:-env-setup-virt-undercloud-install-undercloud-post-installPublishing relatedartcl_publish: true/false – If true, the role will attempt to
rsync logs to the target specified byartcl_rsync_url. UsesBUILD_URL,BUILD_TAGvars from the environment (set during a
Jenkins job run) and requires the next to variables to be set.artcl_txt_rename: false/true – rename text based file to end in
.txt.gz to make upstream log servers display them in the browser
instead of offering them to downloadartcl_publish_timeout: the maximum seconds the role can spend
uploading the logs, the default is 1800 (30 minutes)artcl_use_rsync: false/true – use rsync to upload the logsartcl_rsync_use_daemon: false/true – use rsync daemon instead of
ssh to connectartcl_rsync_url– rsync target for uploading the logs. The
localhost needs to have passwordless authentication to the target or
thePROVISIONER_KEYvar specified in the environment.artcl_use_swift: false/true – use swift object storage to publish
the logsartcl_swift_auth_url– the OpenStack auth URL for Swiftartcl_swift_username– OpenStack username for Swiftartcl_swift_password– password for the Swift userartcl_swift_tenant_name– OpenStack tenant (project) name for Swiftartcl_swift_container– the name of the Swift container to use,
default islogsartcl_swift_delete_after– The number of seconds after which
Swift will remove the uploaded objects, the default is 2678400
seconds = 31 days.artcl_artifact_url– An HTTP URL at which the uploaded logs will
be accessible after upload.artcl_report_server_key- A path to a key for an access to the report
server.Ara relatedara_enabled: true/false - If true, the role will generate ara reports.ara_overcloud_db_path: Path to ara overcloud path (tripleo only).ara_generate_html: true/false - Generate ara html.ara_graphite_prefix: Ara prefix to be used in graphite.ara_only_successful_tasks: true/false - Send to graphite only successfull
tasks.ara_tasks_map: Dictionary with ara tasks to be mapped on graphite.Logs parsing“Sova” module parses logs for known patterns and returns messages that were
found. Patterns are tagged by issues types, like “infra”, “code”, etc.
Patterns are located in file sova-patterns.yml in vars/ directory.config- patterns loaded from filefiles- files and patterns sections matchresult- path to file to write a result of parsingresult_file_dir- directory to write a file with patterns in nameExample of usage of “sova” module:----name:Run sova tasksova:config:"{{pattern_config}}"files:console:"{{ansible_user_dir}}/workspace/logs/quickstart_install.log"errors:"/var/log/errors.txt""ironic-conductor":"/var/log/containers/ironic/ironic-conductor.log"syslog:"/var/log/journal.txt"logstash:"/var/log/extra/logstash.txt"result:"{{ansible_user_dir}}/workspace/logs/failures_file"result_file_dir:"{{ansible_user_dir}}/workspace/logs"Example Role Playbook----name:Gather logshosts:all:!localhostroles:-collect_logs** Note:The tasks that collect data from the nodes are executed with ignore_errors.
Forexample:Templated Bash to rST Conversion NotesTemplated bash scripts used during deployment are converted to rST files
during thecreate-docsportion of the role’s call. Shell scripts are
fed into an awk script and output as restructured text. The awk script
has several simple rules:Only lines between###---start_docsand###---stop_docswill be parsed.Lines containing# nodocwill be excluded.Lines containing## ::indicate subsequent lines should be
formatted as code blocksOther lines beginning with## <anything else>will have the
prepended##removed. This is how and where general rST
formatting is added.All other lines, including shell comments, will be indented by four
spaces.Enabling sosreport Collectionsosreportis a unified tool for
collecting system logs and other debug information. To enable creation
of sosreport(s) with this role, create a custom config (you can use
centosci-logs.yml as a template) and ensure thatartcl_collect_sosreport: trueis set.Sanitizing Log StringsLogs can contain senstive data such as private links and access
passwords. The ‘collect’ task provides an option to replace
private strings with sanitized strings to protect private data.The ‘sanitize_log_strings’ task makes use of the Ansible ‘replace’
module and is enabled by defining asanitize_linesvariable as shown in the example below:---sanitize_lines:-dir_path:'/tmp/{{inventory_hostname}}/etc/repos/'file_pattern:'*'orig_string:'^(.*)download(.*)$'sanitized_string:'SANITIZED_STR_download'-dir_path:'/tmp/{{inventory_hostname}}/home/zuul/'file_pattern:'*'orig_string:'^(.*)my_private_host\.com(.*)$'sanitized_string:'SANITIZED_STR_host'The task searches for files containing the sensitive strings
(orig_string) within a file path, and then replaces the sensitive
strings in those files with the sanitized_string.Usage with InfraRedRun the following steps to execute the role withinfrared.Install infrared and add ansible-role-collect-logs plugin by providing
the url to this repo:(infrared)$ ir plugin add https://opendev.org/openstack/ansible-role-collect-logs.git --src-path infrared_pluginVerify that the plugin is imported by:(infrared)$ ir plugin listRun the plugin:(infrared)$ ir ansible-role-collect-logsLicenseApache 2.0Author InformationRDO-CI Team