Fill in README section on D-Bus event creation
Describe the new xyz.openbmc_project.Logging.Create API that
can be used to create event logs.
Signed-off-by: Matt Spinler <spinler@us.ibm.com>
Change-Id: Iaa02e4a6abeb7ce929577b47ab0e518a9ce00638
diff --git a/README.md b/README.md
index e7178ec..8e4ab28 100644
--- a/README.md
+++ b/README.md
@@ -223,7 +223,55 @@
for an example.
#### D-Bus Event Log Creation
-**TODO**
+There is also a [D-Bus method][log-create-link] to create event logs:
+* Service: xyz.openbmc_project.Logging
+* Object Path: /xyz/openbmc_project/logging
+* Interface: xyz.openbmc_project.Logging.Create
+* Method: Create
+ * Method Arguments:
+ * Message: The `Message` string property for the
+ `xyz.openbmc_project.Logging.Entry` interface.
+ * Severity: The `severity` property for the
+ `xyz.openbmc_project.Logging.Entry` interface.
+ An `xyz.openbmc_project.Logging.Entry.Level` enum value.
+ * AdditionalData: The `AdditionalData` property for the
+ `xyz.openbmc_project.Logging.Entry` interface, but in a map
+ instead of in a vector of "KEY=VALUE" strings.
+ Example:
+```
+ std::map<std::string, std::string> additionalData;
+ additionalData["KEY"] = "VALUE";
+```
+
+
+Unlike the previous APIs where errors could also act as exceptions that could
+be thrown across D-Bus, this API does not require that the error be defined in
+the error YAML in the D-Bus interfaces repository so that sdbusplus knows about
+it. Additionally, as this method passes in everything needed to create the
+event log, the logging daemon doesn't have to know about it ahead of time
+either.
+
+That being said, it is recommended that users of this API still follow some
+guidelines for the message field, which is normally generated from a
+combination of the path to the error YAML file and the error name itself. For
+example, the `Timeout` error in `xyz/openbmc_project/Common.errors.yaml` will
+have a Message property of `xyz.openbmc_project.Common.Error.Timeout`.
+
+The guidelines are:
+1. When it makes sense, one can still use an existing error that has already
+ been defined in an error YAML file, and use the same severity and metadata
+ (AdditionalData) as in the corresponding metadata YAML file.
+
+2. If creating a new error, use the same naming scheme as other errors, which
+ starts with the domain, `xyz.openbmc_project`, `org.open_power`, etc,
+ followed by the capitalized category values, followed by `Error`, followed
+ by the capitalized error name itself, with everything separated by "."s.
+ For example: `xyz.openbmc_project.Some.Category.Error.Name`.
+
+3. If creating a new common error, still add it to the appropriate error and
+ metadata YAML files in the appropriate D-Bus interfaces repository so that
+ others can know about it and use it in the future. This can be done after
+ the fact.
[xyz.openbmc_project.Logging.Entry]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Logging/Entry.interface.yaml
[xyz.openbmc_project.Association.Definitions]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Association/Definitions.interface.yaml
@@ -234,6 +282,7 @@
[elog-errors.hpp]: https://github.com/openbmc/phosphor-logging/blob/master/phosphor-logging/elog.hpp
[openpower-occ-control]: https://github.com/openbmc/openpower-occ-control
[led-link]: https://github.com/openbmc/openbmc/tree/master/meta-phosphor/recipes-phosphor/leds
+[log-create-link]: https://github.com/openbmc/phosphor-dbus-interfaces/blob/master/xyz/openbmc_project/Logging/Create.interface.yaml
## Adding application specific error YAML
* This document captures steps for adding application specific error YAML files