osloreports(1)

OSLOREPORTS(1) oslo.reports OSLOREPORTS(1)

NAME

osloreports - oslo.reports 3.6.0

oslo.reports library

CONTENTS

Installation

At the command line:

$ pip install oslo.reports


Contributing

If you would like to contribute to the development of oslo's libraries, first you must take a look to this page:

https://specs.openstack.org/openstack/oslo-specs/specs/policy/contributing.html


If you would like to contribute to the development of OpenStack, you must follow the steps in this page:

https://docs.openstack.org/infra/manual/developers.html


If you already have a good understanding of how the system works and your OpenStack accounts are set up, you can skip to the development workflow section of this documentation to learn how changes to OpenStack should be submitted for review via the Gerrit tool:

https://docs.openstack.org/infra/manual/developers.html#development-workflow


Pull requests submitted through GitHub will be ignored.

Bugs should be filed on Launchpad, not GitHub:

https://bugs.launchpad.net/oslo.reports


Using oslo.reports

Usage

Every long running service process should have a call to install a signal handler which will trigger the guru meditation framework upon receipt of SIGUSR1/SIGUSR2. This will result in the process dumping a complete report of its current state to stderr.

For RPC listeners, it may also be desirable to install some kind of hook in the RPC request dispatcher that will save a guru meditation report whenever the processing of a request results in an uncaught exception. It could save these reports to a well known directory (/var/log/openstack/<project>/<service>/) for later analysis by the sysadmin or automated bug analysis tools.

To use oslo.reports in a project, you need to add the following call to setup_autorun() somewhere really early in the startup sequence of the process:

from oslo_reports import guru_meditation_report as gmr
gmr.TextGuruMeditation.setup_autorun(version='13.0.0')


Note that the version parameter is the version of the component itself.

To trigger the report to be generated:

kill -SIGUSR2 <process_id>


NOTE:

On SELinux platforms the report process may fail with an AccessDenied exception. If this happens, temporarily disable SELinux enforcement by running sudo setenforce 0, trigger the report, then turn SELinux back on by running sudo setenforce 1.


Here is a sample report:

========================================================================
====                        Guru Meditation                         ====
========================================================================
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
========================================================================
====                            Package                             ====
========================================================================
product = OpenStack Nova
vendor = OpenStack Foundation
version = 13.0.0
========================================================================
====                            Threads                             ====
========================================================================
------                  Thread #140417215547200                   ------
/usr/local/lib/python2.7/dist-packages/eventlet/hubs/hub.py:346 in run

`self.wait(sleep_time)` /usr/local/lib/python2.7/dist-packages/eventlet/hubs/poll.py:82 in wait
`sleep(seconds)` ======================================================================== ==== Green Threads ==== ======================================================================== ------ Green Thread ------ /usr/local/bin/nova-api:10 in <module>
`sys.exit(main())` /opt/stack/nova/nova/cmd/api.py:57 in main
`launcher.wait()` /usr/local/lib/python2.7/dist-packages/oslo_service/service.py:511 in wait
`self._respawn_children()` /usr/local/lib/python2.7/dist-packages/oslo_service/service.py:495 in _respawn_children
`eventlet.greenthread.sleep(self.wait_interval)` /usr/local/lib/python2.7/dist-packages/eventlet/greenthread.py:34 in sleep
`hub.switch()` /usr/local/lib/python2.7/dist-packages/eventlet/hubs/hub.py:294 in switch
`return self.greenlet.switch()` ------ Green Thread ------ No Traceback! ======================================================================== ==== Processes ==== ======================================================================== Process 14756 (under 1) [ run by: stack (1001), state: running ]
Process 14770 (under 14756) [ run by: stack (1001), state: sleeping ]
Process 14771 (under 14756) [ run by: stack (1001), state: sleeping ]
Process 14776 (under 14756) [ run by: stack (1001), state: sleeping ]
Process 14777 (under 14756) [ run by: stack (1001), state: sleeping ]
Process 14784 (under 14756) [ run by: stack (1001), state: sleeping ]
Process 14785 (under 14756) [ run by: stack (1001), state: sleeping ] ======================================================================== ==== Configuration ==== ======================================================================== api_database:
connection = ***
connection_debug = 0
connection_trace = False
idle_timeout = 3600
max_overflow = None
max_pool_size = None
max_retries = 10
mysql_sql_mode = TRADITIONAL
pool_timeout = None
retry_interval = 10
slave_connection = ***
sqlite_synchronous = True cells:
bandwidth_update_interval = 600
call_timeout = 60
capabilities =
hypervisor=xenserver;kvm
os=linux;windows
cell_type = compute
enable = False
instance_update_sync_database_limit = 100
manager = nova.cells.manager.CellsManager
mute_child_interval = 300
name = nova
reserve_percent = 10.0
topic = cells cinder:
cafile = None
catalog_info = volumev2:cinderv2:publicURL
certfile = None
cross_az_attach = True
endpoint_template = None
http_retries = 3
insecure = False
keyfile = None
os_region_name = RegionOne
timeout = None conductor:
manager = nova.conductor.manager.ConductorManager
topic = conductor
use_local = False
workers = 2 database:
backend = sqlalchemy
connection = ***
connection_debug = 0
connection_trace = False
db_inc_retry_interval = True
db_max_retries = 20
db_max_retry_interval = 10
db_retry_interval = 1
idle_timeout = 3600
max_overflow = None
max_pool_size = None
max_retries = 10
min_pool_size = 1
mysql_sql_mode = TRADITIONAL
pool_timeout = None
retry_interval = 10
slave_connection = ***
sqlite_db = nova.sqlite
sqlite_synchronous = True
use_db_reconnect = False
use_tpool = False default:
allow_instance_snapshots = True
allow_resize_to_same_host = True
allow_same_net_traffic = True
api_paste_config = /etc/nova/api-paste.ini
api_rate_limit = False
auth_strategy = keystone
auto_assign_floating_ip = False
bandwidth_poll_interval = 600
bindir = /usr/local/bin
block_device_allocate_retries = 60
block_device_allocate_retries_interval = 3
boot_script_template = /opt/stack/nova/nova/cloudpipe/bootscript.template
ca_file = cacert.pem
ca_path = /opt/stack/data/nova/CA
cert_manager = nova.cert.manager.CertManager
cert_topic = cert
client_socket_timeout = 900
cnt_vpn_clients = 0
compute_available_monitors = None
compute_driver = libvirt.LibvirtDriver
compute_manager = nova.compute.manager.ComputeManager
compute_monitors =
compute_resources =
vcpu
compute_stats_class = nova.compute.stats.Stats
compute_topic = compute
config-dir = None
config-file =
/etc/nova/nova.conf
config_drive_format = iso9660
config_drive_skip_versions = 1.0 2007-01-19 2007-03-01 2007-08-29 2007-10-10 2007-12-15 2008-02-01 2008-09-01
console_host = dims-ubuntu
console_manager = nova.console.manager.ConsoleProxyManager
console_topic = console
consoleauth_manager = nova.consoleauth.manager.ConsoleAuthManager
consoleauth_topic = consoleauth
control_exchange = nova
cpu_allocation_ratio = 0.0
create_unique_mac_address_attempts = 5
crl_file = crl.pem
db_driver = nova.db
debug = True
default_access_ip_network_name = None
default_availability_zone = nova
default_ephemeral_format = ext4
default_flavor = m1.small
default_floating_pool = public
default_log_levels =
amqp=WARN
amqplib=WARN
boto=WARN
glanceclient=WARN
iso8601=WARN
keystonemiddleware=WARN
oslo_messaging=INFO
qpid=WARN
requests.packages.urllib3.connectionpool=WARN
routes.middleware=WARN
sqlalchemy=WARN
stevedore=WARN
suds=INFO
urllib3.connectionpool=WARN
websocket=WARN
default_notification_level = INFO
default_publisher_id = None
default_schedule_zone = None
defer_iptables_apply = False
dhcp_domain = novalocal
dhcp_lease_time = 86400
dhcpbridge = /usr/local/bin/nova-dhcpbridge
dhcpbridge_flagfile =
/etc/nova/nova.conf
dmz_cidr =
dmz_mask = 255.255.255.0
dmz_net = 10.0.0.0
dns_server =
dns_update_periodic_interval = -1
dnsmasq_config_file =
ebtables_exec_attempts = 3
ebtables_retry_interval = 1.0
ec2_dmz_host = 10.0.0.9
ec2_host = 10.0.0.9
ec2_listen = 0.0.0.0
ec2_listen_port = 8773
ec2_path = /
ec2_port = 8773
ec2_private_dns_show_ip = False
ec2_scheme = http
ec2_strict_validation = True
ec2_timestamp_expiry = 300
ec2_workers = 2
enable_instance_password = True
enable_network_quota = False
enable_new_services = True
enabled_apis =
ec2
metadata
osapi_compute
enabled_ssl_apis =
fake_call = False
fake_network = False
fatal_deprecations = False
fatal_exception_format_errors = False
firewall_driver = nova.virt.firewall.NoopFirewallDriver
fixed_ip_disassociate_timeout = 600
fixed_range_v6 = fd00::/48
flat_injected = False
flat_interface = None
flat_network_bridge = None
flat_network_dns = 8.8.4.4
floating_ip_dns_manager = nova.network.noop_dns_driver.NoopDNSDriver
force_config_drive = True
force_dhcp_release = True
force_raw_images = True
force_snat_range =
forward_bridge_interface =
all
fping_path = /usr/sbin/fping
gateway = None
gateway_v6 = None
heal_instance_info_cache_interval = 60
host = dims-ubuntu
image_cache_manager_interval = 2400
image_cache_subdirectory_name = _base
image_decryption_dir = /tmp
injected_network_template = /opt/stack/nova/nova/virt/interfaces.template
instance_build_timeout = 0
instance_delete_interval = 300
instance_dns_domain =
instance_dns_manager = nova.network.noop_dns_driver.NoopDNSDriver
instance_format = [instance: %(uuid)s]
instance_name_template = instance-%08x
instance_usage_audit = False
instance_usage_audit_period = month
instance_uuid_format = [instance: %(uuid)s]
instances_path = /opt/stack/data/nova/instances
internal_service_availability_zone = internal
iptables_bottom_regex =
iptables_drop_action = DROP
iptables_top_regex =
ipv6_backend = rfc2462
key_file = private/cakey.pem
keys_path = /opt/stack/data/nova/keys
keystone_ec2_insecure = False
keystone_ec2_url = http://10.0.0.9:5000/v2.0/ec2tokens
l3_lib = nova.network.l3.LinuxNetL3
linuxnet_interface_driver =
linuxnet_ovs_integration_bridge = br-int
live_migration_retry_count = 30
lockout_attempts = 5
lockout_minutes = 15
lockout_window = 15
log-config-append = None
log-date-format = %Y-%m-%d %H:%M:%S
log-dir = None
log-file = None
log-format = None
log_options = True
logging_context_format_string = %(asctime)s.%(msecs)03d %(color)s%(levelname)s %(name)s [%(request_id)s %(user_name)s %(project_name)s%(color)s] %(instance)s%(color)s%(message)s
logging_debug_format_suffix = from (pid=%(process)d) %(funcName)s %(pathname)s:%(lineno)d
logging_default_format_string = %(asctime)s.%(msecs)03d %(color)s%(levelname)s %(name)s [-%(color)s] %(instance)s%(color)s%(message)s
logging_exception_prefix = %(color)s%(asctime)s.%(msecs)03d TRACE %(name)s %(instance)s
max_age = 0
max_concurrent_builds = 10
max_concurrent_live_migrations = 1
max_header_line = 16384
max_local_block_devices = 3
maximum_instance_delete_attempts = 5
memcached_servers = None
metadata_cache_expiration = 15
metadata_host = 10.0.0.9
metadata_listen = 0.0.0.0
metadata_listen_port = 8775
metadata_manager = nova.api.manager.MetadataManager
metadata_port = 8775
metadata_workers = 2
migrate_max_retries = -1
mkisofs_cmd = genisoimage
monkey_patch = False
monkey_patch_modules =
nova.api.ec2.cloud:nova.notifications.notify_decorator
nova.compute.api:nova.notifications.notify_decorator
multi_host = False
my_block_storage_ip = 10.0.0.9
my_ip = 10.0.0.9
network_allocate_retries = 0
network_api_class = nova.network.neutronv2.api.API
network_device_mtu = None
network_driver = nova.network.linux_net
network_manager = nova.network.manager.VlanManager
network_size = 256
network_topic = network
networks_path = /opt/stack/data/nova/networks
neutron_default_tenant_id = default
non_inheritable_image_properties =
bittorrent
cache_in_nova
notification_driver =
notification_topics =
notifications
notify_api_faults = False
notify_on_state_change = None
null_kernel = nokernel
num_networks = 1
osapi_compute_ext_list =
osapi_compute_extension =
nova.api.openstack.compute.legacy_v2.contrib.standard_extensions
osapi_compute_link_prefix = None
osapi_compute_listen = 0.0.0.0
osapi_compute_listen_port = 8774
osapi_compute_unique_server_name_scope =
osapi_compute_workers = 2
osapi_glance_link_prefix = None
osapi_hide_server_address_states =
building
osapi_max_limit = 1000
ovs_vsctl_timeout = 120
password_length = 12
pci_alias =
pci_passthrough_whitelist =
periodic_enable = True
periodic_fuzzy_delay = 60
policy_default_rule = default
policy_dirs =
policy.d
policy_file = policy.json
preallocate_images = none
project_cert_subject = /C=US/ST=California/O=OpenStack/OU=NovaDev/CN=project-ca-%.16s-%s
public_interface = eth0
publish_errors = False
pybasedir = /opt/stack/nova
quota_cores = 20
quota_driver = nova.quota.DbQuotaDriver
quota_fixed_ips = -1
quota_floating_ips = 10
quota_injected_file_content_bytes = 10240
quota_injected_file_path_length = 255
quota_injected_files = 5
quota_instances = 10
quota_key_pairs = 100
quota_metadata_items = 128
quota_networks = 3
quota_ram = 51200
quota_security_group_rules = 20
quota_security_groups = 10
quota_server_group_members = 10
quota_server_groups = 10
ram_allocation_ratio = 0.0
reboot_timeout = 0
reclaim_instance_interval = 0
region_list =
remove_unused_base_images = True
remove_unused_original_minimum_age_seconds = 86400
report_interval = 10
rescue_timeout = 0
reservation_expire = 86400
reserved_host_disk_mb = 0
reserved_host_memory_mb = 512
resize_confirm_window = 0
resize_fs_using_block_device = False
resume_guests_state_on_host_boot = False
rootwrap_config = /etc/nova/rootwrap.conf
routing_source_ip = 10.0.0.9
rpc_backend = rabbit
rpc_response_timeout = 60
run_external_periodic_tasks = True
running_deleted_instance_action = reap
running_deleted_instance_poll_interval = 1800
running_deleted_instance_timeout = 0
s3_access_key = notchecked
s3_affix_tenant = False
s3_host = 10.0.0.9
s3_port = 3333
s3_secret_key = notchecked
s3_use_ssl = False
scheduler_available_filters =
nova.scheduler.filters.all_filters
scheduler_default_filters =
AvailabilityZoneFilter
ComputeCapabilitiesFilter
ComputeFilter
DiskFilter
ImagePropertiesFilter
RamFilter
RetryFilter
ServerGroupAffinityFilter
ServerGroupAntiAffinityFilter
scheduler_instance_sync_interval = 120
scheduler_manager = nova.scheduler.manager.SchedulerManager
scheduler_max_attempts = 3
scheduler_topic = scheduler
scheduler_tracks_instance_changes = True
scheduler_weight_classes =
nova.scheduler.weights.all_weighers
secure_proxy_ssl_header = None
security_group_api = neutron
send_arp_for_ha = False
send_arp_for_ha_count = 3
service_down_time = 60
servicegroup_driver = db
share_dhcp_address = False
shelved_offload_time = 0
shelved_poll_interval = 3600
shutdown_timeout = 60
snapshot_name_template = snapshot-%s
ssl_ca_file = None
ssl_cert_file = None
ssl_key_file = None
state_path = /opt/stack/data/nova
sync_power_state_interval = 600
syslog-log-facility = LOG_USER
tcp_keepidle = 600
teardown_unused_network_gateway = False
tempdir = None
transport_url = None
until_refresh = 0
update_dns_entries = False
update_resources_interval = 0
use-syslog = False
use-syslog-rfc-format = True
use_cow_images = True
use_forwarded_for = False
use_ipv6 = False
use_network_dns_servers = False
use_neutron_default_nets = False
use_project_ca = False
use_rootwrap_daemon = False
use_single_default_gateway = False
use_stderr = True
user_cert_subject = /C=US/ST=California/O=OpenStack/OU=NovaDev/CN=%.16s-%.16s-%s
vcpu_pin_set = None
vendordata_driver = nova.api.metadata.vendordata_json.JsonFileVendorData
verbose = True
vif_plugging_is_fatal = True
vif_plugging_timeout = 300
virt_mkfs =
vlan_interface = None
vlan_start = 100
volume_api_class = nova.volume.cinder.API
volume_usage_poll_interval = 0
vpn_flavor = m1.tiny
vpn_image_id = 0
vpn_ip = 10.0.0.9
vpn_key_suffix = -vpn
vpn_start = 1000
wsgi_default_pool_size = 1000
wsgi_keep_alive = True
wsgi_log_format = %(client_ip)s "%(request_line)s" status: %(status_code)s len: %(body_length)s time: %(wall_seconds).7f ephemeral_storage_encryption:
cipher = aes-xts-plain64
enabled = False
key_size = 512 glance:
allowed_direct_url_schemes =
api_insecure = False
api_servers =
http://10.0.0.9:9292
host = 10.0.0.9
num_retries = 0
port = 9292
protocol = http guestfs:
debug = False image_file_url:
filesystems = ironic:
admin_auth_token = ***
admin_password = ***
admin_tenant_name = None
admin_url = None
admin_username = None
api_endpoint = None
api_max_retries = 60
api_retry_interval = 2
api_version = 1
client_log_level = None keymgr:
api_class = nova.keymgr.conf_key_mgr.ConfKeyManager keystone_authtoken:
admin_password = ***
admin_tenant_name = admin
admin_token = ***
admin_user = None
auth-url = http://10.0.0.9:35357
auth_admin_prefix =
auth_host = 127.0.0.1
auth_plugin = password
auth_port = 35357
auth_protocol = https
auth_section = None
www_authenticate_uri = http://10.0.0.9:5000
auth_version = None
cache = None
cafile = /opt/stack/data/ca-bundle.pem
certfile = None
check_revocations_for_cached = False
delay_auth_decision = False
domain-id = None
domain-name = None
enforce_token_bind = permissive
hash_algorithms =
md5
http_connect_timeout = None
http_request_max_retries = 3
identity_uri = None
include_service_catalog = True
insecure = False
keyfile = None
memcache_pool_conn_get_timeout = 10
memcache_pool_dead_retry = 300
memcache_pool_maxsize = 10
memcache_pool_socket_timeout = 3
memcache_pool_unused_timeout = 60
memcache_secret_key = ***
memcache_security_strategy = None
memcache_use_advanced_pool = False
memcached_servers = None
password = password
project-domain-id = default
project-domain-name = None
project-id = None
project-name = service
region_name = None
revocation_cache_time = 10
signing_dir = /var/cache/nova
tenant-id = None
tenant-name = None
token_cache_time = 300
trust-id = None
user-domain-id = default
user-domain-name = None
user-id = None
user-name = nova libvirt:
block_migration_flag = VIR_MIGRATE_UNDEFINE_SOURCE, VIR_MIGRATE_PEER2PEER, VIR_MIGRATE_LIVE, VIR_MIGRATE_TUNNELLED, VIR_MIGRATE_NON_SHARED_INC
checksum_base_images = False
checksum_interval_seconds = 3600
connection_uri =
cpu_mode = none
cpu_model = None
disk_cachemodes =
disk_prefix = None
gid_maps =
hw_disk_discard = None
hw_machine_type = None
image_info_filename_pattern = /opt/stack/data/nova/instances/_base/%(image)s.info
images_rbd_ceph_conf =
images_rbd_pool = rbd
images_type = default
images_volume_group = None
inject_key = False
inject_partition = -2
inject_password = False
iscsi_iface = None
iscsi_use_multipath = False
live_migration_bandwidth = 0
live_migration_completion_timeout = 800
live_migration_downtime = 500
live_migration_downtime_delay = 75
live_migration_downtime_steps = 10
live_migration_flag = VIR_MIGRATE_UNDEFINE_SOURCE, VIR_MIGRATE_PEER2PEER, VIR_MIGRATE_LIVE, VIR_MIGRATE_TUNNELLED
live_migration_progress_timeout = 150
live_migration_uri = qemu+ssh://stack@%s/system
mem_stats_period_seconds = 10
num_iscsi_scan_tries = 5
qemu_allowed_storage_drivers =
rbd_secret_uuid = None
rbd_user = None
remote_filesystem_transport = ssh
remove_unused_kernels = True
remove_unused_resized_minimum_age_seconds = 3600
rescue_image_id = None
rescue_kernel_id = None
rescue_ramdisk_id = None
rng_dev_path = None
snapshot_compression = False
snapshot_image_format = None
snapshots_directory = /opt/stack/data/nova/instances/snapshots
sparse_logical_volumes = False
sysinfo_serial = auto
uid_maps =
use_usb_tablet = False
use_virtio_for_bridges = True
virt_type = kvm
volume_clear = zero
volume_clear_size = 0
wait_soft_reboot_seconds = 120
xen_hvmloader_path = /usr/lib/xen/boot/hvmloader mks:
enabled = False
mksproxy_base_url = http://127.0.0.1:6090/ neutron:
admin_auth_url = http://10.0.0.9:35357/v2.0
admin_password = ***
admin_tenant_id = None
admin_tenant_name = service
admin_user_id = None
admin_username = neutron
auth_plugin = None
auth_section = None
auth_strategy = keystone
cafile = None
certfile = None
extension_sync_interval = 600
insecure = False
keyfile = None
metadata_proxy_shared_secret = ***
ovs_bridge = br-int
region_name = RegionOne
service_metadata_proxy = True
timeout = None
url = http://10.0.0.9:9696 osapi_v21:
enabled = True
extensions_blacklist =
extensions_whitelist = oslo_concurrency:
disable_process_locking = False
lock_path = /opt/stack/data/nova oslo_messaging_rabbit:
amqp_auto_delete = False
amqp_durable_queues = False
fake_rabbit = False
heartbeat_rate = 2
heartbeat_timeout_threshold = 60
kombu_reconnect_delay = 1.0
kombu_reconnect_timeout = 60
kombu_ssl_ca_certs =
kombu_ssl_certfile =
kombu_ssl_keyfile =
kombu_ssl_version =
rabbit_ha_queues = False
rabbit_host = localhost
rabbit_hosts =
10.0.0.9
rabbit_login_method = AMQPLAIN
rabbit_max_retries = 0
rabbit_password = ***
rabbit_port = 5672
rabbit_retry_backoff = 2
rabbit_retry_interval = 1
rabbit_use_ssl = False
rabbit_userid = stackrabbit
rabbit_virtual_host = /
rpc_conn_pool_size = 30
send_single_reply = False oslo_middleware:
max_request_body_size = 114688 oslo_versionedobjects:
fatal_exception_format_errors = False rdp:
enabled = False
html5_proxy_base_url = http://127.0.0.1:6083/ remote_debug:
host = None
port = None serial_console:
base_url = ws://127.0.0.1:6083/
enabled = False
listen = 127.0.0.1
port_range = 10000:20000
proxyclient_address = 127.0.0.1 spice:
agent_enabled = True
enabled = False
html5proxy_base_url = http://10.0.0.9:6082/spice_auto.html
keymap = en-us
server_listen = 127.0.0.1
server_proxyclient_address = 127.0.0.1 ssl:
ca_file = None
cert_file = None
key_file = None upgrade_levels:
baseapi = None
cells = None
cert = None
compute = None
conductor = None
console = None
consoleauth = None
network = None
scheduler = None vnc:
enabled = False
keymap = en-us
novncproxy_base_url = http://10.0.0.9:6080/vnc_auto.html
vncserver_listen = 127.0.0.1
vncserver_proxyclient_address = 127.0.0.1
xvpvncproxy_base_url = http://10.0.0.9:6081/console workarounds:
destroy_after_evacuate = True
disable_libvirt_livesnapshot = True
disable_rootwrap = False
handle_virt_lifecycle_events = True


CHANGES

3.6.0

  • add pyproject.toml to support pip 23.1
  • tox: Remove basepython
  • Update master for stable/2025.1

3.5.1

  • Skip installation to speed up pep8
  • reno: Update master for unmaintained/2023.1

3.5.0

  • Add note about requirements lower bounds
  • Remove Python 3.8 support
  • Run pyupgrade to clean up Python 2 syntaxes
  • Declare Python 3.12 support
  • Update master for stable/2024.2
  • Handle shell_completion option in test suite

3.4.0

  • Remove old excludes
  • Update master for stable/2024.1
  • reno: Update master for unmaintained/victoria

3.3.0

  • Remove logic for python 2 support
  • Update coverage commands
  • pre-commit: Integrate bandit
  • pre-commit: Bump versions
  • Make greenlet optional
  • Add missing direct imports
  • Bump hacking
  • Update python classifier in setup.cfg

3.2.0

  • Update master for stable/2023.2
  • GMR: Allow disabling signal handler

3.1.0

  • Imported Translations from Zanata
  • Bump bandit
  • Revert "Moves supported python runtimes from version 3.8 to 3.10"
  • Moves supported python runtimes from version 3.8 to 3.10
  • Update master for stable/2023.1

3.0.0

  • remove unicode prefix from code
  • remove unicode literal from code
  • Imported Translations from Zanata
  • Fix formatting of release list
  • Drop python3.6/3.7 support in testing runtime

2.4.0

  • Update CI to use unversioned jobs template
  • Support integer keys of dicts in text serialization
  • Changed minversion in tox to 3.18.0

2.3.0

  • Switch testing to Xena testing runtime
  • setup.cfg: Replace dashes with underscores
  • Move flake8 as a pre-commit local target
  • Remove lower-constraints remnants
  • Dropping lower constraints testing
  • Replace concatenation with f-strings
  • Use TOX_CONSTRAINTS_FILE
  • Use py3 as the default runtime for tox
  • Fix hacking min version to 3.0.1
  • Remove all six usage
  • Adding pre-commit
  • Add Python3 wallaby unit tests
  • Update master for stable/victoria

2.2.0

  • [goal] Migrate testing to ubuntu focal
  • Bump bandit version
  • Fix pygments style

2.1.0

  • Stop to use the __future__ module
  • Switch to newer openstackdocstheme and reno versions
  • Remove the unused coding style modules
  • Remove translation sections from setup.cfg
  • Align contributing doc with oslo's policy
  • Bump default tox env from py37 to py38
  • Add py38 package metadata
  • Add release notes links to doc index
  • Add Python3 victoria unit tests
  • Update master for stable/ussuri

2.0.1

  • Update hacking for Python3
  • Use unittest.mock instead of third party mock

2.0.0

  • remove outdated header
  • [ussuri][goal] Drop python 2.7 support and testing
  • tox: Trivial cleanup
  • trivial: Remove cruft from sphinx config file
  • tox: Add missing deps for 'releasenotes' job

1.31.1

  • Switch from 'collections' -> 'collections.abc'
  • Exclude tests from apidoc
  • tox: Keeping going with docs
  • Switch to Ussuri jobs
  • Update the constraints url

1.31.0

Update master for stable/train

1.30.0

  • Add Python 3 Train unit tests
  • Move doc related modules to doc/requirements.txt
  • Sync Sphinx requirement
  • Replace git.openstack.org URLs with opendev.org URLs
  • OpenDev Migration Patch
  • Update master for stable/stein

1.29.2

  • add python 3.7 unit test job
  • Update hacking version
  • Use template for lower-constraints
  • Update mailinglist from dev to discuss
  • Clean up .gitignore references to personal tools

1.29.1

  • Imported Translations from Zanata
  • add lib-forward-testing-python3 test job
  • add python 3.6 unit test job
  • import zuul job settings from project-config
  • Update unit test to reflect latest oslo.config
  • Update reno for stable/rocky
  • Switch to stestr
  • Add release notes link to README
  • fix tox python3 overrides
  • Remove the remaining of the removed option
  • Replace deprecated "auth_uri" by "www_authenticate_uri"
  • Remove stale pip-missing-reqs and pypy tox tests
  • Trivial: Update pypi url to new url

1.28.0

  • set default python to python3
  • fix lower constraints and uncap eventlet
  • Document workaround for AccessDenied error
  • add lower-constraints job
  • Updated from global requirements
  • Update links in README

1.27.0

  • Imported Translations from Zanata
  • Imported Translations from Zanata
  • Update reno for stable/queens
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

1.26.0

  • Updated from global requirements
  • Add bandit to pep8 job

1.25.0

  • Remove -U from pip install
  • Avoid tox_install.sh for constraints support
  • Updated from global requirements
  • Remove setting of version/release from releasenotes
  • Updated from global requirements
  • Updated from global requirements

1.24.0

  • Imported Translations from Zanata
  • Remove psutil 1.x compat wrapping
  • Updated from global requirements

1.23.0

  • Updated from global requirements
  • Update the documentation link
  • Remove SIGUSR1 handler, which was deprecated after Ocata
  • Updated from global requirements
  • Update reno for stable/pike
  • Updated from global requirements

1.22.0

  • Updated from global requirements
  • update the doc URL according to document migration

1.21.1

  • switch from oslosphinx to openstackdocstheme
  • rearrange content to fit the new standard layout

1.21.0

  • Updated from global requirements
  • Updated from global requirements
  • Remove pbr warnerrors in favor of sphinx check
  • Updated from global requirements

1.20.0

  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

1.19.0

  • Remove log translations
  • Updated from global requirements

1.18.0

  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Update reno for stable/ocata
  • Remove references to Python 3.4

1.17.0

  • Updated from global requirements
  • Updated from global requirements
  • Add Constraints support
  • Bump hacking dep
  • Show team and repo badges on README

1.16.0

  • Fix a typo
  • Updated from global requirements
  • Add reno for release notes management
  • Updated from global requirements
  • Updated from global requirements
  • Changed the home-page link

1.15.0

Updated from global requirements

1.14.0

Updated from global requirements

1.13.0

  • Updated from global requirements
  • Add Python 3.5 classifier and venv

1.12.0

  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

1.11.0

  • Use file modification events instead of signal handler
  • Imported Translations from Zanata

1.10.0

Updated from global requirements

1.9.0

Trivial: ignore openstack/common in flake8 exclude list

1.8.0

  • Remove direct dependency on babel
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

1.6.0

  • Updated from global requirements
  • Updated from global requirements

1.5.0

Updated from global requirements

1.4.0

  • Update translation setup
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements
  • Updated from global requirements

1.3.0

Updated from global requirements

1.2.0

  • Print the traceback if there was an exception in run()
  • Rename signal handler argument to 'frame'
  • Updated from global requirements
  • Updated from global requirements
  • Trival: Remove 'MANIFEST.in'

1.1.0

Drop python 2.6 support

1.0.0

  • Updated from global requirements
  • Remove Python 2.6 classifier
  • Updated from global requirements
  • Remove python 2.6 and cleanup tox.ini

0.8.0

  • Fix Transition to SIGUSR2 in oslo.reports breaks upgrade
  • Updated from global requirements
  • Updated from global requirements

0.7.0

  • Updated from global requirements
  • Fix a typo in process.py

0.6.0

  • remove extraneous coverage omit instruction
  • No need for Oslo Incubator Sync
  • Fix coverage configuration and execution
  • How to use oslo.reports documentation
  • add auto-generated api documentation
  • clean up release notes in toctree
  • add auto-generated docs for config options
  • Add shields.io version/downloads links/badges into README.rst
  • Updated from global requirements
  • guru_meditation_report: Use SIGUSR2 instead of SIGUSR1

0.5.0

  • Updated from global requirements
  • Updated from global requirements
  • Add a configuration for the directory to generate gmr
  • Fill README from information in the wiki
  • Updated from global requirements
  • Setup translations
  • Updated from global requirements

0.4.0

Updated from global requirements

0.3.0

  • Updated from global requirements
  • Fix mock of open() for mock 1.1.0
  • Fix GMR break with new psutil versions

0.2.0

  • Add oslo.utils dependency
  • Add tox target to find missing requirements

0.1.0

  • Updated from global requirements
  • Guru Meditation Reports broken without version_string
  • Fix intermittent test failures because of sort order
  • Graduation Prep: Use six.text_type instead of str
  • Graduation Prep: Initial Import Fixup
  • exported from oslo-incubator by graduate.sh
  • Remove timeutils.strtime() usage
  • Switch from oslo.config to oslo_config
  • Use oslo_utils instead of deprecated oslo.utils
  • Report: Add basic processes section
  • Change oslo.config to oslo_config
  • switch to oslo_serialization
  • Reports: Use sig handler traceback for curr thread
  • Report: Propagate view_type through collections
  • Report: Support Sequences and Mappings as Data
  • Use same mask pattern for reports as mask_password
  • Mask secrets when output conf
  • Delete graduated serialization files
  • Remove our custom test base class
  • Switch oslo-incubator to use oslo.utils and remove old modules
  • Fix tests.unit.reports.* with python3.4
  • Fix tests.unit.reports.test_base_report with python3.4
  • Set pbr 'warnerrors' option for doc build
  • fixed typos found by RETF rules
  • Report: Fix JinjaView deepcopy
  • Fixed several typos
  • Fix tests.unit.reports.test_guru_meditation_report under Python3
  • Use from/import style in module report
  • Fix tests.unit.reports.test_views failures under Python3
  • Add option for GM report to dump to a file
  • Removed unneeded #noqa tag
  • Fixes Guru Meditation portability issue
  • Fix typo in inline documentation for report module
  • Use six.StringIO/BytesIO instead of StringIO.StringIO
  • Rename Openstack to OpenStack
  • Avoid failure of test_basic_report on 32 bit OS
  • Fix filter() usage due to python 3 compability
  • Unify different names between Python2/3 with six.moves
  • Remove vim header
  • Use six.string_type instead of basestring
  • Fix typos in oslo
  • Adjust import order according to PEP8 imports rule
  • Replace assertEquals with assertEqual
  • Introduces The Guru Meditation Report
  • Introduces Openstack-Specific Report Utilities
  • Introduces Report Views
  • Introduces Basic Report and Model
  • initial commit
  • Initial skeleton project

Reference

Configuration Options

oslo.reports uses oslo.config to define and manage configuration options to allow the deployer to control where the GMR reports should be generated.

oslo_reports

log_dir
Type
string
Default
<None>

Path to a log directory where to create a file


file_event_handler
Type
string
Default
<None>

The path to a file to watch for changes to trigger the reports, instead of signals. Setting this option disables the signal trigger for the reports. If application is running as a WSGI application it is recommended to use this instead of signals.


file_event_handler_interval
Type
integer
Default
1

How many seconds to wait between polls when file_event_handler is set


API

oslo_reports

oslo_reports package

Subpackages

oslo_reports.generators package

Submodules

oslo_reports.generators.conf module

Provides OpenStack config generators

This module defines a class for configuration generators for generating the model in oslo_reports.models.conf.

class oslo_reports.generators.conf.ConfigReportGenerator(cnf=<oslo_config.cfg.ConfigOpts object>)
Bases: object

A Configuration Data Generator

This generator returns oslo_reports.models.conf.ConfigModel, by default using the configuration options stored in oslo_config.cfg.CONF, which is where OpenStack stores everything.

Parameters
cnf (oslo_config.cfg.ConfigOpts) -- the configuration option object


oslo_reports.generators.process module

Provides process-data generators

This modules defines a class for generating process data by way of the psutil package.

class oslo_reports.generators.process.ProcessReportGenerator
Bases: object

A Process Data Generator

This generator returns a oslo_reports.models.process.ProcessModel based on the current process (which will also include all subprocesses, recursively) using the psutil.Process class`.


oslo_reports.generators.threading module

Provides thread-related generators

This module defines classes for threading-related generators for generating the models in oslo_reports.models.threading.

class oslo_reports.generators.threading.GreenThreadReportGenerator
Bases: object

A Green Thread Data Generator

This generator returns a collection of oslo_reports.models.threading.GreenThreadModel objects by introspecting the current python garbage collection state, and sifting through for greenlet.greenlet objects.

SEE ALSO:

Function _find_objects()



class oslo_reports.generators.threading.ThreadReportGenerator(curr_thread_traceback=None)
Bases: object

A Thread Data Generator

This generator returns a collection of oslo_reports.models.threading.ThreadModel objects by introspecting the current python state using sys._current_frames() . Its constructor may optionally be passed a frame object. This frame object will be interpreted as the actual stack trace for the current thread, and, come generation time, will be used to replace the stack trace of the thread in which this code is running.


oslo_reports.generators.version module

Provides OpenStack version generators

This module defines a class for OpenStack version and package information generators for generating the model in oslo_reports.models.version.

class oslo_reports.generators.version.PackageReportGenerator(version_obj)
Bases: object

A Package Information Data Generator

This generator returns oslo_reports.models.version.PackageModel, extracting data from the given version object, which should follow the general format defined in Nova's version information (i.e. it should contain the methods vendor_string, product_string, and version_string_with_package).

Parameters
version_object -- the version information object


Module contents

Provides Data Model Generators

This module defines classes for generating data models ( oslo_reports.models.base.ReportModel ). A generator is any object which is callable with no parameters and returns a data model.

oslo_reports.models package

Submodules

oslo_reports.models.base module

Provides the base report model

This module defines a class representing the basic report data model from which all data models should inherit (or at least implement similar functionality). Data models store unserialized data generated by generators during the report serialization process.

class oslo_reports.models.base.ReportModel(data=None, attached_view=None)
Bases: MutableMapping

A Report Data Model

A report data model contains data generated by some generator method or class. Data may be read or written using dictionary-style access, and may be read (but not written) using object-member-style access. Additionally, a data model may have an associated view. This view is used to serialize the model when str() is called on the model. An appropriate object for a view is callable with a single parameter: the model to be serialized.

If present, the object passed in as data will be transformed into a standard python dict. For mappings, this is fairly straightforward. For sequences, the indices become keys and the items become values.

Parameters
  • data -- a sequence or mapping of data to associate with the model
  • attached_view -- a view object to attach to this model


set_current_view_type(tp, visited=None)
Set the current view type

This method attempts to set the current view type for this model and all submodels by calling itself recursively on all values, traversing intervening sequences and mappings when possible, and ignoring all other objects.

Parameters
  • tp -- the type of the view ('text', 'json', 'xml', etc)
  • visited -- a set of object ids for which the corresponding objects have already had their view type set




oslo_reports.models.conf module

Provides OpenStack Configuration Model

This module defines a class representing the data model for oslo_config configuration options

class oslo_reports.models.conf.ConfigModel(conf_obj)
Bases: ModelWithDefaultViews

A Configuration Options Model

This model holds data about a set of configuration options from oslo_config. It supports both the default group of options and named option groups.

Parameters
conf_obj (oslo_config.cfg.ConfigOpts) -- a configuration object


oslo_reports.models.process module

Provides a process model

This module defines a class representing a process, potentially with subprocesses.

class oslo_reports.models.process.ProcessModel(process)
Bases: ModelWithDefaultViews

A Process Model

This model holds data about a process, including references to any subprocesses

Parameters
process -- a psutil.Process object


oslo_reports.models.threading module

Provides threading and stack-trace models

This module defines classes representing thread, green thread, and stack trace data models

class oslo_reports.models.threading.GreenThreadModel(stack)
Bases: ModelWithDefaultViews

A Green Thread Model

This model holds data for information about an individual thread. Unlike the thread model, it holds just a stack trace, since green threads do not have thread ids.

SEE ALSO:

Class StackTraceModel


Parameters
stack -- the python stack state for the green thread


class oslo_reports.models.threading.StackTraceModel(stack_state)
Bases: ModelWithDefaultViews

A Stack Trace Model

This model holds data from a python stack trace, commonly extracted from running thread information

Parameters
stack_state -- the python stack_state object


class oslo_reports.models.threading.ThreadModel(thread_id, stack)
Bases: ModelWithDefaultViews

A Thread Model

This model holds data for information about an individual thread. It holds both a thread id, as well as a stack trace for the thread

SEE ALSO:

Class StackTraceModel


Parameters
  • thread_id (int) -- the id of the thread
  • stack -- the python stack state for the current thread



oslo_reports.models.version module

Provides OpenStack Version Info Model

This module defines a class representing the data model for OpenStack package and version information

class oslo_reports.models.version.PackageModel(vendor, product, version)
Bases: ModelWithDefaultViews

A Package Information Model

This model holds information about the current package. It contains vendor, product, and version information.

Parameters
  • vendor (str) -- the product vendor
  • product (str) -- the product name
  • version (str) -- the product version



oslo_reports.models.with_default_views module

class oslo_reports.models.with_default_views.ModelWithDefaultViews(*args, **kwargs)
Bases: ReportModel

A Model With Default Views of Various Types

A model with default views has several predefined views, each associated with a given type. This is often used for when a submodel should have an attached view, but the view differs depending on the serialization format

Parameters are as the superclass, except for any parameters ending in '_view': these parameters get stored as default views.

The default 'default views' are

text
oslo_reports.views.text.generic.KeyValueView
xml
oslo_reports.views.xml.generic.KeyValueView
json
oslo_reports.views.json.generic.KeyValueView

to_type()
('type' is one of the 'default views' defined for this model) Serializes this model using the default view for 'type'
Return type
str
Returns
this model serialized as 'type'


set_current_view_type(tp, visited=None)
Set the current view type

This method attempts to set the current view type for this model and all submodels by calling itself recursively on all values, traversing intervening sequences and mappings when possible, and ignoring all other objects.

Parameters
  • tp -- the type of the view ('text', 'json', 'xml', etc)
  • visited -- a set of object ids for which the corresponding objects have already had their view type set




Module contents

Provides data models

This module provides both the base data model, as well as several predefined specific data models to be used in reports.

oslo_reports.views package

Subpackages

oslo_reports.views.json package

Submodules

oslo_reports.views.json.generic module

Provides generic JSON views

This modules defines several basic views for serializing data to JSON. Submodels that have already been serialized as JSON may have their string values marked with __is_json__ = True using oslo_reports._utils.StringWithAttrs (each of the classes within this module does this automatically, and non-naive serializers check for this attribute and handle such strings specially)

class oslo_reports.views.json.generic.BasicKeyValueView
Bases: object

A Basic Key-Value JSON View

This view performs a naive serialization of a model into JSON by simply calling json.dumps() on the model


class oslo_reports.views.json.generic.KeyValueView
Bases: object

A Key-Value JSON View

This view performs advanced serialization to a model into JSON. It does so by first checking all values to see if they are marked as JSON. If so, they are deserialized using json.loads(). Then, the copy of the model with all JSON deserialized is reserialized into proper nested JSON using json.dumps().


Module contents

Provides basic JSON views

This module provides several basic views which serialize models into JSON.

oslo_reports.views.text package

Submodules

oslo_reports.views.text.generic module

Provides generic text views

This modules provides several generic views for serializing models into human-readable text.

class oslo_reports.views.text.generic.BasicKeyValueView
Bases: object

A Basic Key-Value Text View

This view performs a naive serialization of a model into text using a basic key-value method, where each key-value pair is rendered as "key = str(value)"


class oslo_reports.views.text.generic.KeyValueView(indent_str=' ', key_sep=' = ', dict_sep=' = ', list_sep=' = ', anon_dict='[dict]', before_dict=None, before_list=None)
Bases: object

A Key-Value Text View

This view performs an advanced serialization of a model into text by following the following set of rules:

key (text)
key = text
rootkey (Mapping)

rootkey =

serialize(key, value)


key (Sequence)

key =

serialize(item)



Parameters
  • indent_str (str) -- the string used to represent one "indent"
  • key_sep (str) -- the separator to use between keys and values
  • dict_sep (str) -- the separator to use after a dictionary root key
  • list_sep (str) -- the separator to use after a list root key
  • anon_dict (str) -- the "key" to use when there is a dict in a list (does not automatically use the dict separator)
  • before_dict (str or None) -- content to place on the line(s) before the a dict root key (use None to avoid inserting an extra line)
  • before_list (str or None) -- content to place on the line(s) before the a list root key (use None to avoid inserting an extra line)



class oslo_reports.views.text.generic.MultiView
Bases: object

A Text View Containing Multiple Views

This view simply serializes each value in the data model, and then joins them with newlines (ignoring the key values altogether). This is useful for serializing lists of models (as array-like dicts).


class oslo_reports.views.text.generic.TableView(column_names, column_values, table_prop_name)
Bases: object

A Basic Table Text View

This view performs serialization of data into a basic table with predefined column names and mappings. Column width is auto-calculated evenly, column values are automatically truncated accordingly. Values are centered in the columns.

Parameters
  • column_names ([str]) -- the headers for each of the columns
  • column_values ([str]) -- the item name to match each column to in each row
  • table_prop_name (str) -- the name of the property within the model containing the row models



oslo_reports.views.text.header module

Text Views With Headers

This package defines several text views with headers

class oslo_reports.views.text.header.HeaderView(header)
Bases: object

A Text View With a Header

This view simply serializes the model and places the given header on top.

Parameters
header -- the header (can be anything on which str() can be called)


class oslo_reports.views.text.header.TitledView(title)
Bases: HeaderView

A Text View With a Title

This view simply serializes the model, and places a preformatted header containing the given title text on top. The title text can be up to 64 characters long.

Parameters
title (str) -- the title of the view

FORMAT_STR = '========================================================================\n===={0: ^64}====\n========================================================================'


oslo_reports.views.text.process module

Provides process view

This module provides a view for visualizing processes in human-readable form

class oslo_reports.views.text.process.ProcessView(path=None, text=None)
Bases: JinjaView

A Process View

This view displays process models defined by oslo_reports.models.process.ProcessModel

VIEW_TEXT = "Process {{ pid }} (under {{ parent_pid }}) [ run by: {{ username }} ({{ uids.real|default('unknown uid') }}), state: {{ state }} ]\n{% for child in children %} {{ child }}{% endfor %}"


oslo_reports.views.text.threading module

Provides thread and stack-trace views

This module provides a collection of views for visualizing threads, green threads, and stack traces in human-readable form.

class oslo_reports.views.text.threading.GreenThreadView
Bases: object

A Green Thread View

This view displays a green thread provided by the data model oslo_reports.models.threading.GreenThreadModel

FORMAT_STR = '------{thread_str: ^60}------\n{stack_trace}'


class oslo_reports.views.text.threading.StackTraceView(path=None, text=None)
Bases: JinjaView

A Stack Trace View

This view displays stack trace models defined by oslo_reports.models.threading.StackTraceModel

VIEW_TEXT = '{% if root_exception is not none %}Exception: {{ root_exception }}\n------------------------------------\n\n{% endif %}{% for line in lines %}\n{{ line.filename }}:{{ line.line }} in {{ line.name }}\n {% if line.code is not none %}`{{ line.code }}`{% else %}(source not found){% endif %}\n{% else %}\nNo Traceback!\n{% endfor %}'


class oslo_reports.views.text.threading.ThreadView
Bases: object

A Thread Collection View

This view displays a python thread provided by the data model oslo_reports.models.threading.ThreadModel # noqa

FORMAT_STR = '------{thread_str: ^60}------\n{stack_trace}'


Module contents

Provides basic text views

This module provides several basic views which serialize models into human-readable text.

oslo_reports.views.xml package

Submodules

oslo_reports.views.xml.generic module

Provides generic XML views

This modules defines several basic views for serializing data to XML. Submodels that have already been serialized as XML may have their string values marked with __is_xml__ = True using oslo_reports._utils.StringWithAttrs (each of the classes within this module does this automatically, and non-naive serializers check for this attribute and handle such strings specially)

class oslo_reports.views.xml.generic.KeyValueView(wrapper_name='model')
Bases: object

A Key-Value XML View

This view performs advanced serialization of a data model into XML. It first deserializes any values marked as XML so that they can be properly reserialized later. It then follows the following rules to perform serialization:

key (text/xml)
The tag name is the key name, and the contents are the text or xml
key (Sequence)
A wrapper tag is created with the key name, and each item is placed in an 'item' tag
key (Mapping)
A wrapper tag is created with the key name, and the serialize is called on each key-value pair (such that each key gets its own tag)

Parameters
wrapper_name (str) -- the name of the top-level element


Module contents

Provides basic XML views

This module provides several basic views which serialize models into XML.

Submodules

oslo_reports.views.jinja_view module

Provides Jinja Views

This module provides views that utilize the Jinja templating system for serialization. For more information on Jinja, please see http://jinja.pocoo.org/ .

class oslo_reports.views.jinja_view.JinjaView(path=None, text=None)
Bases: object

A Jinja View

This view renders the given model using the provided Jinja template. The template can be given in various ways. If the VIEw_TEXT property is defined, that is used as template. Othewise, if a path parameter is passed to the constructor, that is used to load a file containing the template. If the path parameter is None, the text parameter is used as the template.

The leading newline character and trailing newline character are stripped from the template (provided they exist). Baseline indentation is also stripped from each line. The baseline indentation is determined by checking the indentation of the first line, after stripping off the leading newline (if any).

Parameters
  • path (str) -- the path to the Jinja template
  • text (str) -- the text of the Jinja template


property template
Get the Compiled Template

Gets the compiled template, using a cached copy if possible (stored in attr:_templatecache) or otherwise recompiling the template if the compiled template is not present or is invalid (due to attr:_regentemplate being set to True).

Returns
the compiled Jinja template
Return type
jinja2.Template


property text
Get the Template Text

Gets the text of the current template

Returns
the text of the Jinja template
Return type
str



Module contents

Provides predefined views

This module provides a collection of predefined views for use in reports. It is separated by type (xml, json, or text). Each type contains a submodule called 'generic' containing several basic, universal views for that type. There is also a predefined view that utilizes Jinja.

Submodules

oslo_reports.guru_meditation_report module

Provides Guru Meditation Report

This module defines the actual OpenStack Guru Meditation Report class.

This can be used in the OpenStack command definition files. For example, in a nova command module (under nova/cmd):

from oslo_config import cfg
from oslo_log import log as oslo_logging
from oslo_reports import opts as gmr_opts
from oslo_reports import guru_meditation_report as gmr
CONF = cfg.CONF
# maybe import some options here...
def main():

oslo_logging.register_options(CONF)
gmr_opts.set_defaults(CONF)
CONF(sys.argv[1:], default_config_files=['myapp.conf'])
oslo_logging.setup(CONF, 'myapp')
gmr.TextGuruMeditation.register_section('Some Special Section',
special_section_generator)
gmr.TextGuruMeditation.setup_autorun(version_object, conf=CONF)
server = service.Service.create(binary='some-service',
topic=CONF.some_service_topic)
service.serve(server)
service.wait()


Then, you can do

$ kill -USR2 $SERVICE_PID


and get a Guru Meditation Report in the file or terminal where stderr is logged for that given service.

class oslo_reports.guru_meditation_report.GuruMeditation(version_obj, sig_handler_tb=None, *args, **kwargs)
Bases: object

A Guru Meditation Report Mixin/Base Class

This class is a base class for Guru Meditation Reports. It provides facilities for registering sections and setting up functionality to auto-run the report on a certain signal or use file modification events.

This class should always be used in conjunction with a Report class via multiple inheritance. It should always come first in the class list to ensure the MRO is correct.

classmethod handle_signal(version, service_name, log_dir, frame)
The Signal Handler

This method (indirectly) handles receiving a registered signal and dumping the Guru Meditation Report to stderr or a file in a given dir. If service name and log dir are not None, the report will be dumped to a file named $service_name_gurumeditation_$current_time in the log_dir directory. This method is designed to be curried into a proper signal handler by currying out the version parameter.

Parameters
  • version -- the version object for the current product
  • service_name -- this program name used to construct logfile name
  • logdir -- path to a log directory where to create a file
  • frame -- the frame object provided to the signal handler



classmethod register_section(section_title, generator)
Register a New Section

This method registers a persistent section for the current class.

Parameters
  • section_title (str) -- the title of the section
  • generator -- the generator for the section



run()

classmethod setup_autorun(version, service_name=None, log_dir=None, signum=None, conf=None, setup_signal=True)
Set Up Auto-Run

This method sets up the Guru Meditation Report to automatically get dumped to stderr or a file in a given dir when the given signal is received. It can also use file modification events instead of signals.

Parameters
  • version -- the version object for the current product
  • service_name -- this program name used to construct logfile name
  • logdir -- path to a log directory where to create a file
  • signum -- the signal to associate with running the report
  • conf -- Configuration object, managed by the caller.
  • setup_signal -- Set up a signal handler



timestamp_fmt = '%Y%m%d%H%M%S'


class oslo_reports.guru_meditation_report.TextGuruMeditation(version_obj, traceback=None)
Bases: GuruMeditation, TextReport

A Text Guru Meditation Report

This report is the basic human-readable Guru Meditation Report

It contains the following sections by default (in addition to any registered persistent sections):

  • Package Information
  • Threads List
  • Green Threads List
  • Process List
  • Configuration Options

Parameters
  • version_obj -- the version object for the current product
  • traceback -- an (optional) frame object providing the actual traceback for the current thread



oslo_reports.opts module

oslo_reports.opts.list_opts()
Return a list of oslo.config options available in the library.

The returned list includes all oslo.config options which may be registered at runtime by the library. Each element of the list is a tuple. The first element is the name of the group under which the list of elements in the second element will be registered. A group name of None corresponds to the [DEFAULT] group in config files. This function is also discoverable via the 'oslo_messaging' entry point under the 'oslo.config.opts' namespace. The purpose of this is to allow tools like the Oslo sample config file generator to discover the options exposed to users by this library.

Returns
a list of (group_name, opts) tuples


oslo_reports.opts.set_defaults(conf)
Set defaults for configuration variables.

Overrides default options values.

Parameters
conf (oslo.config.cfg.ConfigOpts) -- Configuration object, managed by the caller.


oslo_reports.report module

Provides Report classes

This module defines various classes representing reports and report sections. All reports take the form of a report class containing various report sections.

class oslo_reports.report.BasicReport
Bases: object

A Basic Report

A Basic Report consists of a collection of ReportSection objects, each of which contains a top-level model and generator. It collects these sections into a cohesive report which may then be serialized by calling run().

add_section(view, generator, index=None)
Add a section to the report

This method adds a section with the given view and generator to the report. An index may be specified to insert the section at a given location in the list; If no index is specified, the section is appended to the list. The view is called on the model which results from the generator when the report is run. A generator is simply a method or callable object which takes no arguments and returns a oslo_reports.models.base.ReportModel or similar object.

Parameters
  • view -- the top-level view for the section
  • generator -- the method or class which generates the model
  • index (int or None) -- the index at which to insert the section (or None to append it)



run()
Run the report

This method runs the report, having each section generate its data and serialize itself before joining the sections together. The BasicReport accomplishes the joining by joining the serialized sections together with newlines.

Return type
str
Returns
the serialized report



class oslo_reports.report.ReportOfType(tp)
Bases: BasicReport

A Report of a Certain Type

A ReportOfType has a predefined type associated with it. This type is automatically propagated down to the each of the sections upon serialization by wrapping the generator for each section.

SEE ALSO:

Class oslo_reports.models.with_default_view.ModelWithDefaultView # noqa
(the entire class)
Class oslo_reports.models.base.ReportModel
oslo_reports.models.base.ReportModel.set_current_view_type() # noqa



Parameters
tp (str) -- the type of the report

add_section(view, generator, index=None)
Add a section to the report

This method adds a section with the given view and generator to the report. An index may be specified to insert the section at a given location in the list; If no index is specified, the section is appended to the list. The view is called on the model which results from the generator when the report is run. A generator is simply a method or callable object which takes no arguments and returns a oslo_reports.models.base.ReportModel or similar object.

Parameters
  • view -- the top-level view for the section
  • generator -- the method or class which generates the model
  • index (int or None) -- the index at which to insert the section (or None to append it)




class oslo_reports.report.ReportSection(view, generator)
Bases: object

A Report Section

A report section contains a generator and a top-level view. When something attempts to serialize the section by calling str() or unicode() on it, the section runs the generator and calls the view on the resulting model.

SEE ALSO:

Class BasicReport
BasicReport.add_section()



Parameters
  • view -- the top-level view for this section
  • generator -- the generator for this section (any callable object which takes no parameters and returns a data model)



class oslo_reports.report.TextReport(name)
Bases: ReportOfType

A Human-Readable Text Report

This class defines a report that is designed to be read by a human being. It has nice section headers, and a formatted title.

Parameters
name (str) -- the title of the report

add_section(heading, generator, index=None)
Add a section to the report

This method adds a section with the given title, and generator to the report. An index may be specified to insert the section at a given location in the list; If no index is specified, the section is appended to the list. The view is called on the model which results from the generator when the report is run. A generator is simply a method or callable object which takes no arguments and returns a oslo_reports.models.base.ReportModel or similar object.

The model is told to serialize as text (if possible) at serialization time by wrapping the generator. The view model's attached view (if any) is wrapped in a oslo_reports.views.text.header.TitledView

Parameters
  • heading (str) -- the title for the section
  • generator -- the method or class which generates the model
  • index (int or None) -- the index at which to insert the section (or None to append)




Module contents

Provides a way to generate serializable reports

This package/module provides mechanisms for defining reports which may then be serialized into various data types. Each report ( oslo_reports.report.BasicReport ) is composed of one or more report sections ( oslo_reports.report.BasicSection ), which contain generators which generate data models ( oslo_reports.models.base.ReportModels ), which are then serialized by views.

RELEASE NOTES

Read also the oslo.reports Release Notes.

INDICES AND TABLES

  • Index
  • Module Index
  • Search Page

AUTHOR

Author name not set

COPYRIGHT

2014, OpenStack Foundation

October 24, 2025 3.6.0