144 lines
5.1 KiB
Markdown
144 lines
5.1 KiB
Markdown
collect-logs
|
|
============
|
|
|
|
An Ansible role for aggregating logs from TripleO nodes.
|
|
|
|
Requirements
|
|
------------
|
|
|
|
This 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 with
|
|
[os-loganalyze](https://github.com/openstack-infra/os-loganalyze).
|
|
|
|
Role Variables
|
|
--------------
|
|
|
|
### Collection related
|
|
|
|
* `artcl_collect_list` -- A list of files and directories to gather from
|
|
the target. Directories are collected recursively. Can include joker
|
|
characters that bash understands. Should be specified as a YaML list,
|
|
e.g.:
|
|
|
|
```yaml
|
|
artcl_collect_list:
|
|
- /etc/nova
|
|
- /home/stack/*.log
|
|
- /var/log
|
|
```
|
|
|
|
* `artcl_collect_dir` -- A local directory where the logs should be
|
|
gathered, without a trailing slash.
|
|
* `artcl_gzip_only`: false/true -- When true, gathered files are gzipped one
|
|
by one in `artcl_collect_dir`, when false, a tar.gz file will contain all the
|
|
logs.
|
|
|
|
### Documentation generation related
|
|
|
|
* `artcl_gen_docs`: true/false -- If true, the role will use build artifacts
|
|
and Sphinx and produce user friendly documentation.
|
|
* `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.
|
|
|
|
```yaml
|
|
artcl_create_docs_payload:
|
|
included_deployment_scripts:
|
|
- undercloud-install
|
|
- undercloud-post-install
|
|
included_static_docs:
|
|
- env-setup-virt
|
|
table_of_contents:
|
|
- env-setup-virt
|
|
- undercloud-install
|
|
- undercloud-post-install
|
|
```
|
|
|
|
### Publishing related
|
|
|
|
* `artcl_publish`: true/false -- If true, the role will attempt to rsync logs
|
|
to the target specified by `artcl_rsync_url`. Uses `BUILD_URL`, `BUILD_TAG`
|
|
vars from the environment (set during a Jenkins job run) and requires the
|
|
next to variables to be set.
|
|
* `artcl_use_rsync`: false/true -- use rsync to upload the logs
|
|
* `artcl_rsync_use_daemon`: false/true -- use rsync daemon instead of ssh to connect
|
|
* `artcl_rsync_url` -- rsync target for uploading the logs. The localhost
|
|
needs to have passwordless authentication to the target or the
|
|
`PROVISIONER_KEY` Var specificed in the environment.
|
|
* `artcl_use_swift`: false/true -- use swift object storage to publish the logs
|
|
* `artcl_swift_auth_url` -- the OpenStack auth URL for Swift
|
|
* `artcl_swift_username` -- OpenStack username for Swift
|
|
* `artcl_swift_password` -- password for the Swift user
|
|
* `artcl_swift_tenant_name` -- OpenStack tenant name for Swift
|
|
* `artcl_swift_container` -- the name of the Swift container to use,
|
|
default is `logs`
|
|
* `artcl_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` -- a HTTP URL at which the uploaded logs will be
|
|
accessible after upload.
|
|
* `artcl_collect_sosreport` -- true/false -- If true, create and collect a
|
|
sosreport for each host.
|
|
|
|
Example Playbook
|
|
----------------
|
|
|
|
```yaml
|
|
---
|
|
- name: Gather logs
|
|
hosts: all:!localhost
|
|
roles:
|
|
- collect-logs
|
|
```
|
|
|
|
Templated Bash to rST Conversion Notes
|
|
--------------------------------------
|
|
|
|
Templated bash scripts used during deployment are converted to rST files
|
|
during the `create-docs` portion 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:
|
|
|
|
1. Only lines between `### ---start_docs` and `### ---stop_docs` will be
|
|
parsed.
|
|
2. Lines containing `# nodoc` will be excluded.
|
|
3. Lines containing `## ::` indicate subsequent lines should be formatted
|
|
as code blocks
|
|
4. Other lines beginning with `## <anything else>` will have the prepended
|
|
`## ` removed. This is how and where general rST formatting is added.
|
|
5. All other lines, including shell comments, will be indented by four spaces.
|
|
|
|
Enabling sosreport Collection
|
|
-----------------------------
|
|
|
|
[sosreport](https://github.com/sosreport/sos) is 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 that `artcl_collect_sosreport: true` is set.
|
|
|
|
License
|
|
-------
|
|
|
|
Apache 2.0
|
|
|
|
Author Information
|
|
------------------
|
|
|
|
RDO-CI Team
|