# openbmc/phosphor-logging architecture

> Architecture diagram of the GitHub repository openbmc/phosphor-logging, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openbmc/phosphor-logging
- Repository: https://github.com/openbmc/phosphor-logging

## Overview

##### Project Type and Purpose
- This is a system‐level, C++ logging library and daemon (“phosphor-log-manager”) within the OpenBMC ecosystem.
- It provides:
- A structured logging API (lg2::commit, elog, report) for applications.
- An event‐logging daemon exposing D-Bus interfaces.
- Code‐generation tools that produce C++ classes from YAML event definitions.
- Pluggable extensions (e.g., OpenPower PELs) and remote‐logging via rsyslog.

##### File‐Structure Analysis
- Top‐level executables & service
- log_create_main.cpp, log_manager_main.cpp, log_resolve_main.cpp
- phosphor-rsyslog-config/ – config tool for remote logging
- Core library
- lib/ – lg2 logger implementation, sdjournal integration
- callouts/ – YAML‐based callout generation scripts & templates
- Code generation
- gen/ – Meson build files, D-Bus interface stub generation from YAML
- yaml/ – Interface definitions for D-Bus objects
- Extensions
- extensions/openpower-pels/ – PEL formatting & registration callbacks
- Configuration and packaging
- config/, dist/ – Meson fragments, D-Bus service files, rsyslog defaults
- Tests
- test/, callouts/callout_test.cpp, test/openpower-pels/*
- Build & dependencies
- meson.build, meson.options, subprojects/ – wrapped dependencies (sdbusplus, nlohmann_json, etc.)

##### Key Components
a. Logging API (libphosphor-logging, lg2)
b. Phosphor‐Log‐Manager Daemon
c. sdbusplus / system D-Bus bus
d. systemd‐journal (sdjournal)
e. Code‐generation module (tools + gen directory)
f. Extensions subsystem (plugin directory + macros)
g. Remote logging client (rsyslog client config)
h. Consumer applications (any OpenBMC service using lg2::commit)
i. Configuration REST interface (settings service for remote logging, boot‐fail)

##### Relationships & Data Flows
- Consumer apps → call lg2::commit / elog() → writes metadata to systemd-journal → emits D-Bus signal/exception
- Phosphor‐Log‐Manager → listens on D-Bus for commit signals or Create() calls → reads journal metadata → creates D-Bus object under /xyz/openbmc_project/logging/entry/X
- Extensions → REGISTER_EXTENSION_FUNCTION hooks in the daemon → invoked on log create/delete events → may disable caps or write alternate logs (e.g., PELs)
- Rsyslog client → reads systemd-journal via journal-gateway or journal configuration → forwards to external rsyslog server
- Configuration REST calls → update D-Bus Settings interface → daemon picks up new remote server address/port
- Code generation (build time) → gen/* & tools/* → parse YAML → emit C++ headers & meson.build fragments

##### Architectural Patterns & Principles
- Plugin/extension framework (REGISTER_EXTENSION_FUNCTION, DISABLE_LOG_ENTRY_CAPS)
- Event‐driven, pub/sub via D-Bus and systemd‐journal
- Code‐generation for consistency and interface‐driven design (YAML → C++)
- Clear separation: API layer vs. daemon vs. extensions vs. transport (journal/D-Bus/rsyslog)

##### Technologies & Frameworks
- C++17, Meson build system
- sdbusplus for D-Bus IPC
- systemd-journal (sdjournal) for persistent event metadata
- Python scripts for codegen (elog-gen.py, callouts.py)
- YAML for D-Bus interface & error/event definitions
- JSON for event‐filter policies and rsyslog templates
- Rsyslog for remote streaming of journal entries

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-time Code Generation
    subgraph "Build-time Codegen" 
        direction TB
        CodeGen["Code-gen Module\n(tools/ gen/ yaml/)"]:::codegen
        JSONPolicy["Event-filter Policy\n(JSON input)"]:::external
    end

    %% Runtime Components
    subgraph "Run-time Flow"
        direction TB
        Consumer["Consumer Apps\n(call lg2::commit/elog)"]:::api
        API["Logging API\n(lib/)"]:::api
        Journal["systemd-journal\n(sdjournal)"]:::persist
        DBusSignal["D-Bus Signal\n(sdbusplus)"]:::bus
        Daemon["Phosphor-Log-Manager\nDaemon"]:::daemon
        DBusStore["D-Bus Object Store\n(/xyz/openbmc_project/logging/)"]:::persist
        Ext["Extensions Subsystem\n(OpenPower PELs)"]:::extension
        RsyslogAgent["Rsyslog Client\n(journal-gateway)"]:::external
        RemoteSrv["Remote Rsyslog Server"]:::external
        ConfigRest["Configuration REST\n(Settings D-Bus)"]:::config
    end

    %% Flow Arrows
    Consumer -->|"lg2::commit\nelog()"| API
    JSONPolicy -->|"policy check"| API
    API -->|"writes metadata"| Journal
    Journal -->|"JournalEntrySignal"| DBusSignal
    DBusSignal -->|"Create() calls"| Daemon
    Daemon -->|"Journal read"| Journal
    Daemon -->|"Create()/Delete()"| DBusStore
    Daemon -->|"REGISTER_EXTENSION_FUNCTION"| Ext
    Daemon -->|"settings update"| ConfigRest
    Daemon -->|"journal forward"| RsyslogAgent
    RsyslogAgent -->|"forward logs"| RemoteSrv

    %% Legend
    subgraph Legend
        direction TB
        A1["API Calls"]:::api
        A2["Daemon"]:::daemon
        A3["Extensions"]:::extension
        A4["Persistent Stores"]:::persist
        A5["D-Bus"]:::bus
        A6["Config"]:::config
        A7["Build-time"]:::codegen
        A8["External"]:::external
    end

    %% Click Events
    click API "https://github.com/openbmc/phosphor-logging/tree/master/lib/"
    click Daemon "https://github.com/openbmc/phosphor-logging/blob/master/log_manager_main.cpp"
    click DBusSignal "https://github.com/openbmc/phosphor-logging/blob/master/subprojects/sdbusplus.wrap"
    click Journal "https://github.com/openbmc/phosphor-logging/blob/master/lib/sdjournal.cpp"
    click CodeGen "https://github.com/openbmc/phosphor-logging/blob/master/tools/elog-gen.py"
    click Ext "https://github.com/openbmc/phosphor-logging/tree/master/extensions/openpower-pels/"
    click RsyslogAgent "https://github.com/openbmc/phosphor-logging/tree/master/phosphor-rsyslog-config/"
    click Consumer "https://github.com/openbmc/phosphor-logging/blob/master/callouts/callouts.py"
    click ConfigRest "https://github.com/openbmc/phosphor-logging/blob/master/config/config.h.meson"

    %% Styles
    classDef api fill:#D6EAF8,stroke:#2E86C1,color:#1B4F72
    classDef daemon fill:#D4EFDF,stroke:#27AE60,color:#145A32
    classDef extension fill:#FCF3CF,stroke:#F1C40F,color:#7D6608
    classDef persist fill:#E8DAEF,stroke:#8E44AD,color:#512E5F
    classDef bus fill:#FADBD8,stroke:#E74C3C,color:#641E16
    classDef config fill:#F2D7D5,stroke:#CD6155,color:#641E16
    classDef codegen fill:#EBEDEF,stroke:#7B7D7D,color:#2C3E50,stroke-dasharray: 5 5
    classDef external fill:#FEF9E7,stroke:#F39C12,color:#B9770E
```
