1# phosphor-logging 2phosphor logging provides mechanism for common event and logging creation based 3on information from the journal log. 4 5## To Build 6``` 7To build this package, do the following steps: 8 9 1. ./bootstrap.sh 10 2. ./configure ${CONFIGURE_FLAGS} 11 3. make 12 13To clean the repository run `./bootstrap.sh clean`. 14``` 15 16## Remote Logging via Rsyslog 17The BMC has the ability to stream out local logs (that go to the systemd journal) 18via rsyslog (https://www.rsyslog.com/). 19 20The BMC will send everything. Any kind of filtering and appropriate storage 21will have to be managed on the rsyslog server. Various examples are available 22on the internet. Here are few pointers : 23https://www.rsyslog.com/storing-and-forwarding-remote-messages/ 24https://www.rsyslog.com/doc/rsyslog%255Fconf%255Ffilter.html 25https://www.thegeekdiary.com/understanding-rsyslog-filter-options/ 26 27#### Configuring rsyslog server for remote logging 28The BMC is an rsyslog client. To stream out logs, it needs to talk to an rsyslog 29server, to which there's connectivity over a network. REST API can be used to 30set the remote server's IP address and port number. 31 32The following presumes a user has logged on to the BMC (see 33https://github.com/openbmc/docs/blob/master/rest-api.md). 34 35Set the IP: 36``` 37curl -b cjar -k -H "Content-Type: application/json" -X PUT \ 38 -d '{"data": <IP address>}' \ 39 https://<BMC IP address>/xyz/openbmc_project/logging/config/remote/attr/Address 40``` 41 42Set the port: 43``` 44curl -b cjar -k -H "Content-Type: application/json" -X PUT \ 45 -d '{"data": <port number>}' \ 46 https://<BMC IP address>/xyz/openbmc_project/logging/config/remote/attr/Port 47``` 48 49#### Querying the current configuration 50``` 51curl -b cjar -k \ 52 https://<BMC IP address>/xyz/openbmc_project/logging/config/remote 53``` 54 55#### Setting the hostname 56Rsyslog can store logs separately for each host. For this reason, it's useful to 57provide a unique hostname to each managed BMC. Here's how that can be done via a 58REST API : 59``` 60curl -b cjar -k -H "Content-Type: application/json" -X PUT \ 61 -d '{"data": "myHostName"}' \ 62 https://<BMC IP address>//xyz/openbmc_project/network/config/attr/HostName 63``` 64 65#### Disabling remote logging 66Remote logging can be disabled by writing 0 to the port, or an empty string("") 67to the IP. 68 69#### Changing the rsyslog server 70When switching to a new server from an existing one (i.e the address, or port, 71or both change), it is recommended to disable the existing configuration first. 72 73 74## Adding application specific error YAML 75* This document captures steps for adding application specific error YAML files 76 and generating local elog-errors.hpp header file for application use. 77* Should cater for continuous integration (CI) build, bitbake image build, and 78 local repository build. 79 80#### Continuous Integration (CI) build 81 * Make is called on the repository that is modified. 82 * Dependent packages are pulled based on the dependency list specified in the 83 configure.ac script. 84 85#### Recipe build 86 * Native recipes copy error YAML files to shared location. 87 * phosphor-logging builds elog-errors.hpp by parsing the error YAML files from 88 the shared location. 89 90#### Local repository build 91 * Copies local error YAML files to the shared location in SDK 92 * Make generates elog-errors.hpp by parsing the error YAML files from the 93 shared location. 94 95#### Makefile changes 96**Reference** 97 * https://github.com/openbmc/openpower-debug-collector/blob/master/Makefile.am 98 99###### Export error YAML to shared location 100*Modify Makefile.am to export newly added error YAML to shared location* 101``` 102yamldir = ${datadir}/phosphor-dbus-yaml/yaml 103nobase_yaml_DATA = \ 104 org/open_power/Host.errors.yaml 105``` 106 107###### Generate elog-errors.hpp using elog parser from SDK location 108 * Add a conditional check "GEN_ERRORS" 109 * Disable the check for recipe bitbake image build 110 * Enable it for local repository build 111 * If "GEN_ERRORS" is enabled, build generates elog-errors.hpp header file. 112``` 113 # Generate phosphor-logging/elog-errors.hpp 114 if GEN_ERRORS 115 ELOG_MAKO ?= elog-gen-template.mako.hpp 116 ELOG_DIR ?= ${OECORE_NATIVE_SYSROOT}${datadir}/phosphor-logging/elog 117 ELOG_GEN_DIR ?= ${ELOG_DIR}/tools/ 118 ELOG_MAKO_DIR ?= ${ELOG_DIR}/tools/phosphor-logging/templates/ 119 YAML_DIR ?= ${OECORE_NATIVE_SYSROOT}${datadir}/phosphor-dbus-yaml/yaml 120 phosphor-logging/elog-errors.hpp: 121 @mkdir -p ${YAML_DIR}/org/open_power/ 122 @cp ${top_srcdir}/org/open_power/Host.errors.yaml \ 123 ${YAML_DIR}/org/open_power/Host.errors.yaml 124 @mkdir -p `dirname $@` 125 @chmod 777 $(ELOG_GEN_DIR)/elog-gen.py 126 $(AM_V_at)$(PYTHON) $(ELOG_GEN_DIR)/elog-gen.py -y ${YAML_DIR} \ 127 -t ${ELOG_MAKO_DIR} -m ${ELOG_MAKO} -o $@ 128 endif 129``` 130 131###### Update BUILT_SOURCES 132 * Append elog-errors.hpp to BUILT_SOURCES list and put it in conditional check 133 GEN_ERRORS so that the elog-errors.hpp is generated only during local 134 repository build. 135``` 136 if GEN_ERRORS 137 nobase_nodist_include_HEADERS += \ 138 phosphor-logging/elog-errors.hpp 139 endif 140 if GEN_ERRORS 141 BUILT_SOURCES += phosphor-logging/elog-errors.hpp 142 endif 143``` 144 145###### Conditional check for native build 146 * As the same Makefile is used both for recipe image build and native recipe 147 build, add a conditional to ensure that only installation of error yaml files 148 happens during native build. It is not required to build repository during 149 native build. 150``` 151 if !INSTALL_ERROR_YAML 152 endif 153``` 154 155#### Autotools changes 156**Reference** 157 * https://github.com/openbmc/openpower-debug-collector/blob/master/configure.ac 158 159###### Add option(argument) to enable/disable installing error yaml file 160 * Install error yaml option(argument) is enabled for native recipe build 161 and disabled for bitbake build. 162 163 * When install error yaml option is disabled do not check for target specific 164 packages in autotools configure script. 165 166###### Add option(argument) to install error yaml files 167``` 168AC_ARG_ENABLE([install_error_yaml], 169 AS_HELP_STRING([--enable-install_error_yaml], 170 [Enable installing error yaml file]),[], [install_error_yaml=no]) 171AM_CONDITIONAL([INSTALL_ERROR_YAML], 172 [test "x$enable_install_error_yaml" = "xyes"]) 173AS_IF([test "x$enable_install_error_yaml" != "xyes"], [ 174.. 175.. 176]) 177``` 178 179###### Add option(argument) to enable/disable generating elog-errors header file 180``` 181AC_ARG_ENABLE([gen_errors], 182 AS_HELP_STRING([--enable-gen_errors], [Enable elog-errors.hpp generation ]), 183 [],[gen_errors=yes]) 184AM_CONDITIONAL([GEN_ERRORS], [test "x$enable_gen_errors" != "xno"]) 185``` 186 187#### Recipe changes 188**Reference** 189* https://github.com/openbmc/openbmc/blob/master/meta-openbmc-machines\ 190/meta-openpower/common/recipes-phosphor/debug/openpower-debug-collector.bb 191 192###### Extend recipe for native and nativesdk 193* Extend the recipe for native and native SDK builds 194``` 195BBCLASSEXTEND += "native nativesdk" 196``` 197###### Remove dependencies for native and native SDK build 198* Native recipe caters only for copying error yaml files to shared location. 199* For native and native SDK build remove dependency on packages that recipe 200 build depends 201 202###### Remove dependency on phosphor-logging for native build 203``` 204DEPENDS_remove_class-native = "phosphor-logging" 205``` 206 207###### Remove dependency on phosphor-logging for native SDK build 208``` 209DEPENDS_remove_class-nativesdk = "phosphor-logging" 210``` 211 212###### Add install_error_yaml argument during native build 213* Add package config to enable/disable install_error_yaml feature. 214 215###### Add package config to enable/disable install_error_yaml feature 216``` 217PACKAGECONFIG ??= "install_error_yaml" 218PACKAGECONFIG[install_error_yaml] = " \ 219 --enable-install_error_yaml, \ 220 --disable-install_error_yaml, ,\ 221 " 222``` 223###### Enable install_error_yaml check for native build 224``` 225PACKAGECONFIG_add_class-native = "install_error_yaml" 226PACKAGECONFIG_add_class-nativesdk = "install_error_yaml" 227``` 228###### Disable install_error_yaml during target build 229``` 230PACKAGECONFIG_remove_class-target = "install_error_yaml" 231``` 232 233###### Disable generating elog-errors.hpp for bitbake build 234* Disable gen_errors argument for bitbake image build as the application uses 235 the elog-errors.hpp generated by phosphor-logging 236* Argument is enabled by default for local repository build in the configure 237 script of the local repository. 238``` 239 XTRA_OECONF += "--disable-gen_errors" 240``` 241 242#### Local build 243* During local build use --prefix=/usr for the configure script. 244 245**Reference** 246* https://github.com/openbmc/openpower-debug-collector/blob/master/README.md 247