{"id":18368624,"url":"https://github.com/openbmc/phosphor-hostlogger","last_synced_at":"2025-04-06T17:31:45.567Z","repository":{"id":49254250,"uuid":"155840762","full_name":"openbmc/phosphor-hostlogger","owner":"openbmc","description":"Host Logging service","archived":false,"fork":false,"pushed_at":"2025-02-03T19:08:02.000Z","size":290,"stargazers_count":2,"open_issues_count":0,"forks_count":2,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-03-22T04:02:00.217Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openbmc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-02T09:05:22.000Z","updated_at":"2025-02-03T19:08:06.000Z","dependencies_parsed_at":"2023-01-25T21:31:37.927Z","dependency_job_id":"f51be63d-5384-4037-b944-a74565a628c0","html_url":"https://github.com/openbmc/phosphor-hostlogger","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-hostlogger","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-hostlogger/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-hostlogger/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openbmc%2Fphosphor-hostlogger/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openbmc","download_url":"https://codeload.github.com/openbmc/phosphor-hostlogger/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247522374,"owners_count":20952534,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-05T23:26:45.911Z","updated_at":"2025-04-06T17:31:45.013Z","avatar_url":"https://github.com/openbmc.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Host Logger\n\nThe main purpose of the Host Logger project is to handle and store host's\nconsole output data, such as boot logs or Linux kernel messages printed to the\nsystem console.\n\nThere are two modes in Host Logger.\n\nBuffer mode: host logs are stored in a temporary buffer and flushed to a file\naccording to the policy that can be defined with service parameters. It gives\nthe ability to save the startup logs and shutdown logs in separate files.\n\nStream mode: host logs are forwarded into a server socket (e.g. a socket created\nby the rsyslog imuxsock module). It gives the ability to stream logs in almost\nrealtime.\n\n## Architecture\n\nHost Logger is a standalone service (daemon) that works on top of the\nobmc-console and uses its UNIX domain socket to read the console output.\n\n### The Buffer Mode\n\n```text\n+-------------+                                       +----------------+\n|    Host     | State  +---------------------+ Event  |   Host Logger  |\n|             |-------\u003e|        D-Bus        |-------\u003e|                |\n|             |        +---------------------+        | +------------+ |\n|             |                                  D +---\u003e| Log buffer | |\n|             |        +---------------------+   a |  | +------+-----+ |\n|             |        | obmc-console-server |   t |  |        V       |\n| +---------+ |  Data  |   +-------------+   |   a |  | +------------+ |\n| | console |---------\u003e|   | UNIX socket |---------+  | |  Log file  | |\n| +---------+ |        |   +-------------+   |        | +------------+ |\n+-------------+        +---------------------+        +----------------+\n```\n\nUnlike the obmc-console project, where console output is a binary byte stream,\nthe service in buffer mode interprets this stream: splits it into separate\nmessages, adds a time stamp and pushes the message into an internal buffer.\nMaximum size of the buffer and flush conditions are controlled by service\nparameters.\n\n### The Stream Mode\n\n```text\n+-----------+                               +-------------+      +------------+\n|           |                               |             |      |            |\n|   Host    |                               | Host Logger |      |  rsyslog   |\n|           |                               |             |      | +--------+ |  +---------+\n|           |                               |             |      | | omfile -----\u003eLog Files|--+\n|           |   +--------------------+      |             |      | +--------+ |  +---------+  |\n|           |   |obmc-console-server |      |             |      |            |  +------------v---+\n|+---------+|   |   +-------------+  |Stream|+-----------+|DGRAM | +--------+ |  | Redfish        |\n|| console -----|--\u003e| UNIX socket |----------\u003e  Service  ---------\u003e|imuxsock| |  | LogService \u0026   |\n|+---------+|   |   +-------------+  |      |+-----------+|      | +--------+ |  | EventService   |\n+-----------+   +--------------------+      +-------------+      +------------+  +----------------+\n```\n\nThe service in stream mode forwards the byte stream into rsyslog via the\nimuxsock module. The log is persisted via the omfile module as soon as\ncollected. It makes Host Logger leverage existing tools (rsyslog and logrotate).\nIt also fits in the Redfish LogService and EventService architecture in OpenBMC.\n\n## Log buffer rotation policy\n\n### The Buffer Mode\n\nMaximum buffer size can be defined in the service configuration using two ways:\n\n- Limits by size: buffer will store the last N messages, the oldest messages are\n  removed. Controlled by `BUF_MAXSIZE` option.\n- Limits by time: buffer will store messages for the last N minutes, oldest\n  messages are removed. Controlled by `BUF_MAXTIME` option.\n\nAny of these parameters can be combined.\n\n### The Stream Mode\n\nRotation and compression are handled by the\n[logrotate](https://linux.die.net/man/8/logrotate) tool.\n\n## Log buffer flush policy\n\n### The Buffer Mode\n\nMessages from the buffer will be written to a file when one of the following\nevents occurs:\n\n- Host changes its state (start, reboot or shut down). The service watches the\n  state via the D-Bus object specified in `HOST_STATE` parameter.\n- Size of the buffer reaches its limits controlled by `BUF_MAXSIZE` and\n  `BUF_MAXTIME` parameters, this mode can be activated by `FLUSH_FULL` flag.\n- Signal `SIGUSR1` is received (manual flush).\n\n### The Stream Mode\n\nLogs are flushed as soon as they are collected.\n\n## Configuration\n\nConfiguration of the service is loaded from environment variables, so each\ninstance of the service can have its own set of parameters. Environment files\nare stored in the directory `/etc/hostlogger` and must have the extension\n`conf`. The file name is the name of the associated Host logger instance and the\ninstance of the obmc-console service (e.g. `ttyVUART0`).\n\n### Environment variables\n\nAny of these variables can be omitted, in which cases default values are used.\nIf variable's value has an invalid format, the service fails with an error.\n\n- `SOCKET_ID`: Socket Id used for connection with the host console. This Id\n  shall match the \"socket-id\" parameter of obmc-console server. The default\n  value is empty (single-host mode).\n- `MODE`: The mode that the service is running in. Possible values: `buffer` or\n  `stream`. The default value is `buffer`.\n\n#### The Buffer Mode\n\n- `BUF_MAXSIZE`: Max number of stored messages in the buffer. The default value\n  is `3000` (0=unlimited).\n\n- `BUF_MAXTIME`: Max age of stored messages in minutes. The default value is `0`\n  (unlimited).\n\n- `FLUSH_FULL`: Flush collected messages from buffer to a file when one of the\n  buffer limits reaches a threshold value. At least one of `BUF_MAXSIZE` or\n  `BUF_MAXTIME` must be defined. Possible values: `true` or `false`. The default\n  value is `false`.\n\n- `HOST_STATE`: Flush collected messages from buffer to a file when the host\n  changes its state. This variable must contain a valid path to the D-Bus object\n  that provides host's state information. Object shall implement interfaces\n  `xyz.openbmc_project.State.Host` and\n  `xyz.openbmc_project.State.OperatingSystem.Status`. The default value is\n  `/xyz/openbmc_project/state/host0`.\n\n- `OUT_DIR`: Absolute path to the output directory for log files. The default\n  value is `/var/lib/obmc/hostlogs`.\n\n- `MAX_FILES`: Log files rotation, max number of files in the output directory,\n  oldest files are removed. The default value is `10` (0=unlimited).\n\n#### The Stream Mode\n\n- `STREAM_DST`: Absolute path to the output unix socket. The default value is\n  `/run/rsyslog/console_input`.\n\n### Example\n\n#### Remove file limits\n\nRelevant for OpenPOWER based servers, using `ttyVUART0` for console.\n\nFile `phosphor-hostlogger_%.bbappend`:\n\n```bitbake\nFILESEXTRAPATHS:prepend := \"${THISDIR}/${PN}:\"\nSRC_URI:append = \" file://ttyVUART0.conf\"\n```\n\nFile `phosphor-hostlogger/ttyVUART0.conf`:\n\n```sh\nMAX_FILES=0\n```\n\n#### Custom object for host state monitoring\n\nRelevant for x86 based servers: using `ttyS2` for console and\n`/xyz/openbmc_project/state/os` for host state monitoring.\n\nFile `phosphor-hostlogger_%.bbappend`:\n\n```bitbake\nFILESEXTRAPATHS:prepend := \"${THISDIR}/${PN}:\"\nSRC_URI:append = \" file://ttyS2.conf\"\n```\n\nFile `phosphor-hostlogger/ttyS2.conf`:\n\n```sh\nHOST_STATE=/xyz/openbmc_project/state/os\n```\n\n## Multi-host support\n\nThe single instance of the service can handle only one host console at a time.\nIf OpenBMC has multiple hosts, the console of each host must be associated with\nits own instance of the Host Logger service. This can be achieved using the\nsystemd unit template.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenbmc%2Fphosphor-hostlogger","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenbmc%2Fphosphor-hostlogger","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenbmc%2Fphosphor-hostlogger/lists"}